Messages API

Version 1

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, RCS, WhatsApp, Viber and Facebook Messenger. See this note on authentication.

Download OpenAPI Specification

Available Operations

Send a message to the given channel

Send a Message

posthttps://api.nexmo.com/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	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

message_type

string

Required

exampletext

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

Must be one of:text

text

string

Required

example

[
  "Hello from Vonage!",
  "Hello from Vonage"
]

The text of message to send; limited to 1000 characters. Unless unless text or unicode has been explicitly set as the value for sms.encoding_type, the Messages API automatically detects whether unicode characters are present in text and sends the message as appropriate as either a text or unicode SMS. For more information on concatenation and encoding please visit: developer.vonage.com/messages/guides/sms/concatenation-and-encoding.

string

Required

Min7

Max15

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

string

Required

example447700900001

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

examplesms

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

Must be one of:sms

ttl

integer

example90000

The duration in seconds the delivery of an SMS will be attempted. By default Vonage attempts delivery for 72 hours, however the maximum effective value depends on the operator and is typically 24 - 48 hours. We recommend this value should be kept at its default or at least 30 minutes.

trusted_sender

boolean

exampletrue

Setting this parameter to true overrides, on a per-message basis, any protections set up via Fraud Defender (Traffic Rules, SMS Burst Protection, AIT Protection).

This parameter only has any effect for accounts subscribed to Fraud Defender Premium.

sms

object

An object of optional settings for the SMS message.

encoding_type

string

exampletext

The encoding type to use for the message. If set to either text or unicode the specified type will be used. If set to auto (the default), the Messages API will automatically set the type based on the content of text; i.e. if unicode characters are detected in text, then the message will be encoded as unicode, and otherwise as text.

Must be one of:textunicodeauto

content_id

string

example1107457532145798767

A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features"

entity_id

string

example1101456324675322134

A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features

pool_id

string

exampleabc123

The ID of the Number Pool to use as the sender of this message. If specified, a number from the pool will be used as the from number. The from number is still required even when specifying a pool_id and will be used as a fall-back if the number pool cannot be used. See the Number Pools documentation for more information.

webhook_version

string

examplev1

Specifies which version of the Messages API will be used to send Status Webhook messages for this particular message. For example, if v0.1 is set, then the JSON body of Status Webhook messages for this message will be sent in Messages v0.1 format. Over-rides account-level and application-level API version settings on a per-message basis.

Must be one of:v0.1v1

client_ref

string

exampleabc123

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

webhook_url

string

examplehttps://example.com/status

Specifies the URL to which Status Webhook messages will be sent for this particular message. Over-rides account-level and application-level Status Webhook url settings on a per-message basis.

failover

array

An array of objects containing the details of the failover messages to send if the primary message fails. The failover messages are sent in the order they are defined in the array. The first message is sent as a fallback if the primary message is rejected, and so on.

Any Of

One Of

message_type

string

Required

exampletext

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

Must be one of:text

text

string

Required

example

[
  "Hello from Vonage!",
  "Hello from Vonage"
]

string

Required

Min7

Max15

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

string

Required

example447700900001

channel

string

Required

examplesms

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

Must be one of:sms

ttl

integer

example90000

trusted_sender

boolean

exampletrue

Setting this parameter to true overrides, on a per-message basis, any protections set up via Fraud Defender (Traffic Rules, SMS Burst Protection, AIT Protection).

This parameter only has any effect for accounts subscribed to Fraud Defender Premium.

sms

object

An object of optional settings for the SMS message.

encoding_type

string

exampletext

Must be one of:textunicodeauto

content_id

string

example1107457532145798767

A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features"

entity_id

string

example1101456324675322134

A string parameter that satisfies regulatory requirements when sending an SMS to specific countries. For more information please refer to the Country-Specific Outbound SMS Features

pool_id

string

exampleabc123

webhook_version

string

examplev1

Must be one of:v0.1v1

client_ref

string

exampleabc123

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

webhook_url

string

examplehttps://example.com/status

Specifies the URL to which Status Webhook messages will be sent for this particular message. Over-rides account-level and application-level Status Webhook url settings on a per-message basis.

Example Request

