Available Operations Webhooks Errors
 
 

Messages API

The Messages API consolidates and normalises exchanges across all messaging channels. It allows you to use a single API to interact with our various channels such as SMS, MMS, WhatsApp, Viber and Facebook Messenger

Available Operations:

There are multiple versions of this API available

Version 0 | Version 1

Send a message to the given channel.

Send a Message

POST https://api.nexmo.com/v1/messages
Host https://api.nexmo.com
POST /v1/messages

Authentication

This API supports both JWT and Basic authentication. Basic authentication is easier to get started with, but does not support advanced features such as ACLs.

You can use either JWT or Basic authentication, but not both at the same time.

Key Description Example Default
Authorization Your JSON web token.
Read more about JWTs
Bearer <JWT> None
Authorization Base64 encoded API key and secret joined by a colon.
Read more
Basic <base64> None

Request body application/json

Send a Message.

message_type
string | Required

The type of message to send. You must provide text in this field

Must be one of: text
text
string | Required

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.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide sms in this field

Must be one of: sms
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide image in this field

Must be one of: image
image
object | Required
url
string (url) | Required

The URL of the image attachment.

Supports .jpg, .jpeg, .png and .gif.

caption
string | Min: 1 | Max: 2000

Additional text to accompany the image.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide mms in this field

Must be one of: mms
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide vcard in this field

Must be one of: vcard
vcard
object | Required
url
string (url) | Required

The URL of the vCard attachment.

Supports .vcf only.

caption
string | Min: 1 | Max: 2000

Additional text to accompany the vCard.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide mms in this field

Must be one of: mms
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide text in this field

Must be one of: text
text
string | Required

The text of message to send; limited to 4096 characters, including unicode.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide whatsapp in this field

Must be one of: whatsapp
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide image in this field

Must be one of: image
image
object | Required
url
string (url) | Required

The URL of the image attachment.

Supports .jpg, .jpeg, and .png.

caption
string | Min: 1 | Max: 3000

Additional text to accompany the image.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide whatsapp in this field

Must be one of: whatsapp
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide audio in this field

Must be one of: audio
audio
object | Required
url
string | Required | Min: 10 | Max: 2000

The URL of the audio attachment.

Supports .aac, .m4a, .amr, .mp3 and .opus.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide whatsapp in this field

Must be one of: whatsapp
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide video in this field

Must be one of: video
video
object | Required
url
string (url) | Required

The URL of the video attachment.

Supports .mp4 and .3gpp. Note, only H.264 video codec and AAC audio codec is supported.

caption
string

Additional text to accompany the file.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide whatsapp in this field

Must be one of: whatsapp
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide file in this field

Must be one of: file
file
object | Required
url
string | Required

The URL of the file attachment.

Supports supports a wide range of attachments including .zip, .csv and .pdf.

caption
string

Additional text to accompany the file.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide whatsapp in this field

Must be one of: whatsapp
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide template in this field

Must be one of: template
template
object | Required
name
string | Required

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.

parameters
array of strings

The parameters are an array of strings. The first value being {{1}} in the template.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide whatsapp in this field

Must be one of: whatsapp
whatsapp
object | Required
policy
string | Required

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. As of right now the only valid choice is deterministic

Must be one of: deterministic
locale
string | Required

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.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_type
string | Required

The type of message to send. You must provide custom in this field

Must be one of: custom
to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

channel
string | Required

The channel to send to. You must provide whatsapp in this field

Must be one of: whatsapp
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

custom
object

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.

message_type
string | Required

The type of message to send. You must provide text in this field

Must be one of: text
text
string | Required

The text of message to send; limited to 640 characters, including unicode.

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

channel
string | Required

The channel to send to. You must provide messenger in this field

Must be one of: messenger
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

messenger
object

The text of message to send.

category
string

The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their Messaging Types policy. 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.

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

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

message_type
string | Required

The type of message to send. You must provide image in this field

Must be one of: image
image
object | Required
url
string (url) | Required

The URL of the image attachment.

Supports .jpg, .jpeg, .png and .gif.

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

channel
string | Required

The channel to send to. You must provide messenger in this field

Must be one of: messenger
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

messenger
object
category
string

The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their Messaging Types policy. 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.

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

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

message_type
string | Required

The type of message to send. You must provide audio in this field

Must be one of: audio
audio
object | Required
url
string | Required | Min: 10 | Max: 2000

The URL of the audio attachment.

Only supports .mp3 files

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

channel
string | Required

The channel to send to. You must provide messenger in this field

Must be one of: messenger
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

messenger
object
category
string

The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their Messaging Types policy. 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.

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

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

message_type
string | Required

The type of message to send. You must provide video in this field

Must be one of: video
video
object | Required
url
string (url) | Required

The URL of the video attachment.

