Messages API Overview
The Messages API allows you to send and in some cases receive messages over SMS, MMS, Facebook Messenger, Viber, and WhatsApp. Further channels may be supported in the future.
Note: Major US carriers have announced their requirements for a new standard for application-to-person (A2P) messaging in the USA, which applies to all messaging over 10-digit geographic phone numbers, also known as 10 DLC. If you are or are planning to send SMS/MMS traffic from a +1 Country Code 10 Digit Long Code into US networks, you will need to register a brand and campaign in order to get approval for sending messages. See the 10 DLC documentation for details.
The following diagram illustrates how the Vonage Messages API enables you to send messages via multiple channels from a single endpoint:
Contents
- Versions
- Supported features
- External Accounts API
- Getting started
- Concepts
- Code Snippets
- Tutorials
- Use Cases
- Reference
Versions
There are currently two versions of the API, v0.1 and v1. Each version has its own API endpoint:
-
v1:
https://api.nexmo.com/v1/messages
-
v0.1:
https://api.nexmo.com/v0.1/messages
One of the primary differences between the two versions is that v1 provides a much simpler and flatter structure for the JSON structure used in the request and response data. Check the relevant API specification for details of the required structure.
NOTE: Most of the code examples in this documentation (other than examples for the Node SDK) use the structure for v1 of the API.
As well as the difference in JSON structure, v1 supports some additional features.
We recommend using v1 of the API. If you are using v0.1 of the API, and are intending to move to v1, check our Migration Guide.
Supported features
The following features are supported in both v0.1 and v1 versions of the API:
Channel | Outbound Text | Outbound Image | Outbound Audio | Outbound Video | Outbound File | Outbound Template |
---|---|---|---|---|---|---|
SMS | n/a | n/a | n/a | n/a | n/a | |
MMS | n/a | n/a | n/a | n/a | ||
Viber Business Messages | n/a | n/a | n/a | |||
Facebook Messenger | ||||||
Channel | Inbound Text | Inbound Image | Inbound Audio | Inbound Video | Inbound File | Inbound Location |
---|---|---|---|---|---|---|
SMS | n/a | n/a | n/a | n/a | n/a | |
MMS | n/a | n/a | n/a | n/a | ||
Viber Business Messages | n/a | n/a | n/a | n/a | n/a | |
Facebook Messenger | ||||||
Limited support is also provided for custom objects:
Channel | Outbound Button | Outbound Location | Outbound Contact |
---|---|---|---|
SMS | n/a | n/a | n/a |
MMS | n/a | n/a | n/a |
Viber Business Messages | n/a | n/a | |
Facebook Messenger | n/a | n/a | |
Key:
- = Supported.
- = Supported by the channel, but not by Vonage.
- n/a = Not supported by the channel.
Additional v1 Features
As well as all of the existing features from v0.1, there are some additional features supported in v1 of the API.
WhatsApp Interactive Messages: v1 of the Messages API, supports WhatsApp's interactive message feature. See our overview of this feature. Once you're ready to start working with interactive messages, read our more detailed explanation.
WhatsApp Reply Context: in v1 of the Messages API, the callbacks to the inbound messages webhooks can provide a reply context.
WhatsApp Profile Name: in v1 of the Messages API, the callbacks to the inbound messages webhooks can provide profile name.
Provider messages: in v1 of the Messages API, the callbacks to the inbound messages webhooks can provide error messages from WhatsApp under a new
provider_message
field.
External Accounts API
The External Accounts API is used to manage your accounts for Viber Business Messages, Facebook Messenger and WhatsApp when using those channels with the Messages and Dispatch APIs.
Getting started
In this example you will need to replace the following variables with actual values using any convenient method:
Key | Description |
---|---|
VONAGE_API_KEY |
Vonage API key which can be obtained from your Vonage API Dashboard. |
VONAGE_API_SECRET |
Vonage API secret which can be obtained from your Vonage API Dashboard. |
FROM_NUMBER |
A phone number you own or some text to identify the sender. |
TO_NUMBER |
The number of the phone to which the message will be sent. |
NOTE: Don't use a leading +
or 00
when entering a phone number, start with the country code, for example 447700900000.
The following code shows how to send an SMS message using the Messages API:
Write the code
Add the following to send-sms-basic-auth.sh
:
curl -X POST https://api.nexmo.com/v0.1/messages \
-u "$VONAGE_API_KEY:$VONAGE_API_SECRET" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d $'{
"from": { "type": "sms", "number": "$FROM_NUMBER" },
"to": { "type": "sms", "number": "$TO_NUMBER" },
"message": {
"content": {
"type": "text",
"text": "This is an SMS sent from the Messages API"
}
}
}'
Run your code
Save this file to your machine and run it:
bash send-sms-basic-auth.sh
Concepts
- External Accounts: External accounts are Messaging accounts such as Facebook, WhatsApp and Viber that you want to link to your Messages and Dispatch applications.
- Understanding Facebook messaging: Understanding Facebook messaging.
- Understanding Viber messaging: Viber messaging solution for businesses.
- WhatsApp v0.1 to v1 Migration Guide: Differences to be aware of between the two versions of the API if migrating to v1
- WhatsApp Interactive Messages: Brief overview of WhatsApp interactive messages.
- Understanding WhatsApp messaging: WhatsApp messaging solution for businesses.
- Custom objects: Understanding custom objects
- Messages API Sandbox: Understanding and utilizing the Messages API Sandbox.
- Working with WhatsApp Interactive Messages: General workflow for working with WhatsApp interactive messages, and examples of lists and reply buttons
Code Snippets
- Before you Begin
- Install Vonage CLI
- Create a Vonage Messages and Dispatch Application
- Install Server SDK
- Configure Webhooks
- Inbound Message Webhook
- Message Status Webhook
- Viber / Send a Text Message
- Whatsapp / Send a Message Template (MTM)
- Viber / Send an Image Message
- Whatsapp / Send a Media Message Template
- Messenger / Send an Audio Message
- Messenger / Send a File Message
- Messenger / Send an Image Message
- Messenger / Send a Message Template
- Messenger / Send a Text Message
- Messenger / Send a Video Message
- Mms / Send an MMS
- Sms / Send an SMS
- Whatsapp / Send an Audio Message
- Whatsapp / Send a Link Button
- Whatsapp / Send a Quick Reply Button
- Whatsapp / Send a Contact
- Whatsapp / Send a File Message
- Whatsapp / Send an Image Message
- Whatsapp / Send a Location
- Whatsapp / Send a Text Message
- Whatsapp / Send a Video Message
Tutorials
- How to send an SMS message
- How to send a Viber message
- How to send a WhatsApp message
- How to send a Facebook Messenger message
Use Cases
- Receive product information automatically via Facebook Messenger
- Real-time data feed into multiple channels using Messages API