{
   "message_type": "text",
   "text": "Hello from Vonage",
   "to": "447700900000",
   "from": "447700900001",
   "channel": "sms",
   "ttl": 90000,
   "trusted_sender": true,
   "sms": {
      "encoding_type": "text",
      "content_id": "1107457532145798767",
      "entity_id": "1101456324675322134",
      "pool_id": "abc123"
   },
   "webhook_version": "v1",
   "client_ref": "abc123",
   "webhook_url": "https://example.com/status",
   "failover": [
      {
         "message_type": "text",
         "text": "Hello from Vonage",
         "to": "447700900000",
         "from": "447700900001",
         "channel": "sms",
         "ttl": 90000,
         "trusted_sender": true,
         "sms": {
            "encoding_type": "text",
            "content_id": "1107457532145798767",
            "entity_id": "1101456324675322134",
            "pool_id": "abc123"
         },
         "webhook_version": "v1",
         "client_ref": "abc123",
         "webhook_url": "https://example.com/status"
      }
   ]
}

{
   "message_type": "text",
   "text": "Hello from Vonage",
   "to": "447700900000",
   "from": "447700900001",
   "channel": "sms",
   "ttl": 90000,
   "trusted_sender": true,
   "sms": {
      "encoding_type": "text",
      "content_id": "1107457532145798767",
      "entity_id": "1101456324675322134",
      "pool_id": "abc123"
   },
   "webhook_version": "v1",
   "client_ref": "abc123",
   "webhook_url": "https://example.com/status",
   "failover": [
      {
         "message_type": "text",
         "text": "Hello from Vonage",
         "to": "447700900000",
         "from": "447700900001",
         "channel": "sms",
         "ttl": 90000,
         "trusted_sender": true,
         "sms": {
            "encoding_type": "text",
            "content_id": "1107457532145798767",
            "entity_id": "1101456324675322134",
            "pool_id": "abc123"
         },
         "webhook_version": "v1",
         "client_ref": "abc123",
         "webhook_url": "https://example.com/status"
      }
   ]
}

Responses
Content Type
application/json

Accepted.

message_uuid

string(uuid)

Required

exampleaaaaaaaa-bbbb-4ccc-8ddd-0123456789ab

The UUID of the message

workflow_id

string

example3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9

The ID of the failover workflow. Only present if the request was sent with the failover property.

Example Response

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9"
}

Update a message for the given channel

This enpoint lets you update the status of outbound and/or inbound messages for certain channels. For example, you can revoke outbound messages or mark inbound messages as read.

patchhttps://{region}.nexmo.com/v1/messages/:message_uuid

Server Variables

Variable	Description	Default Value	Options
region	The specific region that the API request should be sent to.	n/a	api-eu, api-us, api-ap

Authentication

Key	Description	Where	Example
Authorization	Your JSON web token. Read more about JWTs	Headers	`Bearer <JWT>`

Path Parameters

message_uuid

string

Required

UUID of the message to be updated

Request Body
Content Type
application/json

One Of

status

string

Required

examplerevoked

The status to set for the message.

Setting the status of an inbound RCS message to read indicates to the sender of the message that the message has been read.
Setting the status of an outbound RCS message to revoked revokes that message if possible. See RCS Message Revocation for more information.

Must be one of:readrevoked

Example Request»RCS

{
   "status": "revoked"
}

{
   "status": "revoked"
}

Responses

Accepted.

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 webhook

An inbound message from a customer to you.

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

Request Body
Content Type
application/json

One Of

channel

string

Required

examplesms

The channel the message came in on

Must be one of:sms

message_uuid

string(uuid)

Required

exampleaaaaaaaa-bbbb-4ccc-8ddd-0123456789ab

The UUID of the message

string

Required

Min7

Max15

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

string

Required

example447700900001

timestamp

string

Required

example2025-02-03T12:14:25Z

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

text

string

Required

exampleHello From Vonage!

The UTF-8 encoded text of the inbound message.

sms

object

Channel specific metadata for SMS

num_messages

string

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 form a single message. This number indicates how many messages formed this webhook.

keyword

string

exampleHELLO

The first word of the message sent to uppercase.

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.

origin

object

network_code

string

example12345

The network code of the network from which the message originated (if available).

Example Payload

{
   "channel": "sms",
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "text": "Hello From Vonage!",
   "sms": {
      "num_messages": "2",
      "keyword": "HELLO"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   },
   "origin": {
      "network_code": "12345"
   }
}

Responses

Your server returns this code if it accepts the callback.

Message Status webhook

The current status of a message that you have sent. This is a webhook that is triggered when the status of a message changes.

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

Request Body
Content Type
application/json

One Of

message_uuid

string(uuid)

Required

exampleaaaaaaaa-bbbb-4ccc-8ddd-0123456789ab

The UUID of the message

string

Required

Min7

Max15

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

string

Required

example447700900001

timestamp

string

Required

example2025-02-03T12:14:25Z

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

status

string

Required

examplesubmitted

The status of the message.

