Join us in San Francisco on the 29/30th of October for two days of developer workshops and technical talks
Learn More

Messages API Overview

The Messages API allows you to send and in some cases receive messages over the following communications channels:

Further channels may be supported in the future.

The following diagram illustrates the relationship between the Messages API and the Dispatch API:

#{alt_text}

Contents

Beta

This API is currently in Beta.

Nexmo 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 Nexmo 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
WhatsApp
Channel Inbound Text Inbound Image Inbound Audio Inbound Video Inbound File Inbound Location
MMS n/a n/a n/a n/a
Facebook Messenger
WhatsApp

Key:

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
NEXMO_API_KEY Nexmo API key which can be obtained from your Nexmo Dashboard.
NEXMO_API_SECRET Nexmo API secret which can be obtained from your Nexmo 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:

    Copy to Clipboard 
    curl -X POST https://api.nexmo.com/v0.1/messages \
     -u "$NEXMO_API_KEY:$NEXMO_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

    Use Cases

    Reference