Dispatch API Beta

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

Download OpenAPI 3 Definition

Create a workflow

POST https://api.nexmo.com/v0.1/dispatch

Authentication

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

Request body application/json

Key Description Example Default
template
string

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
failover None
workflow
array
None

Any one of the following:

Send With Failover Message
Key Description Example Default
to
Required | object
None
Key Description Example Default
type
Required | string

The type of message that you want to send.


Must be one of: sms, viber_service_msg, messenger or whatsapp
sms None
id
string

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.

0123456789012345 None
number
string

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

447700900000 None
from
Required | object
None
Key Description Example Default
type
Required | string

The type of message that you want to send.


Must be one of: sms, viber_service_msg, messenger or whatsapp
sms None
id
string

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: or WhatsApp This value is not required.

0123456789012345 None
number
string

SMS: The phone number of the message recipient 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.

447700900000 None
message
Required | object
None
Key Description Example Default
content
Required | object
None
Key Description Example Default
type
string

The type of message that you are sending.

Messenger: supports all types.

Viber Service Messages: supports image and text.

WhatsApp: supports template and text.

SMS: supports text.


Must be one of: text, image, audio, video, file, template or custom
text None
text
string

The text of the message.

Messenger: Is limited to 640 characters

SMS or Viber: Is 1000 characters

WhatsApp: is 4096 characters

Nexmo Verification code: 64873. Valid for 10 minutes. None
image
object
None
Key Description Example Default
url
string

The URL of the image attachment. messenger supports .jpg, .png and .gif. viber_service_msg supports .jpg and .png.

https://example.com/image.jpg None
audio
object
None
Key Description Example Default
url
string

The URL of the audio attachment. messenger supports .mp3.

https://example.com/audio.mp3 None
video
object
None
Key Description Example Default
url
string

The URL of the video attachment. messenger supports .mp4

https://example.com/video.mp4 None
file
object
None
Key Description Example Default
url
string

The URL of the file attachment. messenger supports a wide range of attachments including .zip, .csv and .pdf

https://example.com/file.zip None
template
object
None
Key Description Example Default
name
string

The name of the template.

whatsapp:hsm:technology:nexmo:verify None
parameters
array
of object's
None
viber_service_msg
object
None
Key Description Example Default
category
string

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.


Must be one of: transaction or promotion
transaction None
ttl
integer

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.


Must be between 30 and 86400
600 None
messenger
object
None
Key Description Example Default
category
string

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.


Must be one of: response, update or message_tag
message_tag None
tag
string

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

ticket_update None
failover
object
None
Key Description Example Default
expiry_time
integer

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


Must be between 15 and 86400
600 None
condition_status
string

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
delivered None
Send Message
Key Description Example Default
to
Required | object
None
Key Description Example Default
type
Required | string

The type of message that you want to send.


Must be one of: sms, viber_service_msg, messenger or whatsapp
sms None
id
string

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.

0123456789012345 None
number
string

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

447700900000 None
from
Required | object
None
Key Description Example Default
type
Required | string

The type of message that you want to send.


Must be one of: sms, viber_service_msg, messenger or whatsapp
sms None
id
string

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: or WhatsApp This value is not required.

0123456789012345 None
number
string

SMS: The phone number of the message recipient 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.

447700900000 None
message
Required | object
None
Key Description Example Default
content
Required | object
None
Key Description Example Default
type
string

The type of message that you are sending.

Messenger: supports all types.

Viber Service Messages: supports image and text.

WhatsApp: supports template and text.

SMS: supports text.


Must be one of: text, image, audio, video, file, template or custom
text None
text
string

The text of the message.

Messenger: Is limited to 640 characters

SMS or Viber: Is 1000 characters

WhatsApp: is 4096 characters

Nexmo Verification code: 64873. Valid for 10 minutes. None
image
object
None
Key Description Example Default
url
string

The URL of the image attachment. messenger supports .jpg, .png and .gif. viber_service_msg supports .jpg and .png.

https://example.com/image.jpg None
audio
object
None
Key Description Example Default
url
string

The URL of the audio attachment. messenger supports .mp3.

https://example.com/audio.mp3 None
video
object
None
Key Description Example Default
url
string

The URL of the video attachment. messenger supports .mp4

https://example.com/video.mp4 None
file
object
None
Key Description Example Default
url
string

The URL of the file attachment. messenger supports a wide range of attachments including .zip, .csv and .pdf

https://example.com/file.zip None
template
object
None
Key Description Example Default
name
string

The name of the template.

whatsapp:hsm:technology:nexmo:verify None
parameters
array
of object's
None
viber_service_msg
object
None
Key Description Example Default
category
string

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.


Must be one of: transaction or promotion
transaction None
ttl
integer

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.


Must be between 30 and 86400
600 None
messenger
object
None
Key Description Example Default
category
string

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.


Must be one of: response, update or message_tag
message_tag None
tag
string

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

ticket_update None

View response field descriptions

Response Fields

Field Description
dispatch_uuid

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"
  }
}

Message Status Callback

status of the message read or delivered etc.

POST https://example.com /webhooks/message-status

Request body application/json

Key Description Example
message_uuid
string

None

aaaaaaaa-bbbb-cccc-dddd-0123456789ab
to
Required | object
Key Description Example
type
Required | string

The type of message that you want to send.


One of: sms, viber_service_msg, messenger or whatsapp
sms
id
string

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.

0123456789012345
number
string

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

447700900000
from
Required | object
Key Description Example
type
Required | string

The type of message that you want to send.


One of: sms, viber_service_msg, messenger or whatsapp
sms
id
string

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: or WhatsApp This value is not required.

0123456789012345
number
string

SMS: The phone number of the message recipient 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.

447700900000
timestamp
string | (ISO 8601)

The datetime of when the event occurred.

2020-01-01T14:00:00.000Z
status
string

The status of the message.


One of: submitted, delivered, read, rejected or undeliverable
delivered
error
object
Key Description Example
code
integer

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

1300
reason
string

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

Not part of the provider network
usage
object
Key Description Example
currency
string

The charge currency in ISO 4217 format.


One of: EUR
EUR
price
string

The charge amount as a stringified number.

0.0333
_links
object
Key Description Example
workflow
object
Key Description Example
dispatch_uuid
string

None

aaaaaaaa-bbbb-cccc-dddd-0123456789ab
href
string

Please note GET is not currently supported

/workflows/aaaaaaaa-bbbb-cccc-dddd-0123456789ab
Request model
{
  "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 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.

POST https://example.com /webhooks/final-report

Request body application/json

Key Description Example
dispatch_uuid
string

None

aaaaaaaa-bbbb-cccc-dddd-0123456789ab
template
string

None


One of: failover
failover
status
string

None


One of: completed or error
completed
timestamp
string | (ISO 8601)

The datetime of when the event occurred.

2020-01-01T14:00:00.000Z
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.

Key Description Example
price
string

The charge amount as a stringified number.

0.02
currency
string

The charge currency in ISO 4217 format.


One of: EUR
EUR
_links
object
Key Description Example
messages
array
of object's
Request model
{
  "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": "abc123"
      }
    ]
  }
}