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

Configure your prerequisites

There are a few prerequisites that you need to complete before you can work through this tutorial. If you've already completed any of them, feel free to skip that step


You can create a Nexmo a Nexmo account via the Nexmo Dashboard.

Within the Dashboard you can create applications and purchase Nexmo numbers. These activities can also carried out on the command line.

If you want to carry out tasks such as creating applications, purchasing Nexmo numbers and so on, you will need to install the Nexmo CLI. As the Nexmo CLI requires node.js you will need to install node.js first.

The Nexmo CLI allows you to carry out many operations on the command line. Examples include creating applications, purchasing numbers, and linking a number to an application.

To install the Beta version of the CLI with NPM you can use:

npm install nexmo-cli@beta -g

Set up the Nexmo CLI to use your Nexmo API Key and API Secret. You can get these from the settings page in the Nexmo Dashboard.

Run the following command in a terminal, while replacing api_key and api_secret with your own:

nexmo setup api_key api_secret

If you are planning to use JavaScript to develop your application, you'll need to install (or update) the Beta version of the Nexmo Node SDK.

Installation

During Beta, the Node Server SDK can be installed using:

$ npm install --save nexmo@beta

If you already have the Server SDK installed the above command will upgrade your Server SDK to the latest version.

Usage

If you decide to use the Server SDK you will need the following information:

Key Description
NEXMO_API_KEY The Nexmo API key which you can obtain from your Nexmo Dashboard.
NEXMO_API_SECRET The Nexmo API secret which you can obtain from your Nexmo Dashboard.
NEXMO_APPLICATION_ID The Nexmo Application ID for your Nexmo Application which can be obtained from your Nexmo Dashboard.
NEXMO_APPLICATION_PRIVATE_KEY_PATH The path to the private.key file that was generated when you created your Nexmo Application.

These variables can then be replaced with actual values in the Server SDK example code.

There are at least two webhooks you must configure:

  • Message Status webhook
  • Inbound Message webhook

When messages status updates are generated, such as delivered, rejected or accepted, callbacks will be received on the Message Status webhook URL.

When an inbound message is received, a callback with message payload is invoked on the Inbound Message webhook URL.

IMPORTANT: Both webhook URLs should be configured. At the very least your webhook handlers should return 200 responses for both Inbound Message and Message Status callbacks. This ensures potential callback queuing issues are avoided.

To configure the webhook URLs

From Nexmo Dashboard go to Messages and Dispatch.

TIP: If the Webhook URLs for messages in your Nexmo Account are already in production use and you would like a second one for using the Messages API, please email support@nexmo.com and ask for a sub API Key.

Enter your Webhook URLs in the fields labeled Status URL and Inbound URL.

The values you enter for webhook URLs depends on where your webhook server is located. If your server was running on port 3000 on example.com your webhook URLs might be:

Webhook URL
Status URL https://www.example.com:3000/webhooks/message-status
Inbound URL https://www.example.com:3000/webhooks/inbound-message

NOTE: The default method of POST should be used for both of the webhook URLs.

Inbound SMS webhooks

Messages API does not support inbound SMS message and SMS delivery receipt callbacks via the application-specific webhooks described in the previous section. In order to receive callbacks for SMS message and SMS delivery receipts you need to set the account-level webhooks for SMS.

Callback queue

Please note that callbacks emanating from Nexmo, such as those on your Message Status webhook URL and Inbound Message URL, are queued by Nexmo on a per-account basis, not a per-application basis.

To avoid callbacks stalling the callback queue, please ensure that all applications acknowledge callbacks with a 200 response. Further, it is advisable to cease activity on a test application 24 hours before deleting it, or removing webhook configuration, otherwise it could potentially leave callbacks in your callback queue that will not be acknowledged, and therefore result in delays on callbacks destined for your production applications.

In this code snippet you learn how to handle an inbound message.

NOTE: Messages API does not support inbound SMS message and SMS delivery receipt callbacks via the application-specific webhooks. In order to receive callbacks for SMS message and SMS delivery receipts you need to set the account-level webhooks for SMS.

Example

Ensure that your inbound message webhook is set in the Dashboard. As a minimum your handler must return a 200 status code to avoid unnecessary callback queuing. Make sure your webhook server is running before testing your Messages application.

Prerequisites

Install dependencies

npm install nexmo

Write the code

Add the following to app.js:

Copy to Clipboard
'use strict';
const express = require('express');
const bodyParser = require('body-parser');
const app = express();

app.use(bodyParser.json())
app.use(bodyParser.urlencoded({ extended: true }))

app.post('/webhooks/inbound-message', (req, res) => {
  console.log(req.body);
  res.status(200).end();
});

app.post('/webhooks/message-status', (req, res) => {
  console.log(req.body);
  res.status(200).end();
});

app.listen(3000)

View full source

Run your code

Save this file to your machine and run it:

node app.js

Prerequisites

Install dependencies

pip install nexmo

Write the code

Add the following to app.py:

Copy to Clipboard
#!/usr/bin/env python3
from flask import Flask, request, jsonify
from pprint import pprint

app = Flask(__name__)

@app.route("/webhooks/inbound-message", methods=['POST'])
def inbound_message():
    data = request.get_json()
    pprint(data)
    return "200"

@app.route("/webhooks/message-status", methods=['POST'])
def message_status():
    data = request.get_json()
    pprint(data)
    return "200"

if __name__ == '__main__':
    app.run(host="www.example.org", port=3000)

View full source

Run your code

Save this file to your machine and run it:

python3 app.py

If you want to test your application locally you can use Ngrok.

See our information on Using Ngrok for local development

If using Ngrok in this manner you would use the Ngrok URLs for your webhook URLs:

  • https://abcdef1.ngrok.io:3000/webhooks/inbound-message
  • https://abcdef1.ngrok.io:3000/webhooks/message-status

Sending a Facebook message with failover

The Dispatch API provides the ability to create message workflows with failover to secondary channels. This task looks at using the Dispatch API to send a Facebook message with failover to the SMS channel.

Steps