Введение

Когда вы отправляете текстовое сообщение с помощью API Vonage, HTTP-ответ сообщает вам, было ли сообщение принято к отправке. Он не сообщает, действительно ли оно достигло телефона получателя.

Чтобы узнать это, вам нужен отчет о доставке. В этом руководстве вы узнаете, как получать отчеты о доставке SMS с помощью Vonage Messages API и Node.js.

Предварительные требования

Перед началом работы убедитесь, что у вас есть следующее:

Установлен Node.js. В этом руководстве используется Node.js 18 или более поздняя версия.

Установлен Node.js. В этом руководстве используется Node.js 18 или более поздняя версия.

Установлен ngrok и настроена бесплатная учетная запись. Вы будете использовать его для предоставления доступа к вашему локальному серверу из интернета, чтобы Vonage мог связаться с вашим вебхуком.

Установлен ngrok и настроена бесплатная учетная запись. Вы будете использовать его для предоставления доступа к вашему локальному серверу из интернета, чтобы Vonage мог связаться с вашим вебхуком.

Установлен Vonage CLI. Выполните npm install -g @vonage/cli для его глобальной установки.

Установлен Vonage CLI. Выполните npm install -g @vonage/cli для его глобальной установки.

Учетная запись Vonage API.

Учетная запись Vonage API.

Как работают отчеты о доставке в Messages API

Когда сообщение доставляется, мобильный оператор отправляет отчет о доставке в Vonage. Если вы настроили вебхук, Vonage пересылает этот отчет на ваш эндпоинт в виде POST-запроса.

Messages API использует для этой цели вебхук статуса сообщения (Message Status). Это эквивалент отчета о доставке (DLR), используемого в SMS API. Вместо одного обратного вызова вы обычно получаете два: первый со статусом submitted (отправлено), когда сообщение принято оператором, и второй со статусом delivered (доставлено), как только оно достигает телефона.

Вебхук статуса Messages API поддерживает следующие значения статусов:

submitted: сообщение принято к доставке

submitted: сообщение принято к доставке

delivered: сообщение доставлено на телефон

delivered: сообщение доставлено на телефон

rejected: оператор отказался доставлять сообщение

rejected: оператор отказался доставлять сообщение

undeliverable: Messages API не смог подключиться к провайдеру обмена сообщениями, возможно, из-за сбоя у провайдера или другого инцидента

undeliverable: Messages API не смог подключиться к провайдеру обмена сообщениями, возможно, из-за сбоя у провайдера или другого инцидента

Более подробную информацию см. в документации по обратным вызовам статуса Messages API.

Настройка ngrok

ngrok — это кроссплатформенный инструмент, который создает общедоступный URL-адрес, указывающий на сервер, работающий на вашем локальном компьютере. Вы будете использовать его для предоставления доступа к вашему вебхуку, чтобы Vonage мог отправлять на него POST-запросы во время разработки.

После установки ngrok и входа в систему выполните следующую команду:

После запуска ngrok отобразит URL-адрес пересылки (Forwarding URL), который выглядит примерно так:

Запишите этот URL; он понадобится вам на следующем шаге.

Примечание: В бесплатном тарифном плане URL-адрес ngrok меняется при каждом перезапуске сервера. Вам нужно будет обновлять URL-адреса вебхуков в панели управления Vonage каждый раз, когда это происходит.

Примечание: В бесплатном тарифном плане URL-адрес ngrok меняется при каждом перезапуске сервера. Вам нужно будет обновлять URL-адреса вебхуков в панели управления Vonage каждый раз, когда это происходит.

Настройка учетной записи Vonage

Переключение на Messages API

Войдите в свою панель управления Vonage API и перейдите в настройки API (API Settings). В разделе Messaging API type выберите Messages API и сохраните изменения.

Это указывает Vonage использовать формат Messages API для всех вебхуков SMS в вашей учетной записи.

Создание приложения Vonage

Messages API использует конфигурацию на уровне приложения, что означает, что ваши URL-адреса вебхуков и учетные данные привязаны к конкретному приложению Vonage и переопределяют настройки на уровне учетной записи.

В панели управления перейдите в раздел приложений и нажмите «Создать новое приложение» (Create a new application). Дайте ему имя, например, SMS Delivery Receipts.

Нажмите «Создать открытый и закрытый ключи» (Generate public and private key). Ваш браузер загрузит файл private.key. Вам нужно будет переместить его в каталог вашего проекта после создания, а затем добавить в .gitignore, чтобы он не попал в систему контроля версий.

В разделе «Возможности» (Capabilities) включите «Сообщения» (Messages) и заполните оба URL-адреса вебхуков, используя ваш URL-адрес пересылки ngrok:

Нажмите «Создать новое приложение» (Generate new application), чтобы сохранить. На странице приложения прокрутите вниз до раздела «Привязать виртуальные номера» (Link virtual numbers) и привяжите номер Vonage, который вы будете использовать для отправки SMS.

Настройка проекта Node.js

Откройте терминал, создайте новый каталог для вашего проекта и инициализируйте его:

Установите Express и body-parser:

Вы будете использовать Express для обработки входящих запросов вебхуков, а body-parser — для разбора JSON-полезных нагрузок.

Написание обработчика вебхука

Создайте файл с именем index.js и добавьте следующий код:

Эндпоинт /webhooks/message-status — это место, куда Vonage будет отправлять обновления статуса доставки. Обработчик выводит тело запроса в консоль и возвращает ответ 200.

Эндпоинт /webhooks/inbound-message обрабатывает входящие SMS-сообщения. В этом руководстве вам не нужно ничего делать с входящими сообщениями, но эндпоинт должен существовать и возвращать 200. Без него Vonage будет продолжать повторять попытки обратных вызовов входящих сообщений и может создать очередь.

Запуск приложения

Запустите сервер с помощью следующей команды:

Вы должны увидеть в терминале, что сервер прослушивает порт 3000.

Теперь отправьте текстовое сообщение со своего виртуального номера Vonage на свой мобильный телефон. Вы можете сделать это с помощью Vonage CLI или запроса curl:

Замените YOUR_PHONE_NUMBER на ваш личный номер (включая код страны, без знака +), YOUR_VONAGE_NUMBER на ваш виртуальный номер Vonage, а $JWT на JWT, созданный для вашего приложения.

Чего ожидать

Если сообщение доставлено успешно, вы увидите два обратных вызова в своем терминале. Первый приходит вскоре после отправки:

Через несколько секунд вы получите подтверждение доставки:

Поле message_uuid связывает оба обратных вызова с одним и тем же сообщением. Вы можете использовать его для отслеживания статуса доставки в своем приложении. Например, вы можете сохранить его в базе данных при отправке сообщения и обновить запись, когда придет обратный вызов статуса.

Заключение

Вы настроили приложение Node.js, которое получает отчеты о доставке SMS с помощью Vonage Messages API. В процессе вы настроили приложение Vonage с вебхуком статуса сообщения, написали обработчики для эндпоинтов статуса и входящих сообщений, а также протестировали полный процесс доставки.

Отсюда вы можете расширить этот проект, чтобы: