{ "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.\n
\n

Product deprecation notice

\n

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.

\n

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.

\n

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

\n
\n", "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.\n\n**Messenger**: This value should be the `from.id` value you received in the inbound messenger event.\n\n**SMS**: or **Viber**: or **WhatsApp** This value is not required.\n", "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.\n\n**Messenger**: This value is not required.\n" } } }, "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.\n\n**Messenger**: This value should be the `to.id` value you received in the inbound messenger event.\n\n**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/).\n\n**SMS**: **MMS**: or **WhatsApp** This value is not required.\n", "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.\n\n**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/).\n\n**Messenger**: or **Viber**: This value is not required.\n" } } }, "MessageProperty": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The type of message that you are sending.\n\n**Messenger**: supports `text`, `image`, `audio`, `video` and `file`.\n\n**Viber Business Messages**: supports `image` and `text`.\n\n**WhatsApp**: supports `template`, `text`, `image`, `audio`, `video` and `file`.\n\n**SMS**: supports `text`.\n", "type": "string", "enum": [ "text", "image", "audio", "video", "file", "template", "custom" ], "example": "text" }, "text": { "description": "The text of the message.\n\n**Messenger**: Is limited to 640 characters\n\n**SMS** or **Viber**: Is 1000 characters\n\n**WhatsApp**: is 4096 characters\n", "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.\n\n**messenger** supports .mp4\n\n**whatsapp** supports .mp4 and .3gpp. Note, only H.264 video codec and AAC audio codec is supported.\n", "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) 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) 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" ] } } } } } } } } } } }