这份文档还在翻译中,预期年底前完成。欢迎您提供宝贵的意见及建议。

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.


您可以通过 Dashboard 创建 Vonage 帐户。

在 Dashboard 中,您可以创建应用程序并购买 Vonage 号码。您也可以使用 Nexmo CLI 执行这些任务。

如果您想执行创建应用程序、购买 Vonage 号码等任务,则需要安装 Nexmo CLI。由于 Nexmo CLI 需要 node.js,因此您需要先安装 node.js

Nexmo CLI 允许您在命令行执行多项操作。示例包括创建应用程序、购买号码以及将号码链接到应用程序。

要使用 NPM 安装 CLI 的测试版,您可以使用:

npm install nexmo-cli@beta -g

设置 Nexmo CLI 以使用您的 Vonage API 密钥和 API 密码。您可以从 Dashboard 中的设置页面获取。

在终端运行以下命令,同时将 API_KEYAPI_SECRET 替换为您自己的值:

nexmo setup API_KEY API_SECRET

如果您打算使用 JavaScript 开发应用程序,则需要安装(或更新)Vonage Node Server SDK 的测试版。

安装

测试期间,可以使用以下命令安装 Node Server SDK:

$ npm install --save nexmo@beta

如果您已经安装了 Server SDK,则上述命令会将您的 Server SDK 升级到最新版本。

用途

如果您决定使用 Server SDK,则需要以下信息:

说明
NEXMO_API_KEY 您可以从 Dashboard 获取的 Vonage API 密钥。
NEXMO_API_SECRET 您可以从 Dashboard 获取的 Vonage API 密码。
NEXMO_APPLICATION_ID 您可以从 Dashboard 获取的 Vonage 应用程序 ID。
NEXMO_APPLICATION_PRIVATE_KEY_PATH 创建 Vonage 应用程序时生成的 private.key 文件的路径。

然后,可以在 Server SDK 示例代码中将这些变量替换为实际值。

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.

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)

View full source

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)

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

Sending an SMS 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 an SMS message.



Steps