openapi: 3.0.0
info:
  version: 0.4.0
  title: Dispatch API
  x-metaTitle: Vonage Dispatch API Reference | Vonage API Documentation
  x-metaDescription: Find quick answers to questions about the Vonage Dispatch API
    in this reference guide. Learn more in Vonage's API documentation.
  description: >
    The Dispatch API enables the developer to specify a multiple message
    workflow.

    <div style="background-color:#e8f4fb;border:#0476d5
    solid;padding:2%;border-radius:5px;margin-top:2%">
        <h3 style="padding-left:2%">Product deprecation notice</h3>
        <p>From August 31st 2025, the Vonage Dispatch API will be closed to new users, though the product will continue to be supported for existing users. If you are looking to build a messaging application with failover functionality, failover is now supported directly in the Messages API.</p> 
        <p>For general information about the Messages Failover feature please refer to <a href="/messages/guides/failover-message">this guide</a>. For guidance on migrating from Dispatch API to Messages API Failover, please refer to <a href="/dispatch/guides/migration-to-messages-failover">this guide</a>.</p>
        <p>If you have any further questions regarding this product deprecation, please contact your account manager or support for help.</p>
      </div>
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.nexmo.com/
  x-label: Deprecated
servers:
  - url: https://api.nexmo.com/v0.1/dispatch
