Переадресация телефонного звонка с помощью Voice Proxy на Python и Starlette

Использование голосового прокси для сохранения конфиденциальности личных номеров

Вам знакома эта ситуация: вы заказали доставку, но код домофона вашего подъезда не работает, поэтому курьеру нужно позвонить вам, чтобы завершить заказ. Ни вы, ни курьер не хотите раскрывать друг другу свой личный номер телефона. Это вопрос как конфиденциальности, так и практичности. Звонящие с большей вероятностью ответят на номер с привычным кодом региона, чем с неизвестным.

Переадресация вызовов позволяет направлять звонки через промежуточный номер, сохраняя личные номера в тайне. Эта схема известна как голосовой прокси.

В этом учебном пособии мы будем использовать Starlette и Vonage для создания голосового прокси на Python. Starlette отвечает за логику сервера, а Vonage — за телефонию. Читайте дальше, чтобы узнать о каждом компоненте перед прохождением руководства, или перейдите сразу к README, чтобы запустить код.

Что такое Starlette?

Если вы разработчик на Python, то, вероятно, знакомы с некоторыми из самых популярных фреймворков, от Flask до Django и FastAPI. Каждый из них предоставляет структуру и определенный подход к разработке на основе HTTP, но в своей основе все они разделяют фундаментальный шаблон маршрутизации запросов к обработчикам и возврата ответов. Starlette — это легковесный инструментарий ASGI, который лежит в основе FastAPI и может использоваться напрямую, когда вам нужен минимальный, но полностью асинхронный веб-фреймворк без всех дополнительных функций.

Что такое ASGI и как Starlette использует его?

Интерфейс асинхронного шлюза серверов (ASGI) — это спецификация (или соглашение о вызовах) для веб-серверов для перенаправления запросов в асинхронные фреймворки Python. ASGI можно представить как a contract that defines how web servers interact with Python applications. Сигнатура интерфейса выглядит следующим образом:

Параметры в этом интерфейсе определяются следующим образом:

• scope — это словарь метаданных, описывающий входящий запрос. Этот параметр помогает определить, какое соединение необходимо создать, чтобы связь между сервером и приложением Python была успешной.

scope — это словарь метаданных, описывающий входящий запрос. Этот параметр помогает определить, какое соединение необходимо создать, чтобы связь между сервером и приложением Python была успешной.

• receive — это вызываемый объект, используемый для приема и обработки событий от клиента. Он возвращает словарь, представляющий получаемые события.

receive — это вызываемый объект, используемый для приема и обработки событий от клиента. Он возвращает словарь, представляющий получаемые события.

• send — это вызываемый объект, который отправляет события обратно клиенту. Он вызывается для формирования и отправки ответа.

send —- это вызываемый объект, который отправляет события обратно клиенту. Он вызывается для формирования и отправки ответа.

Пример полноценного ASGI-приложения выглядит следующим образом:

Этот паттерн абстрагирует Starlette, избавяя вас от необходимости писать каждый контракт вручную. Без Starlette вашему веб-приложению пришлось бы обрабатывать маршрутизацию с помощью множества вложенных инструкций if/else:

Starlette инкапсулирует всю шаблонную избыточность в чистый API:

Приведенный выше код можно разбить на следующие строительные блоки:

• Объект Route сопоставляет путь URL и метод HTTP с функцией. В этом примере «/users» и метод GET сопоставлены с функцией list_users.

Объект Route сопоставляет путь URL и метод HTTP с функцией. В этом примере «/users» и метод GET сопоставлены с функцией list_users.

• Объект Request, который принимают в качестве параметра как list_users, так и get_user, содержит метаданные о входящем соединении (scope), а также функцию, обрабатывающую сообщение, полученное от клиента (вызываемый объект receive).

Объект Request, который принимают в качестве параметра как list_users, так и get_user, содержит метаданные о входящем соединении (scope), а также функцию, обрабатывающую сообщение, полученное от клиента (вызываемый объект receive).

• Объект JSONResponse обрабатывает сообщение, которое будет отправлено обратно клиенту (вызываемый объект send).

Объект JSONResponse обрабатывает сообщение, которое будет отправлено обратно клиенту (вызываемый объект send).