Supports .mp4 files. Note, only H.264 video codec and AAC audio codec is supported.

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

channel
string | Required

The channel to send to. You must provide messenger in this field

Must be one of: messenger
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

messenger
object
category
string

The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their Messaging Types policy. 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.

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

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

message_type
string | Required

The type of message to send. You must provide file in this field

Must be one of: file
file
object | Required
url
string | Required

The URL of the file attachment.

Supports a wide range of attachments including .zip, .csv and .pdf.

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

channel
string | Required

The channel to send to. You must provide messenger in this field

Must be one of: messenger
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

messenger
object
category
string

The use of different category tags enables the business to send messages for different use cases. For Facebook Messenger they need to comply with their Messaging Types policy. 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.

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

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

message_type
string | Required

The type of message to send. You must provide text in this field

Must be one of: text
text
string | Required

The text of message to send; limited to 1000 characters, including unicode.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

channel
string | Required

The channel to send to. You must provide viber_service in this field

Must be one of: viber_service
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

viber_service
object

The text of message to send.

category
string

The use of different category tags enables the business to send messages for different use cases. For Viber Service Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Vonage sends the transaction category to Viber Service Messages.

Must be one of: transaction or promotion
ttl
integer | Min: 30 | Max: 259200

Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.

type
string

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

message_type
string | Required

The type of message to send. You must provide image in this field

Must be one of: image
image
object | Required
url
string (url) | Required

The URL of the image attachment.

Supports .jpg, .jpeg, and .png.

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

channel
string | Required

The channel to send to. You must provide viber_service in this field

Must be one of: viber_service
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

viber_service
object
category
string

The use of different category tags enables the business to send messages for different use cases. For Viber Service Messages the first message sent from a business to a user must be personal, informative & a targeted message - not promotional. By default Vonage sends the transaction category to Viber Service Messages.

Must be one of: transaction or promotion
ttl
integer | Min: 30 | Max: 259200

Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.

type
string

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

Responses

202 Accepted.
message_uuid
string

The UUID of the message

message_uuid
string

The UUID of the message

message_uuid
string

The UUID of the message

message_uuid
string

The UUID of the message

message_uuid
string

The UUID of the message

Example Request » SMS » Text

{
  "message_type": "text",
  "text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
  "to": "447700900000",
  "from": "447700900001",
  "channel": "sms"
}

Example Request » MMS » Image

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

Example Request » MMS » vCard

{
  "message_type": "vcard",
  "vcard": {
    "url": "https://example.com/contact.vcf"
  },
  "to": "447700900000",
  "from": "447700900001",
  "channel": "mms"
}
{
  "message_type": "vcard",
  "vcard": {
    "url": "https://example.com/contact.vcf",
    "caption": "Additional text to accompany the image."
  },
  "to": "447700900000",
  "from": "447700900001",
  "channel": "mms"
}

Example Request » WhatsApp » Text

{
  "message_type": "text",
  "text": "Nexmo Verification code: 12345. Valid for 10 minutes.",
  "to": "447700900000",
  "from": "447700900001",
  "channel": "whatsapp"
}

Example Request » WhatsApp » Image

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

Example Request » WhatsApp » Audio

{
  "message_type": "audio",
  "audio": {
    "url": "https://example.com/audio.mp3"
  },
  "to": "447700900000",
  "from": "447700900001",
  "channel": "whatsapp"
}

Example Request » WhatsApp » Video

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

Example Request » WhatsApp » File

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

Example Request » WhatsApp » Template

{
  "message_type": "template",
  "template": {
    "name": "verify"
  },
  "to": "447700900000",
  "from": "447700900001",
  "channel": "whatsapp",
  "whatsapp": {
    "policy": "deterministic",
    "locale": "en-US"
  }
}
{
  "message_type": "template",
  "template": {
    "name": "verify",
    "parameters": [
      "Acme",
      "12345"
    ]
  },
  "to": "447700900000",
  "from": "447700900001",
  "channel": "whatsapp",
  "whatsapp": {
    "policy": "deterministic",
    "locale": "en-US"
  }
}

Example Request » WhatsApp » Custom

{
  "message_type": "custom",
  "to": "447700900000",
  "from": "447700900001",
  "channel": "whatsapp"
}

Example Request » Messenger » Text

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

Example Request » Messenger » Image

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

Example Request » Messenger » Audio

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

Example Request » Messenger » Video

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

Example Request » Messenger » File

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

Example Request » Viber » Text

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

Example Request » Viber » Image

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

Example Responses

202 401 402 422 429 500
{
  "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"
}

Message Status Callback

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

Request body application/json

message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

status
string | Required

The status of the message.

One of: submitted, delivered, rejected or undeliverable
channel
string | Required

The channel sending to.

One of: sms
error
object

If the message encountered a problem a descriptive error will be supplied in this object.

type
string (url)

The type of error encountered, follow URL for more details

title
string