paths:
  /:
    post:
      security:
        - bearerAuth: []
        - basicAuth: []
      summary: Create a workflow
      operationId: createWorkflow
      requestBody:
        x-hide-request: true
        description: Please note that last message does not have failover attribute
          inside it. All other messages must contain a failover attribute.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/createWorkflow"
      responses:
        "202":
          description: Accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Response"
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      callbacks:
        message-status:
          "{$request.body#/callback}":
            post:
              summary: Message Status
              operationId: message-status
              x-example-path: /webhooks/message-status
              description: status of the message read or delivered etc.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/MessageStatus"
              responses:
                "200":
                  description: Your server returns this code if it accepts the callback
        final-report:
          "{$request.body#/callback}":
            post:
              summary: The Final Report
              operationId: final-report
              x-example-path: /webhooks/final-report
              description: The final workflow callback is sent when The condition_status was
                met within the expiry_time. If we take the example API call
                above. If we received a delivered status at 300 seconds (within
                the expiry_time) the workflow would be marked as completed. We
                would not send an SMS. We would then send the final callback.
                The final message in the failover is delivered. If the message
                Errors on the last step we will send the final callback. Please
                note GET is not currently supported. You will notice we have an
                href to a resource in some of the callbacks. These will fail to
                load but we wanted to maintain the same structure so that we can
                seamlessly integrate GET later.
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: "#/components/schemas/finalReport"
              responses:
                "200":
                  description: Your server returns this code if it accepts the callback
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      scheme: basic
  schemas:
    createWorkflow:
      type: object
      properties:
        template:
          description: The template that the Dispatch API will execute. For the initial
            version of the API the only available value will be failover
          type: string
          enum:
            - failover
          example: failover
        workflow:
          description: Contains a message object that must reflect the current /messages
            resource. All parameters within the content object reflect the
            /messages docs.
          type: array
          items:
            oneOf:
              - $ref: "#/components/schemas/sendWithFailoverMessage"
              - $ref: "#/components/schemas/sendMessage"
    ToProperty:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The type of message that you want to send.
          example: sms
          enum:
            - sms
            - viber_service_msg
            - messenger
            - whatsapp
        id:
          description: >
            The ID of the message recipient.


            **Messenger**: This value should be the `from.id` value you received
            in the inbound messenger event.


            **SMS**: or **Viber**: or **WhatsApp** This value is not required.
          type: string
          minLength: 1
          maxLength: 50
          example: "0123456789012345"
        number:
          type: string
          minLength: 1
          maxLength: 50
          example: "447700900000"
          description: >
            **SMS**: or **MMS**: or **Viber**: or **WhatsApp** The phone number
            of the message recipient in the
            [E.164](https://en.wikipedia.org/wiki/E.164) format. Don't use a
            leading + or 00 when entering a phone number, start with the country
            code, for example, 447700900000.


            **Messenger**: This value is not required.
    FromProperty:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          description: The type of message that you want to send.
          example: sms
          enum:
            - sms
            - viber_service_msg
            - messenger
            - whatsapp
        id:
          description: >
            Your ID for the platform that you are sending from.


            **Messenger**: This value should be the `to.id` value you received
            in the inbound messenger event.


            **Viber**: This is your Service Message ID given to you by your
            Vonage Account Manager. To find out more please visit
            [vonage.com](https://www.vonage.com/communications-apis/messages/).


            **SMS**: **MMS**: or **WhatsApp** This value is not required.
          type: string
          minLength: 1
          maxLength: 50
          example: "0123456789012345"
        number:
          type: string
          minLength: 1
          maxLength: 50
          example: "447700900000"
          description: >
            **SMS**: or **MMS**: The phone number of the message sender in the
            [E.164](https://en.wikipedia.org/wiki/E.164) format.


            **WhatsApp**: This is your WhatsApp Business Number given to you by
            your Vonage Account Manager. To find out more please visit
            [vonage.com](https://www.vonage.com/communications-apis/messages/).


            **Messenger**: or **Viber**: This value is not required.
    MessageProperty:
      type: object
      required:
        - content
      properties:
        content:
          type: object
          required:
            - type
          properties:
            type:
              description: >
                The type of message that you are sending.


                **Messenger**: supports `text`, `image`, `audio`, `video` and
                `file`.


                **Viber Business Messages**: supports `image` and `text`.


                **WhatsApp**: supports `template`, `text`, `image`, `audio`,
                `video` and `file`.


                **SMS**: supports `text`.
              type: string
              enum:
                - text
                - image
                - audio
                - video
                - file
                - template
                - custom
              example: text
            text:
              description: |
                The text of the message.

                **Messenger**: Is limited to 640 characters

                **SMS** or **Viber**: Is 1000 characters

                **WhatsApp**: is 4096 characters
              type: string
              minLength: 1
              maxLength: 4096
              example: "Vonage Verification code: 64873. Valid for 10 minutes."
            image:
              $ref: "#/components/schemas/ImageProperty"
            audio:
              $ref: "#/components/schemas/AudioProperty"
            video:
              $ref: "#/components/schemas/VideoProperty"
            file:
              $ref: "#/components/schemas/FileProperty"
            template:
              $ref: "#/components/schemas/TemplateProperty"
        viber_service_msg:
          type: object
          properties:
            category:
              description: The use of different category tags enables the business to send
                messages for different use cases. For Viber Business Messages
                the first message sent from a business to a user must be
                personal, informative and a targeted message - not promotional.
                By default Vonage sends the `transaction` category to Viber
                Business Messages.
              type: string
              example: transaction
              enum:
                - transaction
                - promotion
            ttl:
              description: Only valid for Viber Business Messages. Set the time-to-live of
                message to be delivered in seconds. i.e. if the message is not
                delivered in 600 seconds then delete the message.
              type: integer
              example: 600
              minimum: 30
              maximum: 86400
        messenger:
          type: object
          properties:
            category:
              description: The use of different category tags enables the business to send
                messages for different use cases. For Facebook Messenger they
                need to comply with their [Messaging Types policy](
                https://developers.facebook.com/docs/messenger-platform/send-messages#messaging_types).
                Vonage maps our `category` to their `messaging_type`. If
                `message_tag` is used, then an additional `tag` for that type is
                mandatory. By default Vonage sends the `response` category to
                Facebook Messenger.
              type: string
              example: message_tag
              enum:
                - response
                - update
                - message_tag
            tag:
              description: ‘A full list of the possible tags is available on
                [developers.facebook.com](https://developers.facebook.com/docs/messenger-platform/send-messages/message-tags)'
              type: string
              example: ticket_update
        whatsapp:
          type: object
          properties:
            policy:
              description: "Please note that WhatsApp will deprecate `fallback` policy in
                January 2020. There are two policies that you can specify when
                sending a Message Template: `deterministic` and `fallback`.
                `deterministic` — Deliver the Message Template in exactly the
                language and locale asked for. `fallback` — Deliver the Message
                Template in the language that matches users language/locale
                setting on device. If one can not be found, deliver using the
                specified fallback language."
              type: string
              example: deterministic
              enum:
                - fallback
                - deterministic
            locale:
              description: We are using the industry standard, BCP 47, for locales. So in your
                API call to the /messages API you will need to put “en-GB” and
                this will refer to the “en_GB” template for WhatsApp. A full
                list of the possible locales is available on
                [developers.facebook.com](https://developers.facebook.com/docs/whatsapp/message-templates/creation#translations).
              type: string
              example: en-GB
    FailoverProperty:
      description: Please note that last message does not have failover attribute
        inside it. All other messages must contain a failover attribute.
      type: object
      properties:
        expiry_time:
          description: In seconds. Minimum value is 15 and maximum value is 86,400 seconds
            (1 day).
          type: integer
          example: 600
          minimum: 15
          maximum: 86400
        condition_status:
          description: Set the status the message must reach in the expiry_time before
            failing over. Options are delivered or read.
          type: string
          example: delivered
          enum:
            - delivered
            - read
    TimestampProperty:
      type: string
      format: ISO 8601
      description: The datetime of when the event occurred.
      example: 2020-01-01T14:00:00.000Z
    ImageProperty:
      type: object
      properties:
        url:
          type: string
          description: The URL of the image attachment. `messenger` and `mms` supports
            .jpg, .jpeg, .png and .gif. `viber_service_msg` supports .jpg .jpeg,
            and .png. `whatsapp` supports .jpg .jpeg, and .png.
          minLength: 1
          maxLength: 2000
          example: https://example.com/image.jpg
        caption:
          type: string
          description: Additional text to accompany the image. Supported by WhatsApp and
            MMS.
          minLength: 1
          maxLength: 3000
          example: Additional text to accompany the image.
    AudioProperty:
      type: object
      properties:
        url:
          type: string
          description: The URL of the audio attachment. `messenger` supports .mp3.
            `whatsapp` supports .aac, .m4a, .amr, .mp3 and .opus.
          minLength: 1
          maxLength: 2000
          example: https://example.com/audio.mp3
    VideoProperty:
      type: object
      properties:
        url:
          type: string
          description: >
            The URL of the video attachment.


            **messenger** supports .mp4


            **whatsapp** supports .mp4 and .3gpp. Note, only H.264 video codec
            and AAC audio codec is supported.
          minLength: 1
          maxLength: 2000
          example: https://example.com/video.mp4
    FileProperty:
      type: object
      properties:
        url:
          type: string
          description: The URL of the file attachment. `messenger` supports a wide range
            of attachments including .zip, .csv and .pdf. `whatsapp` supports
            .pdf, .doc(x), .ppt(x) and .xls(x).
          minLength: 1
          maxLength: 2000
          example: https://example.com/file.zip
        caption:
          type: string
          description: Additional text to accompany the image. Supported by WhatsApp and
            MMS.
          minLength: 1
          maxLength: 3000
          example: Additional text to accompany the image.
    TemplateProperty:
      type: object
      properties:
        name:
          type: string
          description: The name of the template.
          example: whatsapp:hsm:technology:vonage:verify
        parameters:
          type: array
          items:
            type: object
            properties:
              default:
                type: string
                description: The parameters are an array. The first value being `{{1}}` in the
                  template.
                example: "1234"
    sendWithFailoverMessage:
      type: object
      description: Send With Failover Message
      required:
        - to
        - from
        - message
      properties:
        to:
          $ref: "#/components/schemas/ToProperty"
        from:
          $ref: "#/components/schemas/FromProperty"
        message:
          $ref: "#/components/schemas/MessageProperty"
        failover:
          $ref: "#/components/schemas/FailoverProperty"
    sendMessage:
      type: object
      description: Send Message
      required:
        - to
        - from
        - message
      properties:
        to:
          $ref: "#/components/schemas/ToProperty"
        from:
          $ref: "#/components/schemas/FromProperty"
        message:
          $ref: "#/components/schemas/MessageProperty"
    Response:
      required:
        - dispatch_uuid
      type: object
      properties:
        dispatch_uuid:
          description: The parent ID for workflow request.
          type: string
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
    Error:
      description: The error format is standardized to the 4xx/5xx range with a code
        and a human readable explanation.
      required:
        - type
        - title
        - detail
        - instance
      type: object
      properties:
        type:
          type: string
          example: https://www.nexmo.com/messages/Errors#InvalidParams
        detail:
          type: string
          example: Your request parameters did not validate.
        instance:
          type: string
          example: null
        invalid_parameters:
          type: object
          properties:
            name:
              type: string
              example: Invalid `from` parameter
            reason:
              type: string
              example: Invalid `from` parameter
    MessageStatus:
      description: The callbacks for the message status are the same as defined in the
        Messaging API. The only difference will be that dispatch_uuid and link
        will be appended.
      type: object
      properties:
        message_uuid:
          type: string
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        to:
          $ref: "#/components/schemas/ToProperty"
        from:
          $ref: "#/components/schemas/FromProperty"
        timestamp:
          $ref: "#/components/schemas/TimestampProperty"
        status:
          type: string
          example: delivered
          description: The status of the message.
          enum:
            - submitted
            - delivered
            - read
            - rejected
            - undeliverable
        error:
          type: object
          properties:
            code:
              type: integer
              example: 1300
              description: The error code. See [our errors list](/api-errors/messages-olympus)
                for a list of possible errors
            reason:
              type: string
              example: Not part of the provider network
              description: Text describing the error. See [our errors
                list](/api-errors/messages-olympus) for a list of possible
                errors
        usage:
          type: object
          properties:
            currency:
              type: string
              example: EUR
              description: The charge currency in ISO 4217 format.
              enum:
                - EUR
            price:
              type: string
              example: "0.0333"
              description: The charge amount as a stringified number.
        _links:
          type: object
          properties:
            workflow:
              type: object
              properties:
                dispatch_uuid:
                  type: string
                  example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
                href:
                  description: Please note GET is not currently supported
                  type: string
                  example: /workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
    finalReport:
      type: object
      properties:
        dispatch_uuid:
          type: string
          example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
        template:
          type: string
          enum:
            - failover
          example: failover
        status:
          type: string
          enum:
            - completed
            - error
          example: completed
        timestamp:
          $ref: "#/components/schemas/TimestampProperty"
        usage:
          type: object
          description: This is the total cost of your Workflow request. Please note if a
            preceding message in the workflow request is delivered after the
            final message in the workflow is delivered it may not reflect the
            true total cost of the workflow.
          x-nexmo-developer-collection-description-shown: true
          properties:
            price:
              description: The charge amount as a stringified number.
              type: string
              example: "0.02"
            currency:
              description: The charge currency in ISO 4217 format.
              type: string
              enum:
                - EUR
              example: EUR
        _links:
          type: object
          properties:
            messages:
              type: array
              items:
                type: object
                properties:
                  message_uuid:
                    type: string
                    example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
                  href:
                    description: Please note GET is not currently supported
                    type: string
                    example: aaaaaaaa-bbbb-cccc-dddd-0123456789ab
                  channel:
                    type: string
                    enum:
                      - messenger
                      - viber_sevice_msg
                      - sms
                      - whatsapp
                      - mms
                    example: viber_service_msg
                  usage:
                    type: object
                    properties:
                      currency:
                        type: string
                        example: EUR
                        description: The charge currency in ISO 4217 format.
                        enum:
                          - EUR
                      price:
                        type: string
                        example: "0.0333"
                        description: The charge amount as a stringified number.
                  status:
                    type: string
                    enum:
                      - submitted
                      - delivered
                      - read
                      - rejected
                      - undeliverable
