Sending SMS messages with the Messages API

In this tutorial you will see how to send an SMS using the Messages API.

The same steps taken here can be easily modified to send a message across Viber Service Messages, Facebook Messenger, WhatsApp.

Prerequisites

  1. Create a Nexmo Account
  2. Install Node JS - required for using the Nexmo Command Line Interface (CLI).
  3. Install the Beta version of the Nexmo CLI
  4. Install or update the Beta version of the Nexmo Node client library - only required if using Node.
  5. Configure webhooks.
  6. Know how to write a webhook server
  7. Know how to test your webhook server locally

The steps

After the prerequisites have been met, the steps are as follows:

  1. Create a Nexmo Application
  2. Send an SMS message

Create a Nexmo Application

There are two alternative methods for creating a Messages and Dispatch application:

  1. Using the Nexmo CLI
  2. Using the Dashboard

Each of these methods is described in the following sections.

How to create a Messages and Dispatch application using the Nexmo CLI

To create your application using the Nexmo CLI, enter the following command into the shell:

nexmo app:create "My Messages App" --capabilities=messages --messages-inbound-url=https://example.com/webhooks/inbound-message --messages-status-url=https://example.com/webhooks/message-status --keyfile=private.key

This creates a Nexmo application with a messages capability, with the webhook URLs configured as specified, and generate a private key file private.key.

How to create a Messages and Dispatch application using the Dashboard

You can create Messages and Dispatch applications in the Dashboard.

To create your application using the Dashboard:

  1. Under Messages and Dispatch in the Dashboard, click Create an application.

  2. Under Name, enter the Application name. Choose a name for ease of future reference.

  3. Click the button Generate public and private key. This will create a public/private key pair and the private key will be downloaded by your browser.

  4. Under Capabilities select the Messages button.

  5. Enter the URL for your inbound message webhook, for example, https://example.com/webhooks/inbound-message.

  6. Enter the URL for your message status webhook, for example, https://example.com/webhooks/message-status.

  7. Click the Create new application button. You are now taken to the next step of the Create Application procedure where you can link a Nexmo number to the application, and link external accounts such as Facebook to this application.

  8. If there is an external account you want to link this application to, click the corresponding Link button.

You have now created your application.

NOTE: Before testing your application ensure that your webhooks are configured and your webhook server is running.

Send an SMS message

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

In the example code below you will need to replace the following variables with actual values:

Key Description
FROM_NUMBER The phone number you are sending the message from.
TO_NUMBER The phone number you are sending the message to.

NOTE: Don't use a leading + or 00 when entering a phone number, start with the country code, for example 447700900000.

Example

Write the code

Add the following to send-sms.sh:

Copy to Clipboard
curl -X POST https://api.nexmo.com/v0.1/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"
      }
    }
  }'

View full source

Run your code

Save this file to your machine and run it:

bash send-sms.sh

Prerequisites

Install dependencies

npm install nexmo@beta

Write the code

Add the following to send-sms.js:

Copy to Clipboard
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); }
);

View full source

Run your code

Save this file to your machine and run it:

node send-sms.js

This will send an SMS message to the destination number you specified.

TIP: If testing using Curl you will need a JWT. You can see how to create one in the documentation on creating a JWT.

Further reading