Must be one of:submitteddeliveredrejectedundeliverable

error

object

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

type

string(url)

examplehttps://developer.vonage.com/api-errors/messages#1000

The type of error encountered, follow URL for more details

title

string

example1000

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

detail

string

exampleThrottled - You have exceeded the submission capacity allowed on this account. Please wait and retry

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

instance

string

examplebf0ca0bf927b3b52e3cb03217e1a1ddf

The record id of this error's occurrence.

client_ref

string

exampleabc123

Client reference of up to 100 characters. Only present if this was set in the associated outbound message.

workflow

object

An object containing details of the failover workflow that was used to send the message related to this status. Only present if the request was sent with the failover property.

workflow_id

string

example3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9

The ID of the failover workflow.

items_number

string

example1

The position of the message related to this status within the failover workflow that was used to send the message. For example, an items_number of 1 indicates that this status relates to message that was the primary message in the request; an items_number of 2 indicates that this status relates to message that was the first message in the failover array, and so on.

items_total

string

example2

The total number of messages in the request for the workflow related to this status, including the primary message and all messages in the failover array.

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.

channel

string

Required

examplesms

The channel for the message to which this status relates.

Must be one of:sms

destination

object

network_code

string

example12345

Code indicating the terminating network for the number to which the message was sent. May not always be included in the message status data.

sms

object

Channel specific metadata for SMS

count_total

string

example2

The number of SMS messages concatenated together to comprise the submitted message. SMS messages are 160 characters, if a submitted message exceeds that size it is sent as multiple SMS messages. This number indicates how many SMS messages are required.

Example Payload

{
   "message_uuid": "aaaaaaaa-bbbb-4ccc-8ddd-0123456789ab",
   "to": "447700900000",
   "from": "447700900001",
   "timestamp": "2025-02-03T12:14:25Z",
   "status": "submitted",
   "error": {
      "type": "https://developer.vonage.com/api-errors/messages#1000",
      "title": "1000",
      "detail": "Throttled - You have exceeded the submission capacity allowed on this account. Please wait and retry",
      "instance": "bf0ca0bf927b3b52e3cb03217e1a1ddf"
   },
   "client_ref": "abc123",
   "workflow": {
      "workflow_id": "3TcNjguHxr2vcCZ9Ddsnq6tw8yQUpZ9rMHv9QXSxLan5ibMxqSzLdx9",
      "items_number": "1",
      "items_total": "2"
   },
   "usage": {
      "currency": "EUR",
      "price": "0.0333"
   },
   "channel": "sms",
   "destination": {
      "network_code": "12345"
   },
   "sms": {
      "count_total": "2"
   }
}

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.
1242	Number pool does not exists - check that the number pool has been configured for your account
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.
1251	Unable to route traffic to a destination - This may be due to the routing rules applied for your destination network.
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.
1282	Message blocked by provider - The messaging provider has chosen to block this message. This may be due to content or restrictions imposed by the provider.
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, or message expired before delivered.
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 100 characters.
1451	Invalid context - the reference to the original message could not be found because it is invalid or no longer available.
1460	Daily message limit exceeded - Check compliance with regulations such as 10DLC.
1461	Auto-limiting of messages by Provider - This message was not delivered by Provider to avoid excessive messages to the end user. For details please see this knowledgebase article.
1470	Fraud Defender Traffic Rule - Rejected due to prefix block list.
1472	Fraud Defender SMS Burst Protection - Traffic limit has been reached
1473	AIT Protection - The message has been rejected by Fraud Defender AIT Protection
1474	Fraud Defender Traffic Rule - Rejected due to country block.
1475	Fraud Defender Traffic Rule - Rejected due to network block.
1480	Entity Filter - The message failed due to `entity_id` being incorrect or not provided. More information on country specific regulations.
1481	Header Filter - The message failed because the header ID (`from` phone number) was incorrect or missing. More information on country specific regulations.
1482	Content Filter - The message failed due to `content_id` being incorrect or not provided. More information on country specific regulations.
1483	Consent Filter - The message failed due to consent not being authorized. More information on country specific regulations.
1484	Regulation Error - Unexpected regulation error - contact support.

Messages API

Available Operations

Send a message to the given channel

Authentication

Request Body Content Typeapplication/json

Example Request

Responses Content Typeapplication/json

Example Response

Update a message for the given channel

Server Variables

Authentication

Path Parameters

Request Body Content Typeapplication/json

Example Request»RCS

Responses

Webhooks

Available Operations

Inbound Message webhook

Request Body Content Typeapplication/json

Example Payload

Responses

Message Status 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

Request Body
Content Type
application/json