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.
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:
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:
- Using the Nexmo CLI
- 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:
Under Applications in the Dashboard, click the Create a new application button.
Under Name, enter the Application name. Choose a name for ease of future reference.
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.
Under Capabilities select the Messages button.
In the Inbound URL box, enter the URL for your inbound message webhook, for example,
https://example.com/webhooks/inbound-message
.In the Status URL box, enter the URL for your message status webhook, for example,
https://example.com/webhooks/message-status
.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.
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 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, for example:
Webhook | URL |
---|---|
Status URL | https://www.example.com/webhooks/message-status |
Inbound URL | https://www.example.com/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.
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.
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
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.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)
Run your code
Save this file to your machine and run it:
node app.js
Prerequisites
pip install vonage
Write the code
Add the following to app.py
:
#!/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)
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/webhooks/inbound-message
https://abcdef1.ngrok.io/webhooks/message-status
Sending a Facebook Messenger message
The Messages API provides the ability to send messages to various channels, including Facebook Messenger, SMS, WhatsApp and Viber. This task looks at using the Messages API to send a Facebook Messenger message.Steps