Sending WhatsApp messages with the Messages API

You can use the Messages API to exchange messages with WhatsApp users.

Before continuing with this tutorial you should review the information on Understanding WhatsApp messaging.

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. Contact Nexmo - You will need to obtain a WhatsApp number. Nexmo cannot guarantee you will be assigned a WhatsApp number.
  2. Create a Nexmo Application
  3. Send a WhatsApp 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" https://example.com/webhooks/inbound-message https://example.com/webhooks/message-status --keyfile=private.key --type=messages

How to create a Messages and Dispatch application using the Dashboard

You can now create Messages and Dispatch applications in the Dashboard. This allows you to set webhooks for each application created - this is important for receiving inbound messages and message status updates.

To create your application using the Dashboard:

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

  2. Enter the Application name, which can be anything you like.

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

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

  5. Click the link Generate public/private key pair just below the public key text area. This will create a public/private key pair and the private key will be downloaded by your browser.

  6. Click the Create Application button. You will be taken to phase 2 of the Create Application procedure where you can link external accounts such as Facebook to this application. If you do not have any external accounts listed here, or do not want to link one of those accounts to this application you can click Done.

  7. If there is an external account you want to link this application to, click the corresponding Link button and then click Done.

You have now created your application.

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

Send a WhatsApp message

Please note that free form text messages can only be sent when a customer sends a message to the business first. The business has up to 24 hours from the last moment the customer messages to send a free form message back. After that period a WhatsApp Template (MTM) needs to be used.

If you have not received a message from the customer you will need to send a WhatsApp Template (MTM) before sending a message. You can learn more about this in Understanding WhatsApp Messaging.

If you want to see the code for sending a WhatsApp Template you can view the Sending a WhatsApp Template building block.

Key Description
NEXMO_APPLICATION_ID The ID of the Nexmo Application that you created.
WHATSAPP_NUMBER Your WhatsApp number.
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-whatsapp-message.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": "whatsapp", "number": '$WHATSAPP_NUMBER' },
    "to": { "type": "whatsapp", "number": '$TO_NUMBER' },
    "message": {
      "content": {
        "type": "text",
        "text": "This is a WhatsApp Message sent from the Messages API"
      }
    }
  }'

View full source

Run your code

Save this file to your machine and run it:

$ bash send-whatsapp-message.sh

Write the code

Add the following to app.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": "whatsapp", "number": "TO_NUMBER" },
  { "type": "whatsapp", "number": "WHATSAPP_NUMBER" },
  {
    "content": {
      "type": "text",
      "text": "This is a WhatsApp Message 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 app.js

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