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.
The following diagram illustrates how the Vonage Messages API enables you to send messages via multiple channels from a single endpoint:
Contents
- Beta
- Supported features
- External Accounts API
- Getting started
- Concepts
- Code Snippets
- Tutorials
- Use Cases
- Reference
Beta
This API is currently in Beta.
Vonage always welcomes your feedback. Your suggestions help us improve the product. If you do need help, please email support@nexmo.com and include the Messages API in the subject line. Please note that during the Beta period, support times are limited to Monday to Friday.
During Beta Vonage will expand the capabilities of the API.
Supported features
In this release the following features are supported:
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 Service Messages | n/a | n/a | n/a | |||
Facebook Messenger | ||||||
Channel | Inbound Text | Inbound Image | Inbound Audio | Inbound Video | Inbound File | Inbound Location |
---|---|---|---|---|---|---|
MMS | n/a | n/a | n/a | n/a | ||
Viber Service 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 Service 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.
External Accounts API
The External Accounts API is used to manage your accounts for Viber Service 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.
- Understanding WhatsApp messaging: WhatsApp messaging solution for businesses.
- Custom objects: Understanding custom objects
- Signed webhooks: Verify the source of incoming requests via the Messages API.
- Messages API Sandbox: Understanding and utilizing the Messages API Sandbox.
- 10 DLC guidelines for US customers: Understanding 10 DLC guidelines for US based SMS.
Code Snippets
- Before you Begin
- Install Nexmo CLI
- Create a Vonage Application
- Install Server SDK
- Configure Webhooks
- Inbound Message Webhook
- Message Status Webhook
- Whatsapp / Send a Message Template (MTM)
- Viber / Send a Text Message
- Whatsapp / Send a Media Message Template
- Viber / Send an Image Message
- Sms / Send an SMS
- Whatsapp / Send a File Message
- Whatsapp / Send a Contact
- Whatsapp / Send a Video Message
- Whatsapp / Send an Audio Message
- Whatsapp / Send an Image Message
- Whatsapp / Send a Quick Reply Button
- Whatsapp / Send a Text Message
- Whatsapp / Send a Location
- Whatsapp / Send a Link Button
- Messenger / Send a File Message
- Messenger / Send a Video Message
- Messenger / Send an Audio Message
- Messenger / Send an Image Message
- Messenger / Send a Text Message
- Messenger / Send a Message Template
- Mms / Send an MMS
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