• async def — это синтаксис Python для определения функции-сопрограммы (корутины), который обеспечивает асинхронную работу без блокировки.

async def — это синтаксис Python для определения функции-сопрограммы (корутины), который обеспечивает асинхронную работу без блокировки.

Поскольку Starlette управляет маршрутизацией и обработкой запросов/ответов без включения дополнительных уровней, таких как ORM, аутентификация или шаблонизация, он идеально подходит для такого специализированного проекта, как этот голосовой прокси.

Вы можете обратиться к проекту в качестве примера минимального приложения на Starlette. Чтобы узнать больше о Starlette, обратитесь к .

Что такое голосовой прокси и как он работает?

Голосовой прокси (также известный как маскирование вызовов) — это метод, с помощью которого телефонные звонки перенаправляются в пункты назначения через промежуточный телефонный номер. Конечный телефонный номер маскируется за промежуточным номером, сохраняя тем самым конфиденциальность. Каждый участник получает временный номер, позволяющий им общаться напрямую в режиме реального времени без разглашения личного номера ни одной из сторон. После завершения звонка промежуточный номер освобождается и может быть использован в другом прокси.

Когда кто-то звонит на номер голосового прокси, вызов принимается приложением, которое затем перенаправляет его на реальный номер предполагаемого получателя, не раскрывая его звонящему. Аналогичным образом человек, принимающий вызов, видит только промежуточный номер, а не реальный номер звонящего, обеспечивая тем самым взаимную анонимность телефонных номеров.

Маскирование вызовов полезно в сценариях одноранговой торговли, подобных описанному ранее в этом руководстве, и помогает отслеживать и контролировать вызовы и транзакции. С помощью Vonage Voice и Vonage Python SDK вы можете реализовать маскирование вызовов с помощью API, который абстрагирует всю сложную инфраструктуру телефонии.

Vonage Voice и объекты управления вызовами (NCCO)

API Vonage Voice позволяет объединять людей по всему миру и автоматизировать голосовые взаимодействия, расширяя возможности вашего продукта. Вы можете программно управлять голосовыми вызовами, используя две взаимодополняющие модели:

• Одна инициируется вашим приложением с помощью вызовов REST API или SDK.

Одна инициируется вашим приложением с помощью вызовов REST API или SDK.

• Другая запрашивается у вашего приложения Vonage с помощью веб-хуков и инструкций Call Control Objects (NCCO).

Другая запрашивается у вашего приложения Vonage с помощью веб-хуков и инструкций Call Control Objects (NCCO).

Этот двойной подход поддерживает гибкую обработку вызовов для реализации различных сценариев звонков и вариантов использования программируемой голосовой связи: от простых уведомлений до сложных сценариев контакт-центра и интеграции с ИИ.

NCCO — это структура на основе JSON, которая определяет, что должно происходить во время вызова. Вы возвращаете ее в ответ на запрос веб-хука Vonage при установлении соединения.

К распространенным действиям NCCO относятся:

• talk: преобразование текста в речь и воспроизведение его для вызывающего абонента

talk: преобразование текста в речь и воспроизведение его для вызывающего абонента

• stream: воспроизведение аудиофайла

stream: воспроизведение аудиофайла

• record: Записать аудио вызова

record: Записать аудио вызова

• connect: Подключить другого участника к разговору

connect: Подключить другого участника к разговору

Для этого приложения мы будем использовать действие connect, чтобы соединить вызов с различными конечными точками. Конечной точкой может быть другой номер телефона, WebSocket или SIP-конечная точка. В этом туториале мы подключимся к номеру телефона, чтобы скрыть исходные номера с обеих сторон вызова.

Обратитесь к документации по Voice API и NCCO, чтобы узнать больше.

Туннелирование

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

Вы можете узнать об использовании ngrok с Vonage в документации.

Туториал: Переадресация телефонного звонка через Voice Proxy с использованием Python, Starlette и Vonage

В этом туториале мы будем использовать Starlette для определения вебхука, к которому Voice API сможет отправлять запросы, и создадим голосовой прокси с помощью действия NCCO connect. Рабочий процесс выглядит следующим образом:

• Конечный пользователь набирает виртуальный номер Vonage.

Конечный пользователь набирает виртуальный номер Vonage.

• Vonage отправляет запрос на вебхук, определенный на сервере Starlette.

