Skip to navigation

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:

Messages and Dispatch Overview

Contents

Versions

There are currently two versions of the API, v0.1 and v1. Each version has its own API endpoint:

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
WhatsApp
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
WhatsApp

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
WhatsApp

Key:

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.

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:

  • cURL

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

    View full source

    Run your code

    Save this file to your machine and run it: 

    bash send-sms-basic-auth.sh

    Concepts

    Code Snippets

    Tutorials

    Use Cases

    Reference

    Improve this page