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:

  • 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
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
Viber Business Messages 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:

  • = Supported.
  • = Supported by the channel, but not by Vonage.
  • n/a = Not supported by the channel.

Notes:

  1. MMS text supported as an optional caption in other message types (e.g. Image, Audio, Video).
  2. MMS Video and Audio supported for 10DLC (10 Digit Long Codes) and TFN (Toll-Free Numbers).
  3. MMS Files support .vcf (vCard) files only. Files supported on 10DLC and SC (Short Codes) numbers.

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.

Authentication

The Messages API supports either Basic authentication or JWT (JSON Web Token) authentication, but there are some important differences between the two to be aware of:

  • Basic authentication uses an encoded API key and secret, and authenticates at the account level.
  • JWT authentication uses a JSON Web Token generated using a private key and application id. JWTs support advanced features such as ACLs and authenticate at the application level, meaning that you can access your Vonage application's settings such as application webhooks and Secure Inbound Media.

We recommend that you use JWT authentication in production for most use-cases. Basic authentication may suffice when trying out the API, such as when using the Messages Sandbox, or for some basic use-cases (e.g. when webhooks are not required).

If you are using our Server SDKs to interact with the Messages API, these can automatically create JWTs for you.

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