openapi: 3.0.2
info:
  title: Fyno Rest Fire an Event API
  version: v1
servers:
- url: https://api.fyno.io/v1
security:
- BearerAuth: []
tags:
- name: Fire an Event
paths:
  /{WSID}/{version}/event:
    post:
      tags:
      - Fire an Event
      summary: Notify a single user
      description: This API enables you to fire a notification event, which sends out notifications to your users. <br/><br/>Before firing your first notification event, you must perform the following actions in your Fyno account:<br/>- Create a Template<br/>- Create a Notification Event<br/>- Create an API Key<br/>- And obtain your workspace ID from the API Keys page.
      parameters:
      - name: WSID
        in: path
        description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: FYXXXXXXXX
      - name: version
        in: path
        description: Enter the version for which you wish to fire the notification.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          default: live
          enum:
          - live
          - test
      requestBody:
        description: Your event payload must specify at least *`distinct_id`* or *`to`* while firing a notification event.<br/><br/>If the payload contains&#58;<br/><br/>- <b>Option 1&#58;</b> ONLY *`to`* (and no *`distinct_id`*) - the notification event uses all destination values from the *`to`* object (as it is).<br/><br/>- <b>Option 2&#58;</b> ONLY *`distinct_id`* (and no *`to`*) - the notificaton event uses all destination values (such as SMS, WhatsApp, Email, Push, Voice and so on) from the user's profile and sends the notification.<br/><br/>- <b>Option 3&#58;</b> BOTH *`distinct_id`* and *`to`* - the `to` and `distinct_id` channel data merges (`to` object take precedences) and sends the notification. The sent notification is tagged to the ID specified, which can be then used to search the logs by using `distinct_id`.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/version_event_body'
        required: true
      responses:
        '202':
          $ref: '#/components/responses/EventRequestAccepted'
        '400':
          $ref: '#/components/responses/EventNameDoesNotExist'
        '401':
          $ref: '#/components/responses/APIKeyInvalid'
  /{WSID}/{version}/event/bulk:
    post:
      tags:
      - Fire an Event
      summary: Notify multiple users
      description: This API enables you to notify multiple users with one event trigger.<br/><br/>Before firing your first notification event, you must perform the following actions in your Fyno account:<br/>- Create a Template<br/>- Create an Event<br/>- Create an API Key<br/>- And obtain your workspace ID from the API Keys page.
      parameters:
      - name: WSID
        in: path
        description: Enter your workspace ID. You can obtain this value from the API Keys page within your Fyno account.
        required: true
        style: simple
        explode: false
        schema:
          type: string
        example: FYXXXXXXXX
      - name: version
        in: path
        description: Enter the version for which you wish to fire the notification.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          default: live
          enum:
          - live
          - test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/event_bulk_body'
        required: true
      responses:
        '202':
          $ref: '#/components/responses/BulkEventRequestAccepted'
        '400':
          $ref: '#/components/responses/EventNameDoesNotExist'
        '401':
          $ref: '#/components/responses/APIKeyInvalid'
