Configure your prerequisites

You can create a Vonage account via the Dashboard.

Within the Dashboard you can create Applications and purchase Vonage numbers. You can also perform these tasks using the Nexmo CLI.

If you want to carry out tasks such as creating applications, purchasing Vonage 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 Vonage API Key and API Secret. You can get these from the settings page in the 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 Vonage Node Server 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:

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

Create your 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 Vonage 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 Applications in the Dashboard, click the Create a new application button.

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. In the Inbound URL box, enter the URL for your inbound message webhook, for example, https://example.com/webhooks/inbound-message.

6. In the Status URL box, enter the URL for your message status webhook, for example, https://example.com/webhooks/message-status.

7. Click the Generate new application button. You are now taken to the next step of the Create Application procedure where you can link a Vonage 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 Linked external accounts tab, and then click the corresponding Link button for the account you want to link to.

You have now created your application.

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.

To configure the webhook URLs

In the Dashboard, go to Messages and Dispatch.

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, for example:

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.

Webhook queue

Please note that webhooks emanating from Vonage, such as those on your Message Status webhook URL and Inbound Message URL, are queued by Vonage on a per-message basis.

Please ensure that all applications acknowledge webhooks with a 200 response.

Signed webhooks

In order to validate the origin of your webhooks, you can validate the signature of the webhooks, see instructions here

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

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.

npm install @vonage/server-sdk

'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)

node app.js

pip install vonage

#!/usr/bin/env python3
from pprint import pprint
from flask import Flask, request

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)

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/webhooks/inbound-message
• https://abcdef1.ngrok.io/webhooks/message-status