Messages Overview Developer Preview

The Messaging API is a single API that enables easy integration with various communication channels such as: SMS, Facebook Messenger and Viber.

This API is currently in Developer Preview and you will need to request access  to use it.

During Developer Preview we will expand the capabilities of the API. Please visit the API Reference for a comprehensive breakdown and on high level we currently support:

  • Outbound text messages on SMS, Viber Service Messages and Facebook Messenger.
  • Outbound media messages on Facebook Messenger.
  • Inbound text, media and location messages on Facebook Messenger.

There may be bugs and quirks so we'd welcome your feedback - any suggestions you make help us shape the product. If you do need help, please email support@nexmo.com and include Messages API in the subject line. Please note that during the Developer Preview period support times are limited to Monday to Friday.

Contents

In this document you can learn about:

Concepts

To use the Messages API, you may need to familiarise yourself with:

  • Authentication - The Messages API is authenticated with JWT.
  • Workflows - The Workflow API is used to combine messages together with logic to allow for failover.

Getting Started

In this Getting Started section we will show you how you can send an SMS. The same steps taken here can be easily modified to send a message across Viber Service Messages, Facebook Messenger and any future channels that we add.

1. Configure your Delivery Receipt and Inbound Message endpoint with Nexmo

To receive updates about the state of a message (i.e. "delivered" or "read") you have just sent and to receive inbound messages from your customers you will need to configure an endpoint for Nexmo to send message to. If you don't have a webhook server set up you can use a service like requestb.in  for free.

From Nexmo Dashboard  go to Settings  .

Set the HTTP Method to POST and enter your endpoint in the fields labeled Webhook URL for Inbound Message and Webhook URL for Delivery Receipt:

Screenshot

2. Generate a JWT to Authenticate with Nexmo

The Messages API authenticates using JSON Web Tokens (JWTs).

In order to create a JWT to authenticate your requests, you will need to create a Nexmo Voice Application. This can be done under the Voice tab  or using the Nexmo CLI  tool.

You will be asked to provide an Event URL and an Answer URL when creating a Voice Application. These are currently only used by the Voice API and are ignored by the Messages and Workflows APIs. Instead the Messages API and Workflows API use the Delivery Receipt and Inbound Message URLs that you set in Settings  .

Once you have created a Voice application you can use the application ID and private key to generate a JWT. There is more information on Voice Application management  and the use of Nexmo libraries  .

If you're using the Nexmo CLI the command is:

$ JWT="$(nexmo jwt:generate /path/to/private.key \application_id=NEXMO_APPLICATION_ID)"
$ echo $JWT

This JWT will last 15 minutes. After that, you will need to generate a new one. In production systems, it is advisable to generate a JWT dynamically for each request.

3. Send an SMS message with Messages API

Sending an SMS message with the Messages API can be done with one API call, authenticated using the JWT you just created.

Key Description
NEXMO_APPLICATION_ID The ID of the application that you created.
FROM_NUMBER The phone number you are sending the message from in E.164  format. For example 447700900000.
TO_NUMBER The phone number you are sending the message to in E.164  format. For example 447700900000.

Prerequisites

Example

curl -X POST https://api.nexmo.com/beta/messages \
  -H 'Authorization: Bearer $JWT'\
  -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"
      }
    }
  }'
http POST 'https://api.nexmo.com/beta/messages' \
  'Authorization':'Bearer '$JWT\
  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"
    }
  }'
const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: NEXMO_API_KEY,
  apiSecret: NEXMO_API_SECRET,
  applicationId: NEXMO_APPLICATION_ID,
  privateKey: NEXMO_APPLICATION_PRIVATE_KEY_PATH
})

nexmo.channel.send(
  { "type": "sms", "number": "TO_NUMBER" },
  { "type": "sms", "number": "FROM_NUMBER" },
  {
    "content": {
      "type": "text",
      "text": "This is an SMS sent from the Messages API"
    }
  },
  (err, data) => { console.log(data.message_uuid); }
);

Building Blocks

Guides

Reference