Messages API Beta

The Messaging API is a new API that consolidates all messaging channels. It encapsulates a user (developer) from having to use multiple APIs to interact with our various channels such as SMS, MMS, Viber, Facebook Messenger, etc. The API normalises information across all channels to abstracted to, from and content. This API is currently Beta.

Download OpenAPI 3 Definition

Message

The Message object contains information about the request and details of the message object.

Key Description
message_uuid
Required | string

The UUID of the message.
Example Model
{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Send a Message

POST https://api.nexmo.com/v0.1/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

Key Description Example Default
to
Required | object 		None
Key Description Example Default
type
Required | string

The type of message that you want to send.


Must be one of: sms, viber_service_msg, messenger or whatsapp 		sms None
id
string

The ID of the message recipient.

Messenger: This value should be the from.id value you received in the inbound messenger event.

SMS: or Viber: or WhatsApp This value is not required.

 0123456789012345 None
number
string

SMS: or Viber: or WhatsApp 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.

Messenger: This value is not required.

 447700900000 None
from
Required | object 		None
Key Description Example Default
type
Required | string

The type of message that you want to send.


Must be one of: sms, viber_service_msg, messenger or whatsapp 		sms None
id
string

Your ID for the platform that you are sending from.

Messenger: This value should be the to.id value you received in the inbound messenger event.

Viber: This is your Service Message ID given to you by Nexmo Account Manager. To find out more please visit nexmo.com/products/messages  .

SMS: or WhatsApp This value is not required.

 0123456789012345 None
number
string

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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages  .

Messenger: or Viber: This value is not required.

 447700900000 None
message
Required | object 		None
Key Description Example Default
content
Required | object 		None
Key Description Example Default
type
string

The type of message that you are sending.

Messenger: supports all types.

Viber Service Messages: supports image and text.

WhatsApp: supports template and text.

SMS: supports text.


Must be one of: text, image, audio, video, file, template or custom 		text None
text
string

The text of the message.

Messenger: Is limited to 640 characters

SMS or Viber: Is 1000 characters

WhatsApp: is 4096 characters

 Nexmo Verification code: 64873. Valid for 10 minutes. None
image
object 		None
Key Description Example Default
url
string

The URL of the image attachment. messenger supports .jpg, .png and .gif. viber_service_msg supports .jpg and .png.

 https://example.com/image.jpg None
audio
object 		None
Key Description Example Default
url
string

The URL of the audio attachment. messenger supports .mp3.

 https://example.com/audio.mp3 None
video
object 		None
Key Description Example Default
url
string

The URL of the video attachment. messenger supports .mp4

 https://example.com/video.mp4 None
file
object 		None
Key Description Example Default
url
string

The URL of the file attachment. messenger supports a wide range of attachments including .zip, .csv and .pdf

 https://example.com/file.zip None
template
object 		None
Key Description Example Default
name
string

The name of the template.

 whatsapp:hsm:technology:nexmo:verify None
parameters
array
of object's 		None
fallback_locale
string

Templates sent to a user will be localized according to the device locale settings. Optionally specify a fallback locale for displaying the message if a translation does not exist

 en en
viber_service_msg
object 		None
Key Description Example Default
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 Nexmo sends the transaction category to Viber Service Messages.


Must be one of: transaction or promotion 		transaction None
ttl
integer

Only valid for Viber Service Messages. Set the time-to-live of message to be delivered in seconds. i.e. if the message is not delivered in 600 seconds then delete the message.


Must be between 30 and 86400 		600 None
messenger
object 		None
Key Description Example Default
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  . Nexmo maps our category to their messaging_type. If message_tag is used, then an additional tag for that type is mandatory. By default Nexmo sends the response category to Facebook Messenger.


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

‘A full list of the possible tags is available on developers.facebook.com  '

 ticket_update None
client_ref
string

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

 my-personal-reference None

View response field descriptions

Response Fields

Field Description
message_uuid

The UUID of the message.

 
{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}
{
  "type": "https://www.nexmo.com/messages/Errors#InvalidParams",
  "detail": "Your request parameters did not validate.",
  "instance": "abc123"
}

Message Status Callback

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

Request body application/json

Key Description Example
message_uuid
Required | string

The UUID of the message.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab
to
Required | object
Key Description Example
type
Required | string

The type of message that you want to send.


One of: sms, viber_service_msg, messenger or whatsapp 		sms
id
string

The ID of the message recipient.

Messenger: This value should be the from.id value you received in the inbound messenger event.

SMS: or Viber: or WhatsApp This value is not required.

 0123456789012345
number
string

SMS: or Viber: or WhatsApp 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.

Messenger: This value is not required.

 447700900000
from
Required | object
Key Description Example
type
Required | string

The type of message that you want to send.


One of: sms, viber_service_msg, messenger or whatsapp 		sms
id
string

Your ID for the platform that you are sending from.

Messenger: This value should be the to.id value you received in the inbound messenger event.

Viber: This is your Service Message ID given to you by Nexmo Account Manager. To find out more please visit nexmo.com/products/messages  .

SMS: or WhatsApp This value is not required.

 0123456789012345
number
string

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 Nexmo Account Manager. To find out more please visit nexmo.com/products/messages  .

Messenger: or Viber: This value is not required.

 447700900000
timestamp
Required | string (ISO 8601)

The datetime of when the event occurred.

 2020-01-01T14:00:00.000Z
status
Required | string

The status of the message. The read message status is only available for viber_service_msg and messenger.


One of: submitted, delivered, read, rejected or undeliverable 		delivered
error
object
Key Description Example
code
integer

The error code. See Errors for a table of descriptions.

 1300
reason
string

Text describing the error. See Errors for a more details.

 Not part of the provider network
usage
object
Key Description Example
currency
string

The charge currency in ISO 4217 format.


One of: EUR 		EUR
price
string

The charge amount as a stringified number.

 0.0333
client_ref
string

The client's reference.

 my-personal-reference
Request model
{
  "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"
}

Inbound Message Callback

An inbound message from a customer to you.

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

Request body application/json

Key Description Example
message_uuid
Required | string

The UUID of the message.

 aaaaaaaa-bbbb-cccc-dddd-0123456789ab
to
Required | object
Key Description Example
type
Required | string

The type of message being received.


One of: messenger or whatsapp 		messenger
id
string

The ID of the recipient.

 0123456678901234
from
Required | object
Key Description Example
type
Required | string

The type of message being sent.


One of: messenger or whatsapp 		messenger
id
string

The ID of the sender.

 0123456789012345
timestamp
Required | string (ISO 8601)

The datetime of when the event occurred.

 2020-01-01T14:00:00.000Z
message
object
Key Description Example
content
object
Key Description Example
type
string

The type of message being received.


One of: text, image, audio, video, file or location 		text
text
string

The body of the message.

 Hello World!
image
object
Key Description Example
url
string

The URL of the image attachment. messenger supports .jpg, .png and .gif. viber_service_msg supports .jpg and .png.

 https://example.com/image.jpg
audio
object
Key Description Example
url
string

The URL of the audio attachment. messenger supports .mp3.

 https://example.com/audio.mp3
video
object
Key Description Example
url
string

The URL of the video attachment. messenger supports .mp4

 https://example.com/video.mp4
file
object
Key Description Example
url
string

The URL of the file attachment. messenger supports a wide range of attachments including .zip, .csv and .pdf

 https://example.com/file.zip
location
object
Key Description Example
lat
string

The latitude of the location attachment.

 51.5228349
long
string

The longitude of the location attachment.

 -0.0854414
url
string

Depending on the provider, this can either be the location on a map or the website of the business at this location.

 None
address
string

The address of the location attachment.

 15 Bonhill St London EC2A 4DN
name
string

The name of the location attachment.

 Nexmo London
Request model
{
  "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "to": {
    "type": "messenger",
    "id": "0123456678901234"
  },
  "from": {
    "type": "messenger",
    "id": "0123456789012345"
  },
  "timestamp": "2020-01-01T14:00:00.000Z",
  "message": {
    "content": {
      "type": "text",
      "text": "Hello World!",
      "image": {
        "url": "https://example.com/image.jpg"
      },
      "audio": {
        "url": "https://example.com/audio.mp3"
      },
      "video": {
        "url": "https://example.com/video.mp4"
      },
      "file": {
        "url": "https://example.com/file.zip"
      },
      "location": {
        "lat": "51.5228349",
        "long": "-0.0854414",
        "url": "abc123",
        "address": "15 Bonhill St London EC2A 4DN",
        "name": "Nexmo London"
      }
    }
  }
}