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
Improve this specification

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
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, whatsapp or mms 		sms None
id
string

Messenger: The ID of the message recipient. This value should be the from.id value you received in the inbound messenger event.

 0123456789012345 None
number
string

SMS, Viber, WhatsApp or MMS: The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

 447700900000 None
from
Required | object
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, whatsapp or mms 		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.

 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.

MMS: US shortcode

 447700900000 None
message
Required | object
Key Description Example Default
content
Required | object
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 and custom.

WhatsApp: supports template and text.

SMS: supports text.

MMS: supports image.


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
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
Key Description Example Default
url
string

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

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

The URL of the video attachment. messenger supports .mp4

 https://example.com/video.mp4 None
file
object
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
Key Description Example Default
name
string

The name of the template.

 whatsapp:hsm:technology:nexmo:verify None
parameters
array
of objects 		None
viber_service_msg
object
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

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 259200 		600 None
type
string

Viber-specific type definition. To use "template", please contact Nexmo Account Manager to setup your templates. To find out more please visit nexmo.com/products/messages.

 template None
messenger
object
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
whatsapp
object
Key Description Example Default
policy
string

There are two policies that you can specify when sending an Message Template: deterministic and fallback. deterministic — Deliver the Message Template in exactly the language and locale asked for. fallback — Deliver the Message Template in the language that matches users language/locale setting on device. If one can not be found, deliver using the specified fallback language.


Must be one of: fallback or deterministic 		deterministic None
locale
string

We are using the industry standard, BCP 47, for locales. So in your API call to the /messages API you will need to put “en-GB” and this will refer to the “en_GB” template for WhatsApp.

 en-GB 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",
  "title": "Invalid Parameters",
  "detail": "Your request parameters did not validate.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}

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, whatsapp or mms 		sms
id
string

Messenger: The ID of the message recipient. This value should be the from.id value you received in the inbound messenger event.

 0123456789012345
number
string

SMS, Viber, WhatsApp or MMS: The phone number of the message recipient in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

 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, whatsapp or mms 		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.

 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.

MMS: US shortcode

 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 messenger and whatsapp.


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

The error code. See our errors list for a list of possible errors

 1300
reason
string

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

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

Errors

Nexmo uses error codes to report back when an issue was encountered. Below you can find a full table to error codes:

Asynchronous Errors

Code Text Meaning
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 parameters Some of the parameters of the template were invalid.
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 shoud 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.
1110 Invalid Signature Message was not submitted due to a verification failure in the submitted signature.
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, rety 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 - Insufficent 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.
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 the Facebook Page.
1360 TTL was activated TTL was activated, no callbacks and no charge will be issued.
1370 Expired access Token The access token has expired, for Facebook Messenger, the consent has to be periodically given every 90 days. Try to delete and reconnect the Facebook page to Nexmo.
Example response
{
  "type": "https://www.nexmo.com/messages/Errors#InvalidParams",
  "title": "Invalid Parameters",
  "detail": "Your request parameters did not validate.",
  "instance": "f94b4e56604e07e5e5ad5a7228618f81"
}