Send a Message
POST
https://api.nexmo.com/v1/messages
Host
https://api.nexmo.com
POST
/v1/messages
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 |
Send a Message.
The type of message to send. You must provide text in this field
text
The text of message to send; limited to 1000 characters. The Messages API automatically detects unicode characters when sending SMS and sends the message as a unicode SMS. For more information on how concatenation and encoding please visit: developer.nexmo.com/messaging/sms/guides/concatenation-and-encoding.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide sms in this field
sms
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide image in this field
image
The URL of the image attachment.
Supports .jpg, .jpeg, .png and .gif.
Additional text to accompany the image.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide mms in this field
mms
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide vcard in this field
vcard
The URL of the vCard attachment.
Supports .vcf only.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide mms in this field
mms
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide audio in this field.
For best device and network support .mp3 is recommended. Not supported for US short codes.
Must be one of:audio
The URL of the audio attachment.
Additional text to accompany the audio file.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide mms in this field
mms
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide video in this field.
For best device and network support .mp4 is recommended. Not supported for US short codes.
Must be one of:video
The URL of the video attachment.
Additional text to accompany the video file.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide mms in this field
mms
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide text in this field
text
The text of message to send; limited to 4096 characters, including unicode.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide whatsapp in this field
whatsapp
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide image in this field
image
The URL of the image attachment.
Supports .jpg, .jpeg, and .png.
Additional text to accompany the image.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide whatsapp in this field
whatsapp
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide audio in this field
audio
The URL of the audio attachment.
Supports .aac, .m4a, .amr, .mp3 and .opus.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide whatsapp in this field
whatsapp
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide video in this field
video
The URL of the video attachment.
Supports .mp4 and .3gpp. Note, only H.264 video codec and AAC audio codec is supported.
Additional text to accompany the file.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide whatsapp in this field
whatsapp
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide file in this field
file
The URL of the file attachment.
Supports supports a wide range of attachments including .zip, .csv and .pdf.
Additional text to accompany the file.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide whatsapp in this field
whatsapp
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide template in this field
template
The name of the template. For WhatsApp use your WhatsApp namespace (available via Facebook Business Manager), followed by a colon : and the name of the template to use.
The parameters are an array of strings, with the first string being used for {{1}} in the template, with the second being {{2}} etc. Only required if the template specified by name contains parameters.
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide whatsapp in this field
whatsapp
Policy for resolving what language template to use. As of right now the only valid choice is deterministic.
deterministic
The BCP 47 language of the template. See the WhatsApp documentation for supported languages.
Client reference of up to 40 characters. The reference will be present in every message status.
The type of message to send. You must provide custom in this field
custom
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The channel to send to. You must provide whatsapp in this field
whatsapp
Client reference of up to 40 characters. The reference will be present in every message status.
A custom payload, which is passed directly to WhatsApp for certain features such as templates and interactive messages. The schema of a custom object can vary widely. Read more about Custom Objects.
The type of message to send. You must provide text in this field
text
The text of message to send; limited to 640 characters, including unicode.
The ID of the message recipient
The ID of the message sender
The channel to send to. You must provide messenger in this field
messenger
Client reference of up to 40 characters. The reference will be present in every message status.
The text of message to send.
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.
response, update or message_tag
A tag describing the type and relevance of the 1:1 communication between your app and the end user. A full list of available tags is available here
The type of message to send. You must provide image in this field
image
The URL of the image attachment.
Supports .jpg, .jpeg, .png and .gif.
The ID of the message recipient
The ID of the message sender
The channel to send to. You must provide messenger in this field
messenger
Client reference of up to 40 characters. The reference will be present in every message status.
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.
response, update or message_tag
A tag describing the type and relevance of the 1:1 communication between your app and the end user. A full list of available tags is available here
The type of message to send. You must provide audio in this field
audio
The URL of the audio attachment.
Only supports .mp3 files
The ID of the message recipient
The ID of the message sender
The channel to send to. You must provide messenger in this field
messenger
Client reference of up to 40 characters. The reference will be present in every message status.
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.
response, update or message_tag
A tag describing the type and relevance of the 1:1 communication between your app and the end user. A full list of available tags is available here
The type of message to send. You must provide video in this field
video
The URL of the video attachment.
Supports .mp4 files. Note, only H.264 video codec and AAC audio codec is supported.
The ID of the message recipient
The ID of the message sender
The channel to send to. You must provide messenger in this field
messenger
Client reference of up to 40 characters. The reference will be present in every message status.
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.
response, update or message_tag
A tag describing the type and relevance of the 1:1 communication between your app and the end user. A full list of available tags is available here
The type of message to send. You must provide file in this field
file
The URL of the file attachment.
Supports a wide range of attachments including .zip, .csv and .pdf.
The ID of the message recipient
The ID of the message sender
The channel to send to. You must provide messenger in this field
messenger
Client reference of up to 40 characters. The reference will be present in every message status.
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.
response, update or message_tag
A tag describing the type and relevance of the 1:1 communication between your app and the end user. A full list of available tags is available here
The type of message to send. You must provide text in this field
text
The text of message to send; limited to 1000 characters, including unicode.
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.
The ID of the message sender
The channel to send to. You must provide viber_service in this field
viber_service
Client reference of up to 40 characters. The reference will be present in every message status.
The text of message to send.
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 & a targeted message - not promotional. By default Vonage sends the transaction category to Viber Business Messages.
transaction or promotion
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.
Viber-specific type definition. To use "template", please contact your Vonage Account Manager to setup your templates. To find out more please visit the product page
The type of message to send. You must provide image in this field
image
The URL of the image attachment.
Supports .jpg, .jpeg, and .png.
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.
The ID of the message sender
The channel to send to. You must provide viber_service in this field
viber_service
Client reference of up to 40 characters. The reference will be present in every message status.
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 & a targeted message - not promotional. By default Vonage sends the transaction category to Viber Business Messages.
transaction or promotion
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.
Viber-specific type definition. To use "template", please contact your Vonage Account Manager to setup your templates. To find out more please visit the product page
The UUID of the message
The UUID of the message
The UUID of the message
The UUID of the message
The UUID of the message
{
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
"to": "447700900000",
"from": "447700900001",
"channel": "sms"
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
},
"to": "447700900000",
"from": "447700900001",
"channel": "mms"
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg",
"caption": "Additional text to accompany the image."
},
"to": "447700900000",
"from": "447700900001",
"channel": "mms"
}{
"message_type": "vcard",
"vcard": {
"url": "https://example.com/contact.vcf"
},
"to": "447700900000",
"from": "447700900001",
"channel": "mms"
}{
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
},
"to": "447700900000",
"from": "447700900001",
"channel": "mms"
}{
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3",
"caption": "Additional text to accompany the audio file."
},
"to": "447700900000",
"from": "447700900001",
"channel": "mms"
}{
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
},
"to": "447700900000",
"from": "447700900001",
"channel": "mms"
}{
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4",
"caption": "Additional text to accompany the video file."
},
"to": "447700900000",
"from": "447700900001",
"channel": "mms"
}{
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg",
"caption": "Additional text to accompany the image."
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4",
"caption": "Additional text."
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "file",
"file": {
"url": "https://example.com/file.pdf"
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "file",
"file": {
"url": "https://example.com/file.pdf",
"caption": "Additional text."
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "template",
"template": {
"name": "9b6b4fcb_da19_4a26_8fe8_78074a91b584:verify"
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp",
"whatsapp": {
"locale": "en_US"
}
}{
"message_type": "template",
"template": {
"name": "9b6b4fcb_da19_4a26_8fe8_78074a91b584:verify",
"parameters": [
"Verification",
"2526",
"5"
]
},
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp",
"whatsapp": {
"policy": "deterministic",
"locale": "en_US"
}
}{
"message_type": "custom",
"to": "447700900000",
"from": "447700900001",
"channel": "whatsapp"
}{
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
"to": "0123456789",
"from": "9876543210",
"channel": "messenger"
}{
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
"to": "0123456789",
"from": "9876543210",
"channel": "messenger",
"messenger": {
"category": "response",
"tag": "CONFIRMED_EVENT_UPDATE"
}
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger"
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger",
"messenger": {
"category": "response",
"tag": "CONFIRMED_EVENT_UPDATE"
}
}{
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger"
}{
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger",
"messenger": {
"category": "response",
"tag": "CONFIRMED_EVENT_UPDATE"
}
}{
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger"
}{
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger",
"messenger": {
"category": "response",
"tag": "CONFIRMED_EVENT_UPDATE"
}
}{
"message_type": "file",
"file": {
"url": "https://example.com/file.pdf"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger"
}{
"message_type": "file",
"file": {
"url": "https://example.com/file.pdf"
},
"to": "0123456789",
"from": "9876543210",
"channel": "messenger",
"messenger": {
"category": "response",
"tag": "CONFIRMED_EVENT_UPDATE"
}
}{
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
"to": "447700900000",
"from": "9876543210",
"channel": "viber_service"
}{
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
"to": "447700900000",
"from": "9876543210",
"channel": "viber_service",
"viber_service": {
"ttl": 600
}
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
},
"to": "447700900000",
"from": "9876543210",
"channel": "viber_service"
}{
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
},
"to": "447700900000",
"from": "9876543210",
"channel": "viber_service",
"viber_service": {
"ttl": 600
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}{
"type": "https://developer.nexmo.com/api-errors/#unathorized",
"title": "You did not provide correct credentials.",
"detail": "Check that you're using the correct credentials, and that your account has this feature enabled",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/#unprovisioned",
"title": "The crendentials provided do not have access to the requested product",
"detail": "Check your API key is correct and has been whitelisted",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/#low-balance",
"title": "Low balance",
"detail": "This request could not be performed due to your account balance being low.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors#invalid-json",
"title": "The request body did not contain valid JSON",
"detail": "Unexpected character ('\"' (code 34)): was expecting comma to separate Object entries",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1100",
"title": "Unsupported channel",
"detail": "The specified channel is not supported.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1110",
"title": "Invalid channel parameters",
"detail": "The value of one or more parameters is invalid.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
"invalid_parameters": [
{
"name": "messenger.category",
"reason": "Must be one of `response`, `update` or `message_tag`."
}
]
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1120",
"title": "Invalid sender",
"detail": "The `from` parameter is invalid for the given channel.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#110",
"title": "Invalid recipient",
"detail": "The `to` parameter is invalid for the given channel.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1140",
"title": "Invalid message type",
"detail": "The `to` parameter is invalid for the given channel.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1150",
"title": "Invalid params",
"detail": "The value of one or more parameters is invalid.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf",
"invalid_parameters": [
{
"name": "image.url",
"reason": "is required."
}
]
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1060",
"title": "Invalid client reference",
"detail": "The client reference can be a string of up to 40 characters.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1010",
"title": "Rate Limit Hit",
"detail": "Please wait, then retry your request",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}{
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1000",
"title": "Internal error",
"detail": "There was an error processing your request in the Platform.",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
}Webhooks provide information about events happening to the message such as whether it has been sent, delivered or rejected by the provider.
POST
https://example.com/webhooks/message-status
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The status of the message.
One of:submitted, delivered, rejected or undeliverable
The channel sending to.
One of:sms
If the message encountered a problem a descriptive error will be supplied in this object.
The type of error encountered, follow URL for more details
The error code encountered when sending the message. 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 record id of this error's occurrence.
SMS
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
Client reference of up to 40 characters. The reference will be present in every message status.
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The status of the message.
One of:submitted, delivered, rejected or undeliverable
The channel sending to.
One of:mms
If the message encountered a problem a descriptive error will be supplied in this object.
The type of error encountered, follow URL for more details
The error code encountered when sending the message. 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 record id of this error's occurrence.
MMS
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
Client reference of up to 40 characters. The reference will be present in every message status.
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The status of the message.
One of:submitted, delivered, rejected, undeliverable or read
The channel sending to.
One of:whatsapp
If the message encountered a problem a descriptive error will be supplied in this object.
The type of error encountered, follow URL for more details
The error code encountered when sending the message. 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 record id of this error's occurrence.
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number. For WhatsApp this is the default Vonage charge per conversation.
Client reference of up to 40 characters. The reference will be present in every message status.
An object contining meta-data related to the WhatsApp message that triggered this callback. Only present for callbacks with a status of delivered.
An object contining data for the conversation to which the message relates.
The id of the conversation.
An object contining data related to the origin of the conversation.
The conversation type.
The UUID of the message
The ID of the message recipient
The ID of the message sender
The datetime of when the event occurred, in ISO 8601 format.
The status of the message.
One of:submitted, delivered, rejected, undeliverable or read
The channel sending to.
One of:messenger
If the message encountered a problem a descriptive error will be supplied in this object.
The type of error encountered, follow URL for more details
The error code encountered when sending the message. 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 record id of this error's occurrence.
Messenger
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
Client reference of up to 40 characters. The reference will be present in every message status.
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The status of the message.
One of:submitted, delivered, rejected, undeliverable or read
The channel sending to.
One of:viber_service
If the message encountered a problem a descriptive error will be supplied in this object.
The type of error encountered, follow URL for more details
The error code encountered when sending the message. 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 record id of this error's occurrence.
Viber
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
Client reference of up to 40 characters. The reference will be present in every message status.
{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "submitted",
"channel": "sms"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "submitted",
"channel": "sms",
"error": {
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1000",
"title": 1000,
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
},
"usage": {
"currency": "EUR",
"price": "0.0333"
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "submitted",
"channel": "mms"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "submitted",
"channel": "mms",
"error": {
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1000",
"title": 1000,
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
},
"usage": {
"currency": "EUR",
"price": "0.0333"
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "read",
"channel": "whatsapp"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "read",
"channel": "whatsapp",
"error": {
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1000",
"title": 1000,
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
},
"usage": {
"currency": "EUR",
"price": "0.0333"
},
"whatsapp": {
"conversation": {
"id": "1234567890",
"origin": {
"type": "user_initiated"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "read",
"channel": "messenger"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "read",
"channel": "messenger",
"error": {
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1000",
"title": 1000,
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
},
"usage": {
"currency": "EUR",
"price": "0.0333"
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "read",
"channel": "viber_service"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"status": "read",
"channel": "viber_service",
"error": {
"type": "https://developer.nexmo.com/api-errors/messages-olympus#1000",
"title": 1000,
"detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
"instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
},
"usage": {
"currency": "EUR",
"price": "0.0333"
}
}Webhooks are an extension of an API, but instead of your code requesting data, the API sends data to you. The data arrives in a web request to your application.
To learn more about webhooks, see our webhooks documentation
This API may send any of the webhooks documented below to the URL that you have configured. You must respond with a 200 or 204 HTTP response, or the requests will be retried
An inbound message from a customer to you.
POST
https://example.com/webhooks/inbound-message
The channel the message came in on
One of:sms
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The UTF-8 encoded text of the inbound message.
Channel specific metadata for SMS
The number of inbound SMS messages concatenated together to comprise this message. SMS messages are 160 characters, if an inbound message exceeds that size they are concatenated together to forma single message. This number indicates how many messages formed this webhook.
The first word of the message sent to uppercase.
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
The channel the message came in on
One of:mms
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide image in this field
image
The publicly accessible URL of the image attachment. The image file is available for 48 hours after it is created. Supported types are .jpg, .jpeg, and .png
Client reference of up to 40 characters. The reference will be present in every message status.
The channel the message came in on
One of:mms
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide vcard in this field
vcard
The publicly accessible URL of the vCard attachment. Supported types are .vcf only
Client reference of up to 40 characters. The reference will be present in every message status.
The channel the message came in on
One of:mms
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide audio in this field
audio
Publicly accessible URL of the audio attachment.
Client reference of up to 40 characters. The reference will be present in every message status.
The channel the message came in on
One of:mms
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide video in this field
video
Publicly accessible URL of the video attachment.
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:whatsapp
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide text in this field
text
The text of message to send.
The text of message to send.
The WhatsApp number's displayed profile name
This is only present for the Inbound Message where the user is quoting another message. It provides information about the quoted message.
The UUID of the message being replied to
The phone number of the original sender of the message being replied to in the E.164 format.
A message from the channel provider, which may contain a description, error codes or other information
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:whatsapp
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide image in this field
image
The publicly accessible URL of the image attachment. The image file is available for 48 hours after it is created. Supported types are .jpg, .jpeg, and .png
The WhatsApp number's displayed profile name
This is only present for the Inbound Message where the user is quoting another message. It provides information about the quoted message.
The UUID of the message being replied to
The phone number of the original sender of the message being replied to in the E.164 format.
A message from the channel provider, which may contain a description, error codes or other information
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:whatsapp
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide video in this field
video
Publicly accessible URL of the video attachment. Supports file types .mp4 and .3gpp
Note: Only supports video codec H.264 and audio codec AAC
The WhatsApp number's displayed profile name
This is only present for the Inbound Message where the user is quoting another message. It provides information about the quoted message.
The UUID of the message being replied to
The phone number of the original sender of the message being replied to in the E.164 format.
A message from the channel provider, which may contain a description, error codes or other information
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:whatsapp
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide file in this field
file
The WhatsApp number's displayed profile name
This is only present for the Inbound Message where the user is quoting another message. It provides information about the quoted message.
The UUID of the message being replied to
The phone number of the original sender of the message being replied to in the E.164 format.
A message from the channel provider, which may contain a description, error codes or other information
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:whatsapp
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide audio in this field
audio
The WhatsApp number's displayed profile name
This is only present for the Inbound Message where the user is quoting another message. It provides information about the quoted message.
The UUID of the message being replied to
The phone number of the original sender of the message being replied to in the E.164 format.
A message from the channel provider, which may contain a description, error codes or other information
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:whatsapp
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide custom in this field.
reply
An identifier to help identify the exact interactive message response.
The title displayed on the interactive option chosen.
A description that may be added to the interactive options presented (available only on interactive lists).
The WhatsApp number's displayed profile name
This is only present for the Inbound Message where the user is quoting another message. It provides information about the quoted message.
The UUID of the message being replied to
The phone number of the original sender of the message being replied to in the E.164 format.
A message from the channel provider, which may contain a description, error codes or other information
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:whatsapp
The UUID of the message
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.
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. Will be unsupported if the type of message received from user is not supported by the channel.
unsupported
The WhatsApp number's displayed profile name
This is only present for the Inbound Message where the user is quoting another message. It provides information about the quoted message.
The UUID of the message being replied to
The phone number of the original sender of the message being replied to in the E.164 format.
A message from the channel provider, which may contain a description, error codes or other information
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:messenger
The UUID of the message
The ID of the message recipient
The ID of the message sender
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide text in this field
text
The text of message to send.
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:messenger
The UUID of the message
The ID of the message recipient
The ID of the message sender
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide image in this field
image
The publicly accessible URL of the image attachment. The image file is available for 48 hours after it is created. Supported types are .jpg, .jpeg, and .png
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:messenger
The UUID of the message
The ID of the message recipient
The ID of the message sender
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide video in this field
video
Publicly accessible URL of the video attachment. Supports file types .mp4 and .3gpp
Note: Only supports video codec H.264 and audio codec AAC
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:messenger
The UUID of the message
The ID of the message recipient
The ID of the message sender
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide file in this field
file
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:messenger
The UUID of the message
The ID of the message recipient
The ID of the message sender
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide audio in this field
audio
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:messenger
The UUID of the message
The ID of the message recipient
The ID of the message sender
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. Will be unsupported if the type of message received from user is not supported by the channel.
unsupported
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:viber_service
The UUID of the message
The ID of the message recipient
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide text in this field
text
The text of message to send.
Client reference of up to 40 characters. The reference will be present in every message status.
The channel that the message came in on
One of:viber_service
The UUID of the message
The ID of the message recipient
The phone number of the message sender 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. For SMS in certain localities alpha-numeric sender id's will work as well, see Global Messaging for more details
The datetime of when the event occurred, in ISO 8601 format.
The type of message to send. You must provide image in this field
image
The publicly accessible URL of the image attachment. The image file is available for 48 hours after it is created. Supported types are .jpg, .jpeg, and .png
Client reference of up to 40 characters. The reference will be present in every message status.
{
"channel": "sms",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"text": "Hello From Vonage!"
}{
"channel": "sms",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"text": "Hello From Vonage!",
"sms": {
"num_messages": "2",
"keyword": "HELLO"
},
"usage": {
"currency": "EUR",
"price": "0.0333"
}
}{
"channel": "mms",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}{
"channel": "mms",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "vcard",
"vcard": {
"url": "https://example.com/conatact.vcf"
}
}{
"channel": "mms",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}{
"channel": "mms",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes."
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
"profile": {
"name": "Jane Smith"
},
"context": {
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"message_from": "447700900000"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
},
"profile": {
"name": "Jane Smith"
},
"context": {
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"message_from": "447700900000"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
},
"profile": {
"name": "Jane Smith"
},
"context": {
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"message_from": "447700900000"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "file",
"file": {
"url": "https://example.com/file.pdf"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "file",
"file": {
"url": "https://example.com/file.pdf"
},
"profile": {
"name": "Jane Smith"
},
"context": {
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"message_from": "447700900000"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
},
"profile": {
"name": "Jane Smith"
},
"context": {
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"message_from": "447700900000"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "reply",
"reply": {
"id": "row1",
"title": "9am"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "reply",
"reply": {
"id": "row1",
"title": "9am",
"description": "Select 9am appointmaent time"
},
"profile": {
"name": "Jane Smith"
},
"context": {
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"message_from": "447700900000"
}
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "unsupported"
}{
"channel": "whatsapp",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "447700900000",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "unsupported",
"profile": {
"name": "Jane Smith"
},
"context": {
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"message_from": "447700900000"
}
}{
"channel": "messenger",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes."
}{
"channel": "messenger",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}{
"channel": "messenger",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}{
"channel": "messenger",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "file",
"file": {
"url": "https://example.com/file.pdf"
}
}{
"channel": "messenger",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}{
"channel": "messenger",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "9876543210",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "unsupported"
}{
"channel": "viber_service",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "text",
"text": "Nexmo Verification code: 12345. Valid for 10 minutes."
}{
"channel": "viber_service",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": "0123456789",
"from": "447700900001",
"timestamp": "2020-01-01 14:00:00 +0000",
"message_type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}The following is a non-exhaustive list of error codes that may occur while using this API. These codes are in addition to any of our generic error codes.
| Code | Details |
|---|---|
| 1000 | Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry |
| 1010 | Missing params - Your request is incomplete and missing some mandatory parameters. |
| 1020 | Invalid params - The value of one or more parameters is invalid. |
| 1021 | Invalid tag - The tag value is invalid. |
| 1022 | Invalid template - Invalid template or template parameters |
| 1030 | Internal error - There was an error processing your request in the Platform. |
| 1040 | Invalid message - The Platform was unable to process your request. For example, due to an unrecognised prefix for the phone number. |
| 1050 | Number barred - The number you are trying to submit to is blacklisted and may not receive messages. |
| 1060 | Partner account barred - The |
| 1070 | Partner quota exceeded - Your pre-paid account does not have sufficient credit to process this message. |
| 1080 | Account not enabled for REST - This account is not provisioned for REST submission, you should use SMPP on the SMS API. |
| 1090 | Message too long - The length of |
| 1100 | Communication Failed - Message was not submitted because there was a communication failure. |
| 1120 | Illegal Sender Address - rejected - Due to local regulations, the |
| 1130 | Invalid TTL - The value of |
| 1140 | Facility not allowed - Your request makes use of a facility that is not enabled on your account. |
| 1150 | Invalid Message class - The value of |
| 1160 | Non White-listed Destination - The phone number you set in to is not in your pre-approved destination list. To send messages to this phone number, add it using Dashboard. |
| 1170 | Invalid or Missing Msisdn Param - The phone number you supplied in the to parameter of your request was either missing or invalid. |
| 1180 | Absent Subscriber Temporary - This message was not delivered because to was temporarily unavailable. For example, the handset used for to was out of coverage or switched off. This is a temporary failure, retry later for a positive result. |
| 1190 | Absent Subscriber Permanent - |
| 1200 | Portability Error - There is an issue after the user has changed carrier for to. If the user wants to receive messages from you, they need to contact their carrier directly. |
| 1210 | Anti-Spam Rejection - Carriers often apply restrictions that block messages following different criteria. For example on SenderID or message content. |
| 1220 | Handset Busy - The handset associated with to was not available when this message was sent. If status is rejected, this is a temporary failure; retry later for a positive result. If status is submitted, this message has is in the retry scheme and will be resent until it expires in 24-48 hours. |
| 1230 | Network Error - A network failure while sending your message. This is a temporary failure, retry later for a positive result. |
| 1240 | Illegal Number - You tried to send a message to a blacklisted phone number. That is, the user has already sent a STOP opt-out message and no longer wishes to receive messages from you. |
| 1241 | Too many send requests - Too many send requests to phone numbers. |
| 1250 | Unroutable - The chosen route to send your message is not available. This is because the phone number is either currently on an unsupported network or on a pre-paid or reseller account that could not receive a message sent by from. To resolve this issue either email us at support@nexmo.com or create a helpdesk ticket at https://help.nexmo.com. |
| 1260 | Destination unreachable - The message could not be delivered to the phone number. If using Viber Business Messages your account might not be enabled for this country. |
| 1270 | Subscriber Age Restriction - The carrier blocked this message because the content is not suitable for to based on age restrictions. |
| 1280 | Number Blocked by Carrier - The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended. |
| 1290 | Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message. |
| 1300 | Not part of the provider network - The number or ID is not a user in the provider network. |
| 1310 | Not suitable device - The user's device can't receive the message. |
| 1320 | Message already sent - The message was already sent. |
| 1330 | Unknown - An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid. |
| 1331 | Provider error - The provider is not responding or unable to process the request. Please try sending your message in a few minutes time. |
| 1340 | Outside of the allowed window - This message is sent outside of allowed response window. |
| 1350 | Phone matching fee not paid - Requires phone matching access fee to be paid by the Facebook Page. |
| 1360 | TTL was activated - TTL was activated, no callbacks and no charge will be issued. |
| 1370 | Expired access Token - Please reauthenticate your Facebook Page with Vonage. |
| 1380 | Invalid resource - Please check that the URL your provided to your resource is accessible and valid. |
| 1381 | Resource size is too large - Please try sending a smaller media file. |
| 1382 | Resource type is invalid - Please check that the file you are trying to send is valid. |
| 1400 | Unsupported channel - The channel specified in the request is not supported. |
| 1410 | Invalid channel parameters - The value of one or more parameters is invalid. |
| 1420 | Invalid sender - The |
| 1430 | Invalid recipient - The |
| 1440 | Invalid message type - The message type specified in the request is not supported for the given channel. |
| 1450 | Invalid client reference - The client reference can be a string of up to 40 characters. |