components:
  schemas:
    distinct_id:
      description: Enter the distinct ID that you use to identify the recipient.
      example: XXXXXXXX
      type: string
    inline_response_202_response:
      properties:
        discord:
          $ref: '#/components/schemas/inline_response_202_response_discord'
        email:
          $ref: '#/components/schemas/inline_response_202_response_email'
        inapp:
          $ref: '#/components/schemas/inline_response_202_response_inapp'
        push:
          $ref: '#/components/schemas/inline_response_202_response_push'
        slack:
          $ref: '#/components/schemas/inline_response_202_response_slack'
        sms:
          $ref: '#/components/schemas/inline_response_202_response_sms'
        teams:
          $ref: '#/components/schemas/inline_response_202_response_teams'
        voice:
          $ref: '#/components/schemas/inline_response_202_response_sms'
        whatsapp:
          $ref: '#/components/schemas/inline_response_202_response_sms'
      type: object
    version_event_body:
      oneOf:
      - properties:
          callback:
            $ref: '#/components/schemas/callback'
          data:
            $ref: '#/components/schemas/data'
          event:
            $ref: '#/components/schemas/event'
          to:
            $ref: '#/components/schemas/to'
        required:
        - event
        - to
        type: object
      - properties:
          callback:
            $ref: '#/components/schemas/callback'
          data:
            $ref: '#/components/schemas/data'
          distinct_id:
            $ref: '#/components/schemas/distinct_id'
          event:
            $ref: '#/components/schemas/event'
        required:
        - distinct_id
        - event
        type: object
      - properties:
          callback:
            $ref: '#/components/schemas/callback'
          data:
            $ref: '#/components/schemas/data'
          distinct_id:
            $ref: '#/components/schemas/distinct_id'
          event:
            $ref: '#/components/schemas/event'
          to:
            $ref: '#/components/schemas/to'
        required:
        - distinct_id
        - event
        - to
        type: object
    inline_response_202_response_inapp:
      properties:
        destination:
          example: '12345'
          type: string
        msg_id:
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:XXXX
          type: string
        status:
          example: ok
          type: string
      type: object
      required:
      - destination
      - msg_id
      - status
    inline_response_202_response_discord:
      properties:
        destination:
          example: 101XXXXXXXXXX7XXXXX
          type: string
        msg_id:
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:XXXX
          type: string
        status:
          example: ok
          type: string
      type: object
      required:
      - destination
      - msg_id
      - status
    callback:
      description: (Optional) You can enable callback for an event by specifying the `callback` attribute in the payload of the event. By enabling callback, you will be able to receive delivery status of the events onto your webhook URL specified in the "Allowlist URL" section of the application. See [Configuring Allowlist URL/SQS to receive Delivery Report](../../configuring-allowlist-url-sqs-to-receive-delivery-report) for more details.
      properties:
        custom_id:
          description: Use this parameter to send an ID that you would want to receive as a response (for reconciliation) in your delivery callback.
          example: ID001
          type: string
        custom1:
          description: (Optional) Use this parameter to send another ID that you want to receive as a response (for reconciliation) in your delivery callback.
          example: EV001
          type: string
        custom2:
          description: (Optional) Use this parameter to send yet another ID that you want to receive as a response (for reconciliation) in your delivery callback.
          example: P001
          type: string
        custom3:
          description: (Optional) Use this parameter to send yet another ID that you want to receive as a response (for reconciliation) in your delivery callback.
          example: C001
          type: string
        enable:
          description: (Optional) Set `true` to enable delivery callback or `false` to disable delivery callback. The default value is `true` if `custom_id` is specified.
          enum:
          - true
          - false
          example: true
          type: boolean
        allowlist_url:
          description: (Optional) Allowlist URL name where you want to receive delivery reports. Can be array of Allowlist URL names too if you want the delivery reports in multiple URLs. If `allowlist_url` is not specified, but callback object has `enable=true` and `custom_id` is specified, then the delivery reports will be sent to the default endpoint set to receive delivery reports in the [Configuring Allowlist URL](../../configuring-allowlist-url-sqs-to-receive-delivery-report) settings.
          example:
          - WebhookURL1
          - WebhookURL2
          oneOf:
          - type: string
          - type: array
            items:
              type: string
      required:
      - custom_id
      type: object
    inline_response_202_response_email:
      properties:
        destination:
          example: abcde@fghi.com
          type: string
        msg_id:
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:XXXX
          type: string
        status:
          example: ok
          type: string
      type: object
      required:
      - destination
      - msg_id
      - status
    to:
      properties:
        discord:
          description: Enter the discord ID of the user.
          example: 101XXXXXXXXXX7XXXXX
          type: string
        email:
          description: Enter the email address of the user.
          example: abcde@fghi.com
          type: string
        inapp:
          description: Enter the distinct ID or the generated token of the user.
          example: '12345'
          type: string
        push:
          description: If you use multiple Push providers, add the following prefix for the respective provider tokens:<br/><br/>- <b>For Expo&#58;</b> `expo_token:`<your_pushtoken><br/>- <b>For FCM&#58;</b> `fcm_token:`<your_pushtoken><br/>- <b>For OneSignal playerId&#58;</b> `onesignal_player_id:`<enter_playerid><br/>- <b>For OneSignal externalId&#58;</b> `onesignal_external_id:`<enter_externalid><br/>- <b>For Mi Push&#58;</b> `mi_token:`<your_pushtoken><br/><br/>If you use just one provider, then the prefix is not required. However, if you wish to use OneSignal with playerId token, then the prefix is required.
          example: ExponentPushToken[XXXXX]
          type: string
        slack:
          description: Enter the channel ID, user ID, or email address of the user.
          example: CXXXXXXXXXX
          type: string
        sms:
          description: Enter the mobile number of the user. The number must start with the country code (preferably in E.164 format). For example&#58; +919879XXXXXX.
          example: +919879XXXXXX
          type: string
        teams:
          description: Enter the channel name. For teams, we currently support sending to one channel only. To send to multiple channels, do get in touch and we can share a workaround.
          example: General
          type: string
        voice:
          description: Enter the mobile number of the user. The number must start with the country code (preferably in E.164 format). For example&#58; +919879XXXXXX.
          example: +919879XXXXXX
          type: string
        whatsapp:
          description: Enter the WhatsApp mobile number of the user. The number must start with the country code (preferably in E.164 format). For example&#58; +919879XXXXXX
          example: +919879XXXXXX
          type: string
      type: object
    inline_response_202_response_sms:
      properties:
        destination:
          example: +919879XXXXXX
          type: string
        msg_id:
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:XXXX
          type: string
        status:
          example: ok
          type: string
      type: object
      required:
      - destination
      - msg_id
      - status
    event:
      description: Enter the name of the event you wish to fire.
      example: event_name
      type: string
    event_bulk_body:
      properties:
        batch:
          description: Your batch payload must specify at least *`distinct_id`* or *`to`* while firing a notification event.<br/><br/>If the payload contains&#58;<br/><br/>- <b>Option 1&#58;</b> ONLY *`to`* (and no *`distinct_id`*) - the event uses all destination values from the *`to`* object (as it is).<br/><br/>- <b>Option 2&#58;</b> ONLY *`distinct_id`* (and no *`to`*) - the event uses all destination values (such as SMS, WhatsApp, Email, Push, Voice and so on) from the user's profile and sends the notification.<br/><br/>- <b>Option 3&#58;</b> BOTH *`distinct_id`* and *`to`* - the `to` and `distinct_id` channel data merges (`to` object take precedences) and sends the notification. The sent notification is tagged to the ID specified, which can be then used to search the logs by using `distinct_id`.
          items:
            oneOf:
            - properties:
                callback:
                  $ref: '#/components/schemas/callback'
                data:
                  $ref: '#/components/schemas/data'
                to:
                  $ref: '#/components/schemas/to'
              required:
              - event
              - to
              type: object
            - properties:
                callback:
                  $ref: '#/components/schemas/callback'
                data:
                  $ref: '#/components/schemas/data'
                distinct_id:
                  $ref: '#/components/schemas/distinct_id'
              required:
              - distinct_id
              - event
              type: object
            - properties:
                callback:
                  $ref: '#/components/schemas/callback'
                data:
                  $ref: '#/components/schemas/data'
                distinct_id:
                  $ref: '#/components/schemas/distinct_id'
                to:
                  $ref: '#/components/schemas/to'
              required:
              - distinct_id
              - event
              - to
              type: object
          type: array
        event:
          $ref: '#/components/schemas/event'
      required:
      - batch
      - event
      type: object
    inline_response_202_response_teams:
      properties:
        destination:
          example: General
          type: string
        msg_id:
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:XXXX
          type: string
        status:
          example: ok
          type: string
      type: object
      required:
      - destination
      - msg_id
      - status
    inline_response_202_response_slack:
      properties:
        destination:
          example: CXXXXXXXXXX
          type: string
        msg_id:
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:XXXX
          type: string
        status:
          example: ok
          type: string
      type: object
      required:
      - destination
      - msg_id
      - status
    inline_response_202_response_push:
      properties:
        destination:
          example: ExponentPushToken[XXXXX]
          type: string
        msg_id:
          example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX:XXXX
          type: string
        status:
          example: ok
          type: string
      type: object
      required:
      - destination
      - msg_id
      - status
    data:
      description: (Optional) Enter the keys and values of your replaceabale placeholders. These values are replaced in the respective keys of the template when the notification is sent.
      example:
        placeholder_key_1: placeholder_value_1
        placeholder_key_2: placeholder_value_2
      type: object
    inline_response_202_1_response:
      properties:
        discord:
          $ref: '#/components/schemas/inline_response_202_response_discord'
        email:
          $ref: '#/components/schemas/inline_response_202_response_email'
        inapp:
          $ref: '#/components/schemas/inline_response_202_response_inapp'
        push:
          $ref: '#/components/schemas/inline_response_202_response_push'
        seq:
          example: 1
          type: integer
        slack:
          $ref: '#/components/schemas/inline_response_202_response_slack'
        sms:
          $ref: '#/components/schemas/inline_response_202_response_sms'
        teams:
          $ref: '#/components/schemas/inline_response_202_response_teams'
        voice:
          $ref: '#/components/schemas/inline_response_202_response_sms'
        whatsapp:
          $ref: '#/components/schemas/inline_response_202_response_sms'
      type: object
  responses:
    APIKeyInvalid:
      description: API Key or Workspace ID is invalid. User is unauthorised.
      content:
        application/json:
          schema:
            properties:
              _message:
                example: Invalid API details
                type: string
              status:
                example: error
                type: string
            type: object
            required:
            - _message
            - status
    EventNameDoesNotExist:
      description: Event name does not exist
      content:
        application/json:
          schema:
            properties:
              _message:
                example: The notification event name 'event_name' is invalid or does not exists on prod
                type: string
              status:
                example: error
                type: string
            type: object
            required:
            - _message
            - status
    EventRequestAccepted:
      description: Request accepted successfully and it will be processed asynchronously.
      content:
        application/json:
          schema:
            properties:
              event:
                example: event_name
                type: string
              received_time:
                example: '2025-02-17T07:49:13.352Z'
                type: string
                format: date
              request_id:
                example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
                type: string
              response:
                $ref: '#/components/schemas/inline_response_202_response'
            type: object
            required:
            - event
            - received_time
            - request_id
            - response
    BulkEventRequestAccepted:
      description: Request accepted successfully and it will be processed asynchronously.
      content:
        application/json:
          schema:
            properties:
              event:
                example: event_name
                type: string
              received_time:
                example: 1672991866453
                type: number
              request_id:
                example: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
                type: string
              response:
                items:
                  $ref: '#/components/schemas/inline_response_202_1_response'
                type: array
            type: object
  securitySchemes:
    BearerAuth:
      type: http
      description: Enter your API Key. If you don't have it already, you can create one from the API Keys page within your Fyno account
      scheme: bearer
      x-fern-bearer:
        name: apiKey
        env: FYNO_API_KEY