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 Vonage account via the Dashboard.

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

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

To make sure node.js is installed, please run the following command in the terminal:

node -v

Install latest version of Vonage Command Line Interface (CLI)

The Vonage 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 CLI with NPM run:

npm install -g @vonage/cli

Set up the Vonage 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:

vonage config:set --apiKey=API_KEY --apiSecret=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.


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.


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

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

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 Vonage 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 Vonage CLI

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

vonage apps:create "My Messages App" messages_inbound_url= messages_status_url= 

This creates a Vonage application with a messages capability, with the webhook URLs configured as specified, and generate a private key file my_messages_app.key and creates/updates vonage_app.json.

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,

  6. In the Status URL box, enter the URL for your message status webhook, for example,

  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.

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

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.

To configure the webhook URLs

In the Dashboard, go to Messages and Dispatch.

TIP: If the Webhook URLs for messages in your Vonage Account are already in production use and you would like a second one for using the Messages API, please email 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, for example:

Webhook URL
Status URL
Inbound URL

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.

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.

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.


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

Write the code

Add the following to app.js:

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

app.use(bodyParser.urlencoded({ extended: true }))'/webhooks/inbound-message', (req, res) => {
});'/webhooks/message-status', (req, res) => {


View full source

Run your code

Save this file to your machine and run it:

node app.js


pip install vonage

Write the code

Add the following to

#!/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()
    return "200"

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

if __name__ == '__main__':"", port=3000)

View full source

Run your code

Save this file to your machine and run it:


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:


Sending a Viber message

The Messages API provides the ability to send messages to various channels, including Facebook Messenger, SMS, WhatsApp and Viber. This tutorial describes using the Messages API to send a Viber message.