Dispatch API

The Dispatch API enables the developer to specify a multiple message workflow.

Product deprecation notice

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.

For general information about the Messages Failover feature please refer to this guide. For guidance on migrating from Dispatch API to Messages API Failover, please refer to this guide.

If you have any further questions regarding this product deprecation, please contact your account manager or support for help.

Descargar la especificación OpenAPI
Operaciones disponibles

Create a workflow

posthttps://api.nexmo.com/v0.1/dispatch/

Autenticación

Esta API admite tanto la autenticación JWT como la básica. La autenticación básica es más fácil para empezar, pero no admite funciones avanzadas como ACL.

Puede utilizar o bien la autenticación JWT o Basic, pero no ambas a la vez.

ClaveDescripciónDóndeEjemplo
Authorization

Su token web JSON.
Más información sobre los JWT

Headers

Bearer <JWT>
Authorization

Clave API codificada en Base64 y secreto unidos por dos puntos.
Seguir leyendo

Headers

Basic <base64>

Cuerpo de la solicitud
Tipo de contenido
application/json

template
string
ejemplofailover

The template that the Dispatch API will execute. For the initial version of the API the only available value will be failover

Debe ser uno de:failover
workflow
array

Contains a message object that must reflect the current /messages resource. All parameters within the content object reflect the /messages docs.

Uno de
to
object
Requerido
type
string
Requerido
ejemplosms

The type of message that you want to send.

Debe ser uno de:smsviber_service_msgmessengerwhatsapp
id
string
Min1
Max50
ejemplo0123456789012345

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.

number
string
Min1
Max50
ejemplo447700900000

SMS: or MMS: or Viber: or WhatsApp The phone number of the message recipient in the 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.

from
object
Requerido
type
string
Requerido
ejemplosms

The type of message that you want to send.

Debe ser uno de:smsviber_service_msgmessengerwhatsapp
id
string
Min1
Max50
ejemplo0123456789012345

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.

SMS: MMS: or WhatsApp This value is not required.

number
string
Min1
Max50
ejemplo447700900000

SMS: or MMS: The phone number of the message sender in the 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.

Messenger: or Viber: This value is not required.

message
object
Requerido
content
object
Requerido
type
string
Requerido
ejemplotext

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.

Debe ser uno de:textimageaudiovideofiletemplatecustom
text
string
Min1
Max4096
ejemploVonage Verification code: 64873. Valid for 10 minutes.

The text of the message.

Messenger: Is limited to 640 characters

SMS or Viber: Is 1000 characters

WhatsApp: is 4096 characters

image
object
url
string
Min1
Max2000
ejemplohttps://example.com/image.jpg

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.

caption
string
Min1
Max3000
ejemploAdditional text to accompany the image.

Additional text to accompany the image. Supported by WhatsApp and MMS.

audio
object
url
string
Min1
Max2000
ejemplohttps://example.com/audio.mp3

The URL of the audio attachment. messenger supports .mp3. whatsapp supports .aac, .m4a, .amr, .mp3 and .opus.

video
object
url
string
Min1
Max2000
ejemplohttps://example.com/video.mp4

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.

file
object
url
string
Min1
Max2000
ejemplohttps://example.com/file.zip

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).

caption
string
Min1
Max3000
ejemploAdditional text to accompany the image.

Additional text to accompany the image. Supported by WhatsApp and MMS.

template
object
name
string
ejemplowhatsapp:hsm:technology:vonage:verify

The name of the template.

parameters
array
default
string
ejemplo1234

The parameters are an array. The first value being 1 in the template.

viber_service_msg
object
category
string
ejemplotransaction

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.

Debe ser uno de:transactionpromotion
ttl
integer
Min30
Max86400
ejemplo600

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.

messenger
object
category
string
ejemplomessage_tag

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. 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.

Debe ser uno de:responseupdatemessage_tag
tag
string
ejemploticket_update

‘A full list of the possible tags is available on developers.facebook.com'

whatsapp
object
policy
string
ejemplodeterministic

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.

Debe ser uno de:fallbackdeterministic
locale
string
ejemploen-GB

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.

failover
object

Please note that last message does not have failover attribute inside it. All other messages must contain a failover attribute.

expiry_time
integer
Min15
Max86400
ejemplo600

In seconds. Minimum value is 15 and maximum value is 86,400 seconds (1 day).

condition_status
string
ejemplodelivered

Set the status the message must reach in the expiry_time before failing over. Options are delivered or read.

Debe ser uno de:deliveredread

Ejemplo Solicitar

