The Dispatch API enables the developer to specify a multiple message workflow. A workflow follows a template. The first one we are adding is the failover template. The failover template instructs the Messages API to first send a message to the specified channel. If that message fails immediately or if the condition_status is not reached within the given time period the next message is sent. The developer will also receive status webhooks from the messages resource for each delivery and read event. This API is currently in Beta.
POST
https://api.nexmo.com/v0.1/dispatch
Host
https://api.nexmo.com
POST
/v0.1/dispatch
This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.
You can use either JWT or Basic authentication, but not both at the same time.
| Key | Description | Example | Default |
|---|---|---|---|
| Authorization |
Your JSON web token. Read more about JWTs |
Bearer <JWT> |
None |
| Authorization |
Base64 encoded API key and secret joined by a colon. Read more |
Basic <base64> |
None |
Please note that last message does not have failover attribute inside it. All other messages must contain a failover attribute.
The template that the Dispatch API will execute. For the initial version of the API the only available value will be failover
Must be one of:failover
Contains a message object that must reflect the current /messages resource. All parameters within the content object reflect the /messages docs.
Send With Failover Message
The type of message that you want to send.
Must be one of:sms, viber_service_msg, messenger or whatsapp
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.
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.
Send With Failover Message
The type of message that you want to send.
Must be one of:sms, viber_service_msg, messenger or whatsapp
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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.
SMS: MMS: or WhatsApp This value is not required.
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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.
Messenger: or Viber: This value is not required.
Send With Failover Message
The type of message that you are sending.
Messenger: supports text, image, audio, video and file.
Viber Service Messages: supports image and text.
WhatsApp: supports template, text, image, audio, video and file.
SMS: supports text.
text, image, audio, video, file, template or custom
The text of the message.
Messenger: Is limited to 640 characters
SMS or Viber: Is 1000 characters
WhatsApp: is 4096 characters
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.
Additional text to accompany the image. Supported by WhatsApp and MMS.
The URL of the audio attachment. messenger supports .mp3. whatsapp supports .aac, .m4a, .amr, .mp3 and .opus.
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.
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).
Additional text to accompany the image. Supported by WhatsApp and MMS.
The name of the template.
The parameters are an array. The first value being {{1}} in the template.
The use of different category tags enables the business to send messages for different use cases. For Viber Service Messages the first message sent from a business to a user must be personal, informative and a targeted message - not promotional. By default Nexmo sends the transaction category to Viber Service Messages.
transaction or promotion
Only valid for Viber Service 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.
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. Nexmo maps our category to their messaging_type. If message_tag is used, then an additional tag for that type is mandatory. By default Nexmo sends the response category to Facebook Messenger.
response, update or message_tag
‘A full list of the possible tags is available on developers.facebook.com'
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.
fallback or deterministic
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.
Please note that last message does not have failover attribute inside it. All other messages must contain a failover attribute.
In seconds. Minimum value is 15 and maximum value is 86,400 seconds (1 day).
Set the status the message must reach in the expiry_time before failing over. Options are delivered or read.
Must be one of:delivered or read
Send Message
The type of message that you want to send.
Must be one of:sms, viber_service_msg, messenger or whatsapp
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.
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.
Send Message
The type of message that you want to send.
Must be one of:sms, viber_service_msg, messenger or whatsapp
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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.
SMS: MMS: or WhatsApp This value is not required.
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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.
Messenger: or Viber: This value is not required.
Send Message
The type of message that you are sending.
Messenger: supports text, image, audio, video and file.
Viber Service Messages: supports image and text.
WhatsApp: supports template, text, image, audio, video and file.
SMS: supports text.
text, image, audio, video, file, template or custom
The text of the message.
Messenger: Is limited to 640 characters
SMS or Viber: Is 1000 characters
WhatsApp: is 4096 characters
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.
Additional text to accompany the image. Supported by WhatsApp and MMS.
The URL of the audio attachment. messenger supports .mp3. whatsapp supports .aac, .m4a, .amr, .mp3 and .opus.
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.
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).
Additional text to accompany the image. Supported by WhatsApp and MMS.
The name of the template.
The parameters are an array. The first value being {{1}} in the template.
The use of different category tags enables the business to send messages for different use cases. For Viber Service Messages the first message sent from a business to a user must be personal, informative and a targeted message - not promotional. By default Nexmo sends the transaction category to Viber Service Messages.
transaction or promotion
Only valid for Viber Service 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.
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. Nexmo maps our category to their messaging_type. If message_tag is used, then an additional tag for that type is mandatory. By default Nexmo sends the response category to Facebook Messenger.
response, update or message_tag
‘A full list of the possible tags is available on developers.facebook.com'
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.
fallback or deterministic
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.
The parent ID for workflow request.
{
"dispatch_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}{
"type": "https://www.nexmo.com/messages/Errors#InvalidParams",
"detail": "Your request parameters did not validate.",
"instance": "abc123",
"invalid_parameters": {
"name": "Invalid `from` parameter",
"reason": "Invalid `from` parameter"
}
}status of the message read or delivered etc.
POST
https://example.com/webhooks/message-status
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.
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.
The type of message that you want to send.
One of:sms, viber_service_msg, messenger or whatsapp
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.
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.
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.
The type of message that you want to send.
One of:sms, viber_service_msg, messenger or whatsapp
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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.
SMS: MMS: or WhatsApp This value is not required.
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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages.
Messenger: or Viber: This value is not required.
The datetime of when the event occurred.
The status of the message.
One of:submitted, delivered, read, rejected or undeliverable
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.
The error code. See our errors list for a list of possible errors
Text describing the error. See our errors list for a list of possible errors
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.
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
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.
Please note GET is not currently supported
{
"to": {
"type": "sms"
},
"from": {
"type": "sms"
}
}{
"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"
}
}
}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.
POST
https://example.com/webhooks/final-report
failover
completed or error
The datetime of when the event occurred.
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.
The charge amount as a stringified number.
The charge currency in ISO 4217 format.
One of:EUR
Please note GET is not currently supported
messenger, viber_sevice_msg, sms, whatsapp or mms
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
submitted, delivered, read, rejected or undeliverable
{
"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"
}
}
]
}
}