Messages API

Version 0

The Messages API enables you to send messages to customers via their preferred channels (currently Facebook Messenger, WhatsApp, Viber, and SMS/MMS) using a single API. The Messages API is currently in Beta.

Download OpenAPI Specification

Available Operations

Send a Message

Send a Message

Send a Message over SMS, WhatsApp, Viber, Facebook Messenger, or MMS

posthttps://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	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`
Authorization	Base64 encoded API key and secret joined by a colon. Read more	Headers	`Basic <base64>`

Request Body
Content Type
application/json

One Of

client_ref

string

exampleclient-ref2

client reference up to 40 characters, the reference will be present in every message status

object

Required

type

string

Required

examplesms

The channel the message is going to.

Must be one of:sms

number

string

Required

example447700900000

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

object

Required

type

string

Required

examplesms

The channel the message is coming from

Must be one of:sms

number

string

Required

example447700900001

The Vonage Virtual number the message is originating from in the E.164 format. Don't use a leading + or 00 when entering a phone number, start with the country code, for example, 447700900000.

message

object

Required

content

object

Required

type

string

Required

exampletext

The content type of the message

Must be one of:text

text

string

Required

exampleHello From Vonage!

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.vonage.com/messaging/sms/guides/concatenation-and-encoding.

Example Request

{
   "client_ref": "client-ref2",
   "to": {
      "type": "sms",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "number": "447700900001"
   },
   "message": {
      "content": {
         "type": "text",
         "text": "Hello From Vonage!"
      }
   }
}

{
   "client_ref": "client-ref2",
   "to": {
      "type": "sms",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "number": "447700900001"
   },
   "message": {
      "content": {
         "type": "text",
         "text": "Hello From Vonage!"
      }
   }
}

Responses
Content Type
application/json

Accepted.

message_uuid

string

Required

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

Example Response

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Message Status callback

Webhooks to inform about events happening to the message at communication level (has it been delivered, rejected by the provider...).

posthttps://example.com/webhooks/message-status

Request Body
Content Type
application/json

message_uuid

string

Required

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

object

Required

type

string

Required

examplesms

The type of message that you want to send.

Must be one of:smsviber_service_msgmessengerwhatsappmms

string

Min1

Max50

example0123456789012345

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

number

string

Min1

Max50

example447700900000

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.

from

object

Required

type

string

Required

examplesms

The type of message that you want to send.

Must be one of:smsviber_service_msgmessengerwhatsappmms

string

Min1

Max50

example0123456789012345

Your ID for the platform that you are sending from.

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

Viber: This is your Service Message ID given to you by your Vonage Account Manager. To find out more please visit vonage.com.

number

string

Min1

Max50

example447700900000

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

WhatsApp: This is your WhatsApp Business Number given to you by your Vonage Account Manager. To find out more please visit vonage.com.

MMS: US shortcode

timestamp

string(ISO 8601)

Required

example2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

status

string

Required

exampledelivered

The status of the message. The read message status is available for messenger, whatsapp and viber.

Must be one of:submitteddeliveredreadrejectedundeliverable

error

object

code

integer

example1300

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

reason

string

exampleNot part of the provider network

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

usage

object

currency

string

exampleEUR

The charge currency in ISO 4217 format.

Must be one of:EUR

price

string

example0.0333

The charge amount as a stringified number.

client_ref

string

examplemy-personal-reference

The client's reference.

Example Payload

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

Responses

Your server returns this code if it accepts the callback.

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.

Available Operations

Inbound Message

Inbound Message webhook

An inbound message from a customer to you.

posthttps://example.com/webhooks/inbound-message

Request Body
Content Type
application/json

One Of

message_uuid

string

Required

exampleaaaaaaaa-bbbb-cccc-dddd-0123456789ab

The UUID of the message.

timestamp

string(ISO 8601)

Required

example2020-01-01T14:00:00.000Z

The datetime of when the event occurred.

object

Required

type

string

Required

examplesms

The channel the message is going to.

Must be one of:sms

number

string

Required

example447700900000

The Vonage Virtual number the sms is being sent to in the E.164 format.

from

object

Required

type

string

Required

examplesms

The channel the message is coming from

Must be one of:sms

number

string

Required

example447700900001

The phone number the message is originating from in the E.164 format.

message

object

Required

content

object

Required

type

string

Required

exampletext

The content type of the message

Must be one of:text

text

string

Required

exampleHello From Vonage!

The UTF-8 encoded text of the inbound message.

sms

object

Required

num_messages

string

Required

example2

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.

usage

object

Required

currency

string

Required

exampleEUR

The charge currency in ISO 4217 format.

Must be one of:EUR

price

string

Required

example0.0333

The charge amount as a stringified number.

Example Payload

{
   "message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
   "timestamp": "2020-01-01T14:00:00.000Z",
   "to": {
      "type": "sms",
      "number": "447700900000"
   },
   "from": {
      "type": "sms",
      "number": "447700900001"
   },
   "message": {
      "content": {
         "type": "text",
         "text": "Hello From Vonage!"
      },
      "sms": {
         "num_messages": "2"
      }
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   }
}

Responses

Your server returns this code if it accepts the callback.

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	Information
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 support or create a helpdesk ticket here.
1260	Destination unreachable - The message could not be delivered to the phone number. If using Viber Business Messages your account might not be enabled for this country.
1270	Subscriber Age Restriction - The carrier blocked this message because the content is not suitable for to based on age restrictions.
1280	Number Blocked by Carrier - The carrier blocked this message. This could be due to several reasons. For example, to's plan does not include SMS or the account is suspended.
1290	Pre-Paid - Insufficient funds - to’s pre-paid account does not have enough credit to receive the message.
1300	Not part of the provider network - The number or ID is not a user in the provider network.
1310	Not suitable device - The user's device can't receive the message.
1320	Message already sent - The message was already sent.
1330	Unknown - An unknown error was received from the carrier who tried to send this this message. Depending on the carrier, that to is unknown. When you see this error, and status is rejected, always check if to in your request was valid.
1331	Provider error - The provider is not responding or unable to process the request. Please try sending your message in a few minutes time.
1340	Outside of the allowed window - This message is sent outside of allowed response window.
1350	Phone matching fee not paid - Requires phone matching access fee to be paid by the Facebook Page.
1360	TTL was activated - TTL was activated, no callbacks and no charge will be issued.
1370	Expired access Token - Please reauthenticate your Facebook Page with Vonage.
1380	Invalid resource - Please check that the URL your provided to your resrouce is accesible and valid.
1381	Resource size is too large - Please try sending a smaller media file.
1382	Resource type is invalid - Please check that the file you are trying to send is valid.

Messages API

Available Operations

Send a Message

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Message Status callback

Request Body Content Typeapplication/json

Example Payload

Responses

Webhooks

Available Operations

Inbound Message webhook

Request Body Content Typeapplication/json

Example Payload

Responses

Errors

Request Body
Content Type
application/json

Responses
Content Type
application/json

Request Body
Content Type
application/json

Request Body
Content Type
application/json