Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
581 lines (547 sloc) 21.4 KB
openapi: "3.0.0"
info:
version: 0.3.0
title: Dispatch API
description: '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.'
contact:
name: Nexmo DevRel
email: devrel@nexmo.com
url: 'https://developer.nexmo.com/'
x-label: Beta
servers:
- url: https://api.nexmo.com/v0.1
paths:
/dispatch:
post:
security:
- bearerAuth: []
- basicAuth: []
summary: Create a workflow
operationId: createWorkflow
requestBody:
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 Nexmo Account Manager. To find out more please visit [nexmo.com/products/messages](https://www.nexmo.com/products/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 Nexmo Account Manager. To find out more please visit [nexmo.com/products/messages](https://www.nexmo.com/products/messages).
**Messenger**: or **Viber**: This value is not required.
MessageProperty:
type: object
required:
- content
properties:
content:
type: object
properties:
type:
description: |
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`.
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: 'Nexmo 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 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.'
type: string
example: 'transaction'
enum:
- transaction
- promotion
ttl:
description: '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.'
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). 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.'
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: 'There are two policies that you can specify when sending an 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.'
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:nexmo: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:
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](https://developer.nexmo.com/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](https://developer.nexmo.com/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
You can’t perform that action at this time.