The Messages API enables you to send messages to customers via their preferred channels (currently Facebook Messenger, WhatsApp, Viber, and SMS/MMS) using a single API. The Messages API is currently in Beta.
Send a Message over SMS, WhatsApp, Viber, Facebook Messenger, or MMS
POST
https://api.nexmo.com/v0.1/messages
Host
https://api.nexmo.com
POST
/v0.1/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 channel the message is going to.
Must be one of:sms
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 channel the message is coming from
Must be one of:sms
The Vonage Virtual number the message is originating from 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 content type of the message
Must be one of:text
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.
client reference up to 40 characters, the reference will be present in every message status
Channel the message is going to
Must be one of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
Must be one of:whatsapp
WhatsApp Number the message is to be sent from.
Content of the whatsapp message
The type of message that you are sending
Must be one of:text
Text Message limited to 4096 characters, including unicode.
client reference up to 40 characters, the reference will be present in every message status
Channel the message is going to
Must be one of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
Must be one of:whatsapp
WhatsApp Number the message is to be sent from.
the type of message that you are sending
Must be one of:template
The Template request object to be sent to WhatsApp.
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. The first value being {{1}} in the template.
The BCP 47 language of the template. Vonage will translate the BCP 47 format to the WhatsApp equivalent. For examples en-GB will be auto-translate to en_GB.
Policy for resolving what language template to use. Please note that WhatsApp deprecated the fallback policy in January of 2020, all requests carrying a fallback policy will be rejected with a 400 error
deterministic
client reference up to 40 characters, the reference will be present in every message status
Channel the message is going to
Must be one of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
Must be one of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message that you are sending
Must be one of:image
image content object
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
Additional text to accompany the image.
client reference up to 40 characters, the reference will be present in every message status
Channel the message is going to
Must be one of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
Must be one of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message that you are sending
Must be one of:video
the video content object for the WhatsApp request
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 up to 40 characters, the reference will be present in every message status
Channel the message is going to
Must be one of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
Must be one of:whatsapp
WhatsApp Number the message is to be sent from.
the type of message that you are sending
Must be one of:audio
The audio content object for the request
The publicly accessible URL of the audio attachment. The audio file is available for 48 hours after it is created. Supports .aac, .m4a, .amr, .mp3 and .opus
client reference up to 40 characters, the reference will be present in every message status
Channel the message is going to
Must be one of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
Must be one of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message that you are sending.
Must be one of:file
The file content object to be sent.
The publicly accessible URL of the file to be sent. Supports .pdf, .doc(x), .ppt(x), and .xls(x)
Additional text to accompany the file.
client reference up to 40 characters, the reference will be present in every message status
The channel you are sending to
Must be one of:viber_service_msg
The Viber 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 channel your message will be coming from.
Must be one of:viber_service_msg
This is your Service Message ID given to you by your Vonage Account Manager. To find out more please visit vonage.com.
The type of message being sent
Must be one of:text
Text to be sent to the user, limited to 1000 characters, including unicode.
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 & a targeted message - not promotional. By default Vonage sends the transaction category to Viber Service 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 Vonage Account Manager to setup your templates. To find out more please visit vonage.com/products/messages.
client reference up to 40 characters, the reference will be present in every message status
The channel you are sending to
Must be one of:viber_service_msg
The Viber 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 channel your message will be coming from.
Must be one of:viber_service_msg
This is your Service Message ID given to you by your Vonage Account Manager. To find out more please visit vonage.com.
The type of message being sent
Must be one of:image
Image content to be sent
Publicly accessible URL of the image to be attached. The image file is available for 48 hours after it's created. Supports .jpg, .jpeg, and .png.
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 & a targeted message - not promotional. By default Vonage sends the transaction category to Viber Service 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 Vonage Account Manager to setup your templates. To find out more please visit vonage.com/products/messages.
client reference up to 40 characters, the reference will be present in every message status
The channel you are sending to
Must be one of:viber_service_msg
The Viber 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 channel your message will be coming from.
Must be one of:viber_service_msg
This is your Service Message ID given to you by your Vonage Account Manager. To find out more please visit vonage.com.
The type of message you are sending
Must be one of:template
The template to be sent.
The name of the template to be sent
The parameters are an array. The first value being {{1}} in the template.
The use of different category tags enables the business to send messages for different use cases. For Viber Service Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Vonage sends the transaction category to Viber Service 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 Vonage Account Manager to setup your templates. To find out more please visit vonage.com/products/messages.
client reference up to 40 characters, the reference will be present in every message status
The channel that you are sending to
Must be one of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
Must be one of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
Must be one of:text
The text to be sent to the recipient's Facebook Messenger account.
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 full list of the possible tags is available on developers.facebook.com
client reference up to 40 characters, the reference will be present in every message status
The channel that you are sending to
Must be one of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
Must be one of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
Must be one of:image
The image content being sent to the recipient.
The URL of the image attachment. The image file is available for 48 hours after it is created. Supported types are .jpg, .jpeg, .png, and .gif
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 full list of the possible tags is available on developers.facebook.com
client reference up to 40 characters, the reference will be present in every message status
The channel that you are sending to
Must be one of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
Must be one of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
Must be one of:video
The video content being sent to the recipient.
The URL of the video attachment. Supports .mp4.
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 full list of the possible tags is available on developers.facebook.com
client reference up to 40 characters, the reference will be present in every message status
The channel that you are sending to
Must be one of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
Must be one of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
Must be one of:audio
The audio content being sent to the recipient.
The URL of the audio attachment. Supports .mp3.
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 full list of the possible tags is available on developers.facebook.com
client reference up to 40 characters, the reference will be present in every message status
The channel that you are sending to
Must be one of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
Must be one of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
Must be one of:file
The file content being sent to the recipient.
The URL of the file attachment. Supports .zip, .csv, and .pdf
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 full list of the possible tags is available on developers.facebook.com
client reference up to 40 characters, the reference will be present in every message status
The channel the message is going to
Must be one of:mms
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 channel the message is coming from
Must be one of:mms
A US shortcode
The type of message to be sent
Must be one of:image
The URL of the image attachment. The image file is available for 48 hours after it is created. Supported file types are .jpg, .jpeg, .png, and .gif
client reference up to 40 characters, the reference will be present in every message status
The UUID of the message.
{
"to": {
"type": "sms",
"number": "447700900000"
},
"from": {
"type": "sms",
"number": "447700900001"
},
"message": {
"content": {
"type": "text",
"text": "Hello From Vonage!"
}
}
}{
"to": {
"type": "sms",
"number": "447700900000"
},
"from": {
"type": "sms",
"number": "447700900001"
},
"message": {
"content": {
"type": "text",
"text": "Hello From Vonage!"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "text",
"text": "Hello From Vonage!"
}
}
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "text",
"text": "Hello From Vonage!"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "template",
"template": {
"name": "example_namespace':'verify"
}
},
"whatsapp": {
"locale": "en-GB"
}
}
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "template",
"template": {
"name": "example_namespace':'verify",
"parameters": [
"Daisy",
"12345"
]
}
},
"whatsapp": {
"locale": "en-GB",
"policy": "deterministic"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/cat.jpg"
}
}
}
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/cat.jpg",
"caption": "My Tabby cat, Oliver."
}
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}
}
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}
}
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "file",
"file": {
"url": "https://example.com/file.pdf"
}
}
}
}{
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "file",
"file": {
"url": "https://example.com/file.pdf",
"caption": "An important report"
}
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "viber_service_msg",
"number": "447700900000"
},
"from": {
"type": "viber_service_msg",
"id": "654321"
},
"message": {
"content": {
"type": "text",
"text": "Hello from Vonage!"
}
}
}{
"to": {
"type": "viber_service_msg",
"number": "447700900000"
},
"from": {
"type": "viber_service_msg",
"id": "654321"
},
"message": {
"content": {
"type": "text",
"text": "Hello from Vonage!"
},
"viber_service_msg": {
"category": "transaction",
"ttl": 600,
"type": "template"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "viber_service_msg",
"number": "447700900000"
},
"from": {
"type": "viber_service_msg",
"id": "654321"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}
}
}{
"to": {
"type": "viber_service_msg",
"number": "447700900000"
},
"from": {
"type": "viber_service_msg",
"id": "654321"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
},
"viber_service_msg": {
"category": "transaction",
"ttl": 600,
"type": "template"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "viber_service_msg",
"number": "447700900000"
},
"from": {
"type": "viber_service_msg",
"id": "654321"
},
"message": {
"content": {
"type": "template",
"template": {
"name": "verify"
}
}
}
}{
"to": {
"type": "viber_service_msg",
"number": "447700900000"
},
"from": {
"type": "viber_service_msg",
"id": "654321"
},
"message": {
"content": {
"type": "template",
"template": {
"name": "verify",
"parameters": [
"Daisy",
"12345"
]
}
},
"viber_service_msg": {
"category": "transaction",
"ttl": 600,
"type": "template"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "text",
"text": "Hello from Vonage!"
}
}
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "text",
"text": "Hello from Vonage!"
},
"messenger": {
"category": "update",
"tag": "CONFIRMED_EVENT_UPDATE"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}
}
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
},
"messenger": {
"category": "update",
"tag": "CONFIRMED_EVENT_UPDATE"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}
}
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
},
"messenger": {
"category": "update",
"tag": "CONFIRMED_EVENT_UPDATE"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}
}
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
},
"messenger": {
"category": "update",
"tag": "CONFIRMED_EVENT_UPDATE"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "file",
"file": {
"url": "https://example.com/file.zip"
}
}
}
}{
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "file",
"file": {
"url": "https://example.com/file.zip"
}
},
"messenger": {
"category": "update",
"tag": "CONFIRMED_EVENT_UPDATE"
}
},
"client_ref": "client-ref2"
}{
"to": {
"type": "mms",
"number": "447700900000"
},
"from": {
"type": "mms",
"number": "12345"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}
}
}{
"to": {
"type": "mms",
"number": "447700900000"
},
"from": {
"type": "mms",
"number": "12345"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}
},
"client_ref": "client-ref2"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}{
"type": "https://www.nexmo.com/messages/Errors#InvalidParams",
"title": "Invalid Parameters",
"detail": "Your request parameters did not validate.",
"instance": "f94b4e56604e07e5e5ad5a7228618f81"
}Webhooks to inform about events happening to the message at communication level (has it been delivered, rejected by the provider...).
POST
https://example.com/webhooks/message-status
The UUID of the message.
The type of message that you want to send.
One of:sms, viber_service_msg, messenger, whatsapp or mms
Messenger: The ID of the message recipient. This value should be the from.id value you received in the inbound messenger event.
SMS, Viber, WhatsApp or MMS: 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 type of message that you want to send.
One of:sms, viber_service_msg, messenger, whatsapp or mms
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 your Vonage Account Manager. To find out more please visit vonage.com.
SMS: 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.
WhatsApp: This is your WhatsApp Business Number given to you by your Vonage Account Manager. To find out more please visit vonage.com.
MMS: US shortcode
The datetime of when the event occurred.
The status of the message. The read message status is available for messenger, whatsapp and viber.
submitted, delivered, read, rejected or undeliverable
The error code. See our errors list for a list of possible errors
Text describing the error. See our errors list for a list of possible errors
The charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
The client's reference.
{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": {
"type": "sms"
},
"from": {
"type": "sms"
},
"timestamp": "2020-01-01T14:00:00.000Z",
"status": "delivered"
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"to": {
"type": "sms",
"id": "0123456789012345",
"number": "447700900000"
},
"from": {
"type": "sms",
"id": "0123456789012345",
"number": "447700900000"
},
"timestamp": "2020-01-01T14:00:00.000Z",
"status": "delivered",
"error": {
"code": 1300,
"reason": "Not part of the provider network"
},
"usage": {
"currency": "EUR",
"price": "0.0333"
},
"client_ref": "my-personal-reference"
}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 UUID of the message.
The datetime of when the event occurred.
The channel the message is going to.
One of:sms
The Vonage Virtual number the sms is being sent to in the E.164 format.
The channel the message is coming from
One of:sms
The phone number the message is originating from in the E.164 format.
The content type of the message
One of:text
The UTF-8 encoded text of the inbound message.
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 charge currency in ISO 4217 format.
One of:EUR
The charge amount as a stringified number.
The UUID of the message.
The datetime of when the event occurred.
Channel the message is going to
One of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
One of:whatsapp
WhatsApp Number the message is to be sent from.
Content of the whatsapp message
The type of message that you are sending
One of:text
Text Message limited to 4096 characters, including unicode.
The UUID of the message.
The datetime of when the event occurred.
Channel the message is going to
One of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
One of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message that you are sending
One of:image
image content object
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
Additional text to accompany the image.
The UUID of the message.
The datetime of when the event occurred.
Channel the message is going to
One of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
One of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message that you are sending
One of:video
the video content object for the WhatsApp request
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 UUID of the message.
The datetime of when the event occurred.
Channel the message is going to
One of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
One of:whatsapp
WhatsApp Number the message is to be sent from.
the type of message that you are sending
One of:audio
The audio content object for the request
The publicly accessible URL of the audio attachment. The audio file is available for 48 hours after it is created. Supports .aac, .m4a, .amr, .mp3 and .opus
The UUID of the message.
The datetime of when the event occurred.
Channel the message is going to
One of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
One of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message that you are sending.
One of:file
The file content object to be sent.
The publicly accessible URL of the file to be sent. Supports .pdf, .doc(x), .ppt(x), and .xls(x)
Additional text to accompany the file.
The UUID of the message.
The datetime of when the event occurred.
Channel the message is going to
One of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
One of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message that you are sending
One of:location
location content object
The longitude of the location
The latitude of the location
Name of the Location.
The address of the location, only displays if name is present
The UUID of the message.
The datetime of when the event occurred.
Channel the message is going to
One of:whatsapp
The WhatsApp 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.
Channel the message is going to be sent from.
One of:whatsapp
WhatsApp Number the message is to be sent from.
The type of message will be unsupported if a message is received is of an unsupported type
unsupported
The UUID of the message.
The datetime of when the event occurred.
The channel you are sending to
One of:viber_service_msg
This is your Service Message ID given to you by Vonage Account Manager. To find out more please visit vonage.com/products/messages.
The channel your message will be coming from.
One of:viber_service_msg
The Viber 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 type of message being sent
One of:text
Text to be sent to the user, limited to 1000 characters, including unicode.
The UUID of the message.
The datetime of when the event occurred.
The channel you are sending to
One of:viber_service_msg
This is your Service Message ID given to you by Vonage Account Manager. To find out more please visit vonage.com/products/messages.
The channel your message will be coming from.
One of:viber_service_msg
The Viber 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 type of message will be unsupported if a message is received is of an unsupported type
unsupported
The UUID of the message.
The datetime of when the event occurred.
The channel that you are sending to
One of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
One of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
One of:text
The text to be sent to the recipient's Facebook Messenger account.
The UUID of the message.
The datetime of when the event occurred.
The channel that you are sending to
One of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
One of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
One of:image
The image content being sent to the recipient.
The URL of the image attachment. The image file is available for 48 hours after it is created. Supported types are .jpg, .jpeg, .png, and .gif
The UUID of the message.
The datetime of when the event occurred.
The channel that you are sending to
One of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
One of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
One of:video
The video content being sent to the recipient.
The URL of the video attachment. Supports .mp4.
The UUID of the message.
The datetime of when the event occurred.
The channel that you are sending to
One of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
One of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
One of:audio
The audio content being sent to the recipient.
The URL of the audio attachment. Supports .mp3.
The UUID of the message.
The datetime of when the event occurred.
The channel that you are sending to
One of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
One of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message being sent.
One of:file
The file content being sent to the recipient.
The URL of the file attachment. Supports .zip, .csv, and .pdf
The UUID of the message.
The datetime of when the event occurred.
The channel that you are sending to
One of:messenger
The ID of the Message recipient. This value should be the from.id value you receive on an inbound message from messenger
The channel that you are sending from
One of:messenger
This value should be the to.id value you received in the inbound messenger event. Can also be found using your account dashboard when trying to link external accounts to your applications.
The type of message will be unsupported if a message is received is of an unsupported type
unsupported
The UUID of the message.
The datetime of when the event occurred.
The channel the message is going to
One of:mms
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 channel the message is coming from
One of:mms
A US shortcode
The type of message to be sent
One of:image
The URL of the image attachment. The image file is available for 48 hours after it is created. Supported file types are .jpg, .jpeg, .png, and .gif
{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "sms",
"number": "447700900000"
},
"from": {
"type": "sms",
"number": "447700900001"
},
"message": {
"content": {
"type": "text",
"text": "Hello From Vonage!"
},
"sms": {
"num_messages": "2"
}
},
"usage": {
"currency": "EUR",
"price": "0.0333"
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "text",
"text": "Hello From Vonage!"
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/cat.jpg"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/cat.jpg",
"caption": "My Tabby cat, Oliver."
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "file",
"file": {
"url": "https://example.com/file.pdf"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "file",
"file": {
"url": "https://example.com/file.pdf",
"caption": "An important report"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "location",
"location": {
"longitude": "-122.425332",
"latitude": "37.758056"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "location",
"location": {
"longitude": "-122.425332",
"latitude": "37.758056",
"name": "Facebook HQ",
"address": "1 Hacker Way, Menlo Park, CA 94025"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "whatsapp",
"number": "447700900000"
},
"from": {
"type": "whatsapp",
"number": "447700900001"
},
"message": {
"content": {
"type": "unsupported"
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "viber_service_msg",
"id": "654321"
},
"from": {
"type": "viber_service_msg",
"number": "447700900000"
},
"message": {
"content": {
"type": "text",
"text": "Hello from Vonage!"
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "viber_service_msg",
"id": "654321"
},
"from": {
"type": "viber_service_msg",
"number": "447700900000"
},
"message": {
"content": {
"type": "unsupported"
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "text",
"text": "Hello from Vonage!"
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "image",
"image": {
"url": "https://example.com/image.jpg"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "video",
"video": {
"url": "https://example.com/video.mp4"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "audio",
"audio": {
"url": "https://example.com/audio.mp3"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "file",
"file": {
"url": "https://example.com/file.zip"
}
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "messenger",
"id": "123456789987"
},
"from": {
"type": "messenger",
"id": "123456789987"
},
"message": {
"content": {
"type": "unsupported"
}
}
}{
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2020-01-01T14:00:00.000Z",
"to": {
"type": "mms",
"number": "447700900000"
},
"from": {
"type": "mms",
"number": "12345"
},
"message": {
"content": {
"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 Service 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 resrouce is accesible 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. |