The error code encountered when sending the message. See our errors list for a list of possible errors

detail
string

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

instance
string

The record id of this error's occurrence.

usage
object

SMS

currency
string

The charge currency in ISO 4217 format.

One of: EUR
price
string

The charge amount as a stringified number.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

status
string | Required

The status of the message.

One of: submitted, delivered, rejected or undeliverable
channel
string | Required

The channel sending to.

One of: mms
error
object

If the message encountered a problem a descriptive error will be supplied in this object.

type
string (url)

The type of error encountered, follow URL for more details

title
string

The error code encountered when sending the message. See our errors list for a list of possible errors

detail
string

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

instance
string

The record id of this error's occurrence.

usage
object

MMS

currency
string

The charge currency in ISO 4217 format.

One of: EUR
price
string

The charge amount as a stringified number.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

status
string | Required

The status of the message.

One of: submitted, delivered, rejected, undeliverable or read
channel
string | Required

The channel sending to.

One of: whatsapp
error
object

If the message encountered a problem a descriptive error will be supplied in this object.

type
string (url)

The type of error encountered, follow URL for more details

title
string

The error code encountered when sending the message. See our errors list for a list of possible errors

detail
string

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

instance
string

The record id of this error's occurrence.

usage
object

WhatsApp

currency
string

The charge currency in ISO 4217 format.

One of: EUR
price
string

The charge amount as a stringified number.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

status
string | Required

The status of the message.

One of: submitted, delivered, rejected, undeliverable or read
channel
string | Required

The channel sending to.

One of: messenger
error
object

If the message encountered a problem a descriptive error will be supplied in this object.

type
string (url)

The type of error encountered, follow URL for more details

title
string

The error code encountered when sending the message. See our errors list for a list of possible errors

detail
string

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

instance
string

The record id of this error's occurrence.

usage
object

Messenger

currency
string

The charge currency in ISO 4217 format.

One of: EUR
price
string

The charge amount as a stringified number.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

status
string | Required

The status of the message.

One of: submitted, delivered, rejected, undeliverable or read
channel
string | Required

The channel sending to.

One of: viber_service
error
object

If the message encountered a problem a descriptive error will be supplied in this object.

type
string (url)

The type of error encountered, follow URL for more details

title
string

The error code encountered when sending the message. See our errors list for a list of possible errors

detail
string

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

instance
string

The record id of this error's occurrence.

usage
object

Viber

currency
string

The charge currency in ISO 4217 format.

One of: EUR
price
string

The charge amount as a stringified number.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

Example Payload » SMS

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

Example Payload » MMS

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

Example Payload » WhatsApp

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

Example Payload » Messenger

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

Example Payload » Viber

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

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

 

Inbound Message Webhook

An inbound message from a customer to you.

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

Request body application/json

channel
string | Required

The channel the message came in on

One of: sms
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

text
string | Required

The UTF-8 encoded text of the inbound message.

sms
object

Channel specific metadata for SMS

num_messages
string

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.

keyword
string

The first word of the message sent to uppercase.

usage
object
currency
string

The charge currency in ISO 4217 format.

One of: EUR
price
string

The charge amount as a stringified number.

channel
string | Required

The channel the message came in on

One of: mms
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide image in this field

One of: image
image
object | Required
url
string (url) | Required

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_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel the message came in on

One of: mms
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide vcard in this field

One of: vcard
vcard
object | Required
url
string (url) | Required

The publicly accessible URL of the vCard attachment. Supported types are .vcf only

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: whatsapp
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide text in this field

One of: text
text
string | Required

The text of message to send.

profile
object

The text of message to send.

name
string | Required

The WhatsApp number's displayed profile name

context
object

The text of message to send.

message_uuid
string | Required

The UUID of the message being replied to

message_from
string | Required

The phone number of the original sender of the message being replied to in the E.164 format.

provider_message
string

A message from the channel provider, which may contain a description, error codes or other information

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: whatsapp
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide image in this field

One of: image
image
object | Required
url
string (url) | Required

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

profile
object
name
string | Required

The WhatsApp number's displayed profile name

context
object
message_uuid
string | Required

The UUID of the message being replied to

message_from
string | Required

The phone number of the original sender of the message being replied to in the E.164 format.

provider_message
string

A message from the channel provider, which may contain a description, error codes or other information

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: whatsapp
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide video in this field

One of: video
video
object | Required
url
string (url) | Required

Publicly accessible URL of the video attachment. Supports file types .mp4 and .3gpp

Note: Only supports video codec H.264 and audio codec AAC

profile
object
name
string | Required

The WhatsApp number's displayed profile name

context
object
message_uuid
string | Required

The UUID of the message being replied to

message_from
string | Required

The phone number of the original sender of the message being replied to in the E.164 format.

provider_message
string

A message from the channel provider, which may contain a description, error codes or other information

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: whatsapp
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide file in this field

