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 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:

Follow the steps outlined on the Getting Started with Vonage CLI page to install and configure the command line.

If you are planning to use JavaScript to develop your application, you'll need to install (or update) the Vonage Node Server SDK.

Installation

The Node Server SDK can be installed using:

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 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:

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, 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

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 express body-parser

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.listen(3000);

pip install fastapi[standard]

from pprint import pprint

from fastapi import FastAPI, Request, status

app = FastAPI()


@app.post('/webhooks/message-status', status_code=status.HTTP_200_OK)
async def message_status(request: Request):
    data = await request.json()
    pprint(data)


@app.post('/webhooks/inbound-message')
async def inbound_message(request: Request):
    data = await request.json()
    pprint(data)

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