Введение
Создание приложений с поддержкой голосовой связи раньше требовало работы с аппаратными шлюзами и низкоуровневыми протоколами телефонии. Сегодня Vonage Voice API берет всю эту сложность на себя всего в нескольких строках кода.
В этом учебном пособии вы создадите небольшое приложение на PHP, которое обрабатывает как входящие, так и исходящие телефонные звонки с помощью Vonage Voice API. Вы начнете с возврата сообщения преобразования текста в речь (TTS) любому, кто позвонит на ваш номер Vonage, а затем расширите приложение для программного запуска исходящих вызовов. Наконец, вы сделаете озвученное сообщение динамическим, получая случайную шутку из публичного API.
Tl;dr: Посмотрите пример кода в репозитории Vonage Community на GitHub.
Предварительные требования
Прежде чем начать, убедитесь, что у вас есть следующее:
- Установлен PHP версии 8.3 или выше. Выполните php -v, чтобы проверить версию.
Установлен PHP версии 8.3 или выше. Выполните php -v, чтобы проверить версию.
- Composer для управления зависимостями
для управления зависимостями
- Node.js и npm для установки Vonage CLI
Node.js и npm для установки Vonage CLI
- ngrok (или аналогичный инструмент создания туннелей) для предоставления доступа к вашему локальному серверу из интернета
(или аналогичный инструмент создания туннелей) для предоставления доступа к вашему локальному серверу из интернета
Настройка Vonage CLI
Vonage CLI позволяет управлять вашей учетной записью, создавать приложения и покупать номера прямо из терминала. Установите его глобально с помощью npm:
После установки аутентифицируйте CLI с помощью вашего ключа API и секретного ключа, которые вы найдете в панели управления Vonage API:
Создание приложения Vonage
Приложение Vonage — это контейнер для конфигурации и учетных данных, необходимых вашему коду для взаимодействия с API Vonage. Создайте новый рабочий каталог для вашего проекта, перейдите в него и выполните следующую команду:
Теперь вы создали приложение Vonage. Запишите возвращенный идентификатор приложения (Application ID); он скоро вам понадобится. CLI также сохраняет файл private.key в вашем текущем каталоге; храните его в безопасности, так как мы будем использовать его вместе с идентификатором приложения для аутентификации в Voice API на последующих этапах.
Затем вам нужно приобрести виртуальный номер с поддержкой голосовой связи для привязки к вашему приложению. Найдите доступный номер в вашей стране (при необходимости замените US на ваш двухбуквенный код страны). Номера должны быть в формате E.164: укажите код страны и опустите любые ведущие нули (например, британский номер 07700900001 становится 447700900001):
Выберите номер из полученного списка, а затем купите его, выполнив:
Наконец, привяжите номер к вашему приложению:
Вы можете проверить, правильно ли номер привязан к вашему приложению, выполнив:
Настройка рабочего пространства
В каталоге вашего проекта выполните composer init для начала. Примите все значения по умолчанию и пропустите интерактивное определение зависимостей; мы сделаем это на следующем шаге.
В этом учебном пособии используется Slim Framework для обработки входящих вебхуков от Vonage. Затем установите Slim вместе с его реализацией PSR-7 и библиотекой phpdotenv для управления переменными окружения:
Убедитесь, что файл private.key, полученный при создании приложения, находится в этом каталоге на том же уровне, что и composer.json.
Создайте файл .env в корне проекта для хранения ваших учетных данных:
Добавьте .env и private.key в файл .gitignore, чтобы учетные данные никогда не попадали в систему контроля версий:
Теперь запустите локальный сервер разработки PHP:
Ваше приложение теперь прослушивает порт 8000.
Затем вам нужно предоставить вашему приложению доступ к интернету, чтобы Vonage мог обращаться к вашим вебхукам. Давайте используем для этого ngrok:
Запишите ваш новый URL-адрес ngrok; он понадобится вам для обновления приложения Vonage на следующем шаге.
Перейдите в панель управления Vonage и найдите свое приложение «vonage-calls» на вкладке Applications. Нажмите кнопку Edit, включите переключатель Voice в разделе Capabilities, а затем заполните URL-адреса вебхуков, как показано ниже:
Сохраните изменения, и все готово!
Создание вашего NCCO
Голосовые вызовы Vonage управляются с помощью объектов управления вызовами JSON, называемых NCCO. NCCO — это массив действий в формате JSON, который указывает Vonage, что делать при начале вызова. Некоторые из доступных действий включают:
- connect — подключить вызов к другому номеру
connect — подключить вызов к другому номеру
- record — записать вызов
record — записать вызов
- conversation — создать конференц-связь
conversation — создать конференц-связь
- talk — сгенерировать сообщение с преобразованием текста в речь
talk — сгенерировать сообщение с преобразованием текста в речь
Полный список смотрите в справочнике по NCCO.
Вот NCCO, с которого вы начнете; простое сообщение с преобразованием текста в речь:
Примечание о кастомизации голоса: действие talk поддерживает параметры языка и стиля для управления голосом, используемым для преобразования текста в речь. Полный список доступных голосов см. в справочнике по языкам для преобразования текста в речь.
Примечание о кастомизации голоса: действие talk поддерживает параметры языка и стиля для управления голосом, используемым для преобразования текста в речь. Полный список доступных голосов см. в справочнике по языкам для преобразования текста в речь.
Создание вебхука ответов
Создайте файл public/index.php. Приведенный ниже код инициализирует приложение Slim, загружает ваши переменные окружения, регистрирует обработчик вебхука ответов и возвращает NCCO в виде ответа JSON всякий раз, когда Vonage делает GET-запрос к /webhooks/answer.
Он также регистрирует вебхук событий по адресу /webhooks/event, на который Vonage отправляет обновления о статусе вызова (например, вызов идет, отвечено и завершен) в течение всего жизненного цикла вызова. На данный момент обработчик просто подтверждает получение ответом 204 No Content; в продакшн-приложении вы бы логировали эти события или реагировали на них.
Когда Vonage делает GET-запрос к вашему URL-адресу ответа, обработчик возвращает NCCO в формате JSON. До тех пор, пока ответ представляет собой валидный JSON в правильном формате, Vonage знает, как обработать вызов.
Пришло время протестировать его! Сохраните файл, а затем позвоните на купленный вами виртуальный номер, чтобы услышать сообщение с преобразованием текста в речь.
Совершение исходящего вызова
Вы обработали входящий вызов, теперь давайте инициируем исходящий. Когда вы совершаете исходящий вызов, Vonage по-прежнему обращается к вашему URL-адресу ответа, чтобы узнать, как его обработать, поэтому созданный вами вебхук будет обслуживать оба направления.
Для совершения исходящего вызова нам понадобится SDK Vonage для PHP:
Теперь добавьте следующие инструкции use в верхнюю часть public/index.php после существующих:
Затем добавьте маршрут перед $app->run():
Чтобы инициировать исходящий вызов, перейдите по следующему URL-адресу в вашем браузере, заменив DESTINATION_NUMBER на номер, на который вы хотите позвонить, в формате E.164 (например, 14155550100 для американского номера):
Добавление динамических NCCO
Вы добились того, к чему стремились, но воспроизведение одного и того же сообщения каждый раз становится немного однообразным. Давайте сделаем это динамичным, получая случайную шутку о программировании из JokeAPI и зачитывая ее во время звонка.
Для выполнения HTTP-запросов установите Guzzle:
Добавьте инструкцию use для Guzzle в начале файла index.php:
Теперь обновите обработчик /webhooks/answer для получения шутки и использования ее в качестве произносимого текста:
— это активно поддерживаемый бесплатный API. Параметр type=twopart возвращает шутки с полями завязки и кульминации, а параметр safe-mode отфильтровывает контент для взрослых. Обработчик объединяет их в одну строку, чтобы действие talk могло зачитать ее вслух.
Теперь в любое время, когда Vonage запрашивает ваш URL-адрес ответа (Answer URL), будь то для входящего или инициированного вами исходящего вызова, система будет получать новую шутку о программировании и зачитывать ее. Проверьте это, позвонив на свой номер Vonage или обратившись к эндпоинту /makeCall.
Что дальше?
Вы создали систему голосовых вызовов с преобразованием текста в речь, которая обрабатывает как входящие, так и исходящие вызовы и предоставляет динамический контент.
Отсюда вы можете:
- Создать систему голосовых оповещений: циклически перебирать список контактов, совершать массовые обзвоны и просить получателей нажать клавишу для подтверждения получения
Создать систему голосовых оповещений: циклически перебирать список контактов, совершать массовые обзвоны и просить получателей нажать клавишу для подтверждения получения
- Настроить сообщение в зависимости от того, кто звонит, времени суток или данных из вашей собственной базы данных
Настроить сообщение в зависимости от того, кто звонит, времени суток или данных из вашей собственной базы данных
- Добавить запись звонка с помощью действия записи NCCO и руководства по записи Voice API
Добавить запись звонка с помощью действия записи NCCO и руководства по записи Voice API
- Изучить полный справочник NCCO, чтобы добавлять IVR-меню, конференц-связь и многое другое
Изучить полный справочник NCCO, чтобы добавлять IVR-меню, конференц-связь и многое другое