One of: file
file
object | Required
url
string | Required
profile
object
name
string | Required

The WhatsApp number's displayed profile name

context
object
message_uuid
string | Required

The UUID of the message being replied to

message_from
string | Required

The phone number of the original sender of the message being replied to in the E.164 format.

provider_message
string

A message from the channel provider, which may contain a description, error codes or other information

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: whatsapp
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide audio in this field

One of: audio
audio
object | Required
url
string | Required | Min: 10 | Max: 2000
profile
object
name
string | Required

The WhatsApp number's displayed profile name

context
object
message_uuid
string | Required

The UUID of the message being replied to

message_from
string | Required

The phone number of the original sender of the message being replied to in the E.164 format.

provider_message
string

A message from the channel provider, which may contain a description, error codes or other information

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: whatsapp
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide custom in this field.

One of: reply
reply
object | Required
id
string | Required

An identifier to help identify the exact interactive message response.

title
string | Required

The title displayed on the interactive option chosen.

description
string

A description that may be added to the interactive options presented (available only on interactive lists).

profile
object
name
string | Required

The WhatsApp number's displayed profile name

context
object
message_uuid
string | Required

The UUID of the message being replied to

message_from
string | Required

The phone number of the original sender of the message being replied to in the E.164 format.

provider_message
string

A message from the channel provider, which may contain a description, error codes or other information

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: whatsapp
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 7 | Max: 15

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.

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. Will be unsupported if the type of message received from user is not supported by the channel.

One of: unsupported
profile
object
name
string | Required

The WhatsApp number's displayed profile name

context
object
message_uuid
string | Required

The UUID of the message being replied to

message_from
string | Required

The phone number of the original sender of the message being replied to in the E.164 format.

provider_message
string

A message from the channel provider, which may contain a description, error codes or other information

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: messenger
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide text in this field

One of: text
text
string | Required

The text of message to send.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: messenger
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide image in this field

One of: image
image
object | Required
url
string (url) | Required

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_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: messenger
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide video in this field

One of: video
video
object | Required
url
string (url) | Required

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_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: messenger
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide file in this field

One of: file
file
object | Required
url
string | Required
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: messenger
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide audio in this field

One of: audio
audio
object | Required
url
string | Required | Min: 10 | Max: 2000
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: messenger
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required | Min: 1 | Max: 50

The ID of the message sender

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. Will be unsupported if the type of message received from user is not supported by the channel.

One of: unsupported
client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: viber_service
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide text in this field

One of: text
text
string | Required

The text of message to send.

client_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

channel
string | Required

The channel that the message came in on

One of: viber_service
message_uuid
string | Required

The UUID of the message

to
string | Required | Min: 1 | Max: 50

The ID of the message recipient

from
string | Required

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

timestamp
string | Required

The datetime of when the event occurred, in ISO 8601 format.

message_type
string | Required

The type of message to send. You must provide image in this field

One of: image
image
object | Required
url
string (url) | Required

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_ref
string

Client reference of up to 40 characters. The reference will be present in every message status.

Example Payload » SMS

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

Example Payload » MMS » Image

{
  "channel": "mm",
  "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"
  }
}

Example Payload » MMS » vCard

{
  "channel": "mm",
  "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"
  }
}

Example Payload » WhatsApp » Text

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

Example Payload » WhatsApp » Image

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

Example Payload » WhatsApp » Video

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

Example Payload » WhatsApp » File

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

Example Payload » WhatsApp » Audio

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

Example Payload » WhatsApp » Reply

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

Example Payload » WhatsApp » 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"
}
{
  "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"
  }
}

Example Payload » Messenger » Text

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

Example Payload » Messenger » Image

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

Example Payload » Messenger » Video

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

Example Payload » Messenger » File

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

Example Payload » Messenger » Audio

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

Example Payload » Messenger » Unsupported

{
  "channel": "messenger",
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": "0123456789",
  "from": "9876543210",
  "timestamp": "2020-01-01 14:00:00 +0000",
  "message_type": "unsupported"
}

Example Payload » Viber » Text

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

Example Payload » Viber » Image

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

Errors

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 api_key you supplied is for an account that has been barred from submitting messages.

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 udh and body was greater than 140 octets for a binary type SMS request.

1100

Communication Failed - Message was not submitted because there was a communication failure.

1120

Illegal Sender Address - rejected - Due to local regulations, the SenderID you set in from in the request was not accepted. Please check the Global messaging section.

1130

Invalid TTL - The value of ttl in your request was invalid.

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 message-class in your request was out of range. See https://en.wikipedia.org/wiki/Data_Coding_Scheme.

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 - to is no longer active, You should remove this phone number from your database.

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 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 from parameter is invalid for the given channel.

1430

Invalid recipient - The to parameter is invalid for the given channel.

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.