{
   "template": "failover",
   "workflow": [
      {
         "to": {
            "type": "sms",
            "id": "0123456789012345",
            "number": "447700900000"
         },
         "from": {
            "type": "sms",
            "id": "0123456789012345",
            "number": "447700900000"
         },
         "message": {
            "content": {
               "type": "text",
               "text": "Vonage Verification code: 64873. Valid for 10 minutes.",
               "image": {
                  "url": "https://example.com/image.jpg",
                  "caption": "Additional text to accompany the image."
               },
               "audio": {
                  "url": "https://example.com/audio.mp3"
               },
               "video": {
                  "url": "https://example.com/video.mp4"
               },
               "file": {
                  "url": "https://example.com/file.zip",
                  "caption": "Additional text to accompany the image."
               },
               "template": {
                  "name": "whatsapp:hsm:technology:vonage:verify",
                  "parameters": [
                     {
                        "default": "1234"
                     }
                  ]
               }
            },
            "viber_service_msg": {
               "category": "transaction",
               "ttl": 600
            },
            "messenger": {
               "category": "message_tag",
               "tag": "ticket_update"
            },
            "whatsapp": {
               "policy": "deterministic",
               "locale": "en-GB"
            }
         },
         "failover": {
            "expiry_time": 600,
            "condition_status": "delivered"
         }
      }
   ]
}

Respuestas
Tipo de contenido
application/json

Accepted

dispatch_uuid
string
Requerido
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The parent ID for workflow request.

Ejemplo Respuesta

{
   "dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Message Status callback

status of the message read or delivered etc.

posthttps://example.com/webhooks/message-status

Cuerpo de la solicitud
Tipo de contenido
application/json

message_uuid
string
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab
to
object
type
string
Requerido
ejemplosms

The type of message that you want to send.

Debe ser uno de:smsviber_service_msgmessengerwhatsapp
id
string
Min1
Max50
ejemplo0123456789012345

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.

number
string
Min1
Max50
ejemplo447700900000

SMS: or MMS: or Viber: or WhatsApp The phone number of the message recipient in the 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.

from
object
type
string
Requerido
ejemplosms

The type of message that you want to send.

Debe ser uno de:smsviber_service_msgmessengerwhatsapp
id
string
Min1
Max50
ejemplo0123456789012345

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.

SMS: MMS: or WhatsApp This value is not required.

number
string
Min1
Max50
ejemplo447700900000

SMS: or MMS: The phone number of the message sender in the 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.

Messenger: or Viber: This value is not required.

timestamp
string(ISO 8601)
ejemplo2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

status
string
ejemplodelivered

The status of the message.

Debe ser uno de:submitteddeliveredreadrejectedundeliverable
error
object
code
integer
ejemplo1300

The error code. See our errors list for a list of possible errors

reason
string
ejemploNot part of the provider network

Text describing the error. See our errors list for a list of possible errors

usage
object
currency
string
ejemploEUR

The charge currency in ISO 4217 format.

Debe ser uno de:EUR
price
string
ejemplo0.0333

The charge amount as a stringified number.

_links
object
workflow
object
dispatch_uuid
string
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab
href
string
ejemplo/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab

Please note GET is not currently supported

Ejemplo Carga útil

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "to": {
      "type": "sms",
      "id": "0123456789012345",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "id": "0123456789012345",
      "number": "447700900000"
   },
   "timestamp": "2020-01-01T14:00:00.000Z",
   "status": "delivered",
   "error": {
      "code": 1300,
      "reason": "Not part of the provider network"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   },
   "_links": {
      "workflow": {
         "dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
         "href": "/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
      }
   }
}

Respuestas

Your server returns this code if it accepts the callback

The Final Report callback

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.

posthttps://example.com/webhooks/final-report

Cuerpo de la solicitud
Tipo de contenido
application/json

dispatch_uuid
string
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab
template
string
ejemplofailover
Debe ser uno de:failover
status
string
ejemplocompleted
Debe ser uno de:completederror
timestamp
string(ISO 8601)
ejemplo2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

usage
object

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.

price
string
ejemplo0.02

The charge amount as a stringified number.

currency
string
ejemploEUR

The charge currency in ISO 4217 format.

Debe ser uno de:EUR
_links
object
messages
array
message_uuid
string
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab
href
string
ejemploaaaaaaaa-bbbb-cccc-dddd-0123456789ab

Please note GET is not currently supported

channel
string
ejemploviber_service_msg
Debe ser uno de:messengerviber_sevice_msgsmswhatsappmms
usage
object
currency
string
ejemploEUR

The charge currency in ISO 4217 format.

Debe ser uno de:EUR
price
string
ejemplo0.0333

The charge amount as a stringified number.

status
string
Debe ser uno de:submitteddeliveredreadrejectedundeliverable

Ejemplo Carga útil

{
   "dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "template": "failover",
   "status": "completed",
   "timestamp": "2020-01-01T14:00:00.000Z",
   "usage": {
      "price": "0.02",
      "currency": "EUR"
   },
   "_links": {
      "messages": [
         {
            "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
            "href": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
            "channel": "viber_service_msg",
            "usage": {
               "currency": "EUR",
               "price": "0.0333"
            },
            "status": "submitted"
         }
      ]
   }
}

Respuestas

Your server returns this code if it accepts the callback