Vonage отправляет запрос на вебхук, определенный на сервере Starlette.

• Сервер возвращает действие NCCO connect.

Сервер возвращает действие NCCO connect.

• Vonage перенаправляет вызов на настроенный номер назначения.

Vonage перенаправляет вызов на настроенный номер назначения.

• Ни одна из сторон не видит реальные номера телефонов — они видят только виртуальный номер.

Ни одна из сторон не видит реальные номера телефонов — они видят только виртуальный номер.

Посмотрите полный код этого туториала на GitHub и следуйте инструкциям в , чтобы запустить его. Ниже мы рассмотрим наиболее важные части кода.

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

• Python 3.10+

Python 3.10+

• Учетная запись Vonage API и виртуальный номер

Учетная запись Vonage API и виртуальный номер

• Установка Vonage CLI (необязательно)

Установка Vonage CLI (необязательно)

• Учетная запись и установка ngrok

Учетная запись и установка ngrok

Настройка туториала

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

Вам потребуется создать голосовое приложение Vonage для использования в этом туториале. Сделать это можно двумя способами:

• Через панель управления разработчика Vonage

Через панель управления разработчика Vonage

• Через Vonage CLI

Через Vonage CLI

В любом случае убедитесь, что вы выбрали и привязали номер с поддержкой голосовой связи для использования в этом туториале.

Настройка среды разработки

Следуйте инструкциям в , чтобы создать виртуальную среду и установить зависимости проекта:

А затем:

Узнайте больше о виртуальных средах из нашей статьи в блоге.

Настройка переменных окружения

Скопируйте и переименуйте файл env.template:

Заполните файл вашим виртуальным номером Vonage и номером устройства, которое вы будете использовать для тестирования приложения голосового прокси. Это номер, к которому Vonage подключится с помощью виртуального номера для маскировки исходного номера:

Запуск туннеля ngrok

Чтобы сделать ваше приложение доступным для Vonage, используйте ngrok для создания туннеля к публичному URL-адресу на порту 8000:

Чтобы узнать больше об использовании ngrok с приложениями Vonage, прочитайте нашу статью в блоге.

Определение и настройка вебхуков с помощью Starlette и Vonage

Приложение Starlette можно найти в файле server.py file. Абстрагировавшись от всей шаблонной логики ASGI, Starlette позволяет нам создать голосовой прокси менее чем из 100 строк кода, в то время как Vonage берет на себя сложность телефонии через API на базе SDK с поддержкой Pydantic.

Здесь мы определяем класс VoiceProxy, который расширяет класс HTTPEndpoint от Starlette. Этот класс позволяет нам настраивать обработчики HTTP как методы одного класса, а не писать единую функцию, требующую ручной проверки метода запроса.

Метод GET отвечает за возврат действия NCCO, которое создает маскировку вызова с помощью connect. В данном случае connect настроен на использование конечной точки в виде номера телефона. Это номер, который получит замаскированный вызов с настроенного номера отправителя, которым в данном сценарии является ваш виртуальный номер Vonage:

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

Голосовые приложения Vonage также могут быть настроены с вебхуком событий. Это конечная точка, на которую отправляются запросы по мере возникновения голосовых событий. В нашем приложении голосового прокси мы используем метод post для логирования нашего голосового рабочего процесса и демонстрации маскировки вызова в действии:

Наконец, мы регистрируем наши маршруты и передаем их в приложение Starlette:

Запустите приложение с помощью uvicorn:

Настройка вебхуков в Vonage

Чтобы Vonage мог связаться с вашим приложением, используйте публичный URL-адрес, созданный ngrok. Отредактируйте свое голосовое приложение на панели управления разработчика Vonage так, чтобы URL-адрес ответа (Answer URL) и URL-адрес событий (Event URL) указывали на URL-адрес, предоставленный ngrok. Он будет выглядеть примерно так:

Обязательно установите подходящие методы запросов для каждого из них:

• GET для URL-адреса ответа

GET для URL-адреса ответа

• POST для URL-адреса событий

POST для URL-адреса событий

Попробуйте в деле!

Для тестирования приложения вам понадобятся два устройства, способные совершать и принимать телефонные звонки.

• С устройства с номером телефона, не настроенным для использования с приложением, позвоните на свой виртуальный номер Vonage.

С устройства с номером телефона, не настроенным для использования с приложением, позвоните на свой виртуальный номер Vonage.

• Вы должны услышать приветствие синтезатора речи, за которым последует сигнал вызова, так как Vonage вызывает тестовый номер, предоставленный вами приложению.

Вы должны услышать приветствие синтезатора речи, за которым последует сигнал вызова, так как Vonage вызывает тестовый номер, предоставленный вами приложению.

• Устройство, связанное с тестовым номером, должно зазвонить, но вместо номера устройства, с которого вы совершили первоначальный вызов, будет отображаться ваш виртуальный номер. Другими словами, виртуальный номер Vonage маскирует ваш личный номер телефона.

Устройство, связанное с тестовым номером, должно зазвонить, но вместо номера устройства, с которого вы совершили первоначальный вызов, будет отображаться ваш виртуальный номер. Другими словами, виртуальный номер Vonage маскирует ваш личный номер телефона.

Вы можете проверить журналы событий вызовов, чтобы убедиться в этом окончательно:

В этом примере:

• 12015551497 — промежуточный маскирующий номер.

12015551497 — промежуточный маскирующий номер.

• 18055556289 — номер, инициирующий вызов.

18055556289 — номер, инициирующий вызов.

• 14155555833 — номер, к которому происходит подключение с использованием маскирующего номера.

14155555833 — номер, к которому происходит подключение с использованием маскирующего номера.

Используя прокси, абоненты могут быть соединены друг с другом без раскрытия своих телефонных номеров. Это обеспечивает одноранговое обслуживание клиентов при сохранении их конфиденциальности.

В заключение

В этом руководстве вы создали приложение голосового прокси на Python с использованием Starlette и Vonage Voice API. Голосовой прокси, также известный как маскировка вызовов, перенаправляет звонки через промежуточный виртуальный номер, чтобы ни одна из сторон не видела реальный номер телефона другой стороны. Вы узнали, как легкий инструментарий ASGI от Starlette упрощает обработку вебхуков, как объекты управления вызовами Vonage (NCCO) определяют поведение вызова и как ngrok открывает ваш локальный сервер для Vonage во время разработки. В итоге у вас получилось рабочее приложение, которое соединяет двух абонентов через виртуальный номер Vonage, сохраняя конфиденциальность обоих номеров — этот шаблон находит реальное применение в службах доставки, такси, на торговых площадках и в платформах обслуживания клиентов. Чтобы узнать больше о том, как использовать Vonage для интеграции голосовых функций в ваши приложения и сервисы, ознакомьтесь с нашими учебными материалами по Voice или посмотрите видео ниже о том, как автоматизировать звонки с помощью ИИ.

Дополнительное чтение и ссылки

• : Starlette — это легкий фреймворк/инструментарий ASGI, который идеально подходит для создания асинхронных веб-сервисов на Python.

: Starlette — это легкий фреймворк/инструментарий ASGI, который идеально подходит для создания асинхронных веб-сервисов на Python.

• : Демонстрационное приложение, показывающее, как создать сервис голосового прокси (маскировки вызовов) с использованием Vonage Voice API и Starlette, легкого ASGI-фреймворка для Python.

: Демонстрационное приложение, показывающее, как создать сервис голосового прокси (маскировки вызовов) с использованием Vonage Voice API и Starlette, легкого ASGI-фреймворка для Python.

• Создание ИИ-голосовых агентов в реальном времени с помощью Pipecat, AgentCore и Vonage: узнайте, как создать ИИ-голосового агента с использованием Vonage, Pipecat, AWS Nova Sonic и AgentCore для телефонных разговоров в реальном времени.

Создание ИИ-голосовых агентов в реальном времени с помощью Pipecat, AgentCore и Vonage: узнайте, как создать ИИ-голосового агента с использованием Vonage, Pipecat, AWS Nova Sonic и AgentCore для телефонных разговоров в реальном времени.

• Создание системы конференц-связи на Python: узнайте, как подключить несколько участников к одной конференции на Python с помощью Vonage Voice API и фреймворка Flask.

Создание системы конференц-связи на Python: узнайте, как подключить несколько участников к одной конференции на Python с помощью Vonage Voice API и фреймворка Flask.