ThunderPhone v3 уже доступен.Самостоятельный запуск — от 2 ¢/мин.Читать анонс

Contact centers

Подключение из Amazon Connect

Направляйте звонки из Amazon Connect AI-агенту ThunderPhone по SIP с идентификатором контакта и UUI, а затем продолжайте сценарий после передачи звонка агентом.

Ваш поток Amazon Connect передаёт звонящего агенту вместе с идентификатором контакта и любыми заданными UUI. Когда агент завершает вызов, ваш поток продолжается, а Lambda получает сведения о передаче по идентификатору контакта.

Перед началом работы

  • Агент ThunderPhone и ключ API организации.
  • Коннектор Amazon Connect Внешняя передача голоса. Сначала запросите увеличение квоты «Коннекторы внешней передачи голоса на аккаунт»: меню остаётся скрытым, пока AWS не одобрит запрос. AWS взимает плату за каждый коннектор в день ($100 в день с 21 июля 2025 года) плюс поминутное использование.

1. Создайте SIP-эндпоинт

В документации коннектора не описана SIP-аутентификация Digest, поэтому создайте эндпоинт, принимающий вызовы по адресу источника:

curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 12,
    "name": "Amazon Connect",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["CONNECT_SIGNALLING_RANGE_1", "CONNECT_SIGNALLING_RANGE_2"]
  }'

Получите у AWS диапазоны SIP-сигнализации коннектора для вашего региона. Каждый диапазон должен быть публичным диапазоном IPv4 /16 или уже (IPv6 /48 или уже). См. Платформы, аутентифицирующиеся по исходному IP-адресу для ознакомления с правилами и риском использования адреса, общего для всех клиентов платформы. Сохраните sip_uri из ответа, например sip:agent-12-jhxmginwjx@sip.thunderphone.com.

2. Отправляйте вызовы с контекстом

  1. В консоли Amazon Connect откройте Внешние голосовые системы → Интеграции передачи голоса и выберите Создать.
  2. Выберите тип назначения (SBC) и добавьте исходящий маршрут с хостом sip.thunderphone.com, портом 5061 и протоколом TLS. Эндпоинту требуется TLS или TCP (порт 5060); UDP он отклоняет. AWS не документирует, какие протоколы поддерживает коннектор, поэтому подтвердите у AWS, что он может использовать один из них.
  3. В вашем потоке добавьте блок Перевести на номер телефона, задайте для Перевести на значение Внешняя голосовая система и настройте:
    • ARN назначения: коннектор.
    • Пользователь назначения: часть пользователя из sip_uri эндпоинта, например agent-12-jhxmginwjx.
    • UUI (необязательно): контекст для агента. Connect отправляет его в шестнадцатеричном кодировании.
    • Возобновить поток после отключения: Да, чтобы поток продолжался, когда агент завершит вызов.

Connect отправляет идентификатор контакта в X-Amzn-ConnectContactId. ThunderPhone сохраняет его как external_call_id вызова, благодаря чему ваш поток находит вызов позже. UUI поступает в промпт как {{sip_uui}}. Сторонние интеграции документируют заголовок идентификатора контакта, но документация AWS — нет, поэтому проверьте его при первом тестовом вызове.

3. Получите вызов обратно

AWS не документирует способ для Connect читать заголовки в BYE или принимать REFER от агента. Поэтому агент возвращает вызов: прощается и завершает вызов, а ваш сценарий продолжается после блока перевода. Добавьте этот номер перевода (см. Добавление номера перевода):

{"name": "Amazon Connect", "action": "return"}

Затем получите данные передачи с помощью блока Вызвать функцию AWS Lambda после перевода. Lambda ищет вызов по идентификатору контакта:

import json
import os
import urllib.error
import urllib.parse
import urllib.request
 
 
def lambda_handler(event, context):
    contact_id = event["Details"]["ContactData"]["ContactId"]
    url = "https://api.thunderphone.com/v1/calls/handoff?" + urllib.parse.urlencode(
        {"external_call_id": contact_id}
    )
    request = urllib.request.Request(
        url, headers={"Authorization": "Bearer " + os.environ["THUNDERPHONE_API_KEY"]}
    )
    try:
        with urllib.request.urlopen(request, timeout=5) as response:
            call = json.load(response)
    except (urllib.error.URLError, TimeoutError):
        return {"found": "false"}
    handoff = call.get("handoff") or {}
    return {
        "found": "true",
        "intent": handoff.get("intent") or "",
        "summary": handoff.get("summary") or "",
    }

Блок возвращает плоскую карту, поэтому сценарий может ветвиться по intent или задать summary как атрибут контакта для человека, который принимает вызов. Запускайте блок синхронно (до 8 секунд) и храните ключ API в зашифрованном виде, например в AWS Secrets Manager. Поля ответа описаны в разделе Поиск переданного вызова.

Проверьте

Позвоните на номер в вашем экземпляре Connect, который ведёт к блоку перевода, попросите агента соединить с человеком и убедитесь, что сценарий продолжается. Затем откройте вызов с помощью GET /v1/calls/{call_id}: в sip_headers должен быть указан x-amzn-connectcontactid, а external_call_id должен совпадать с ContactId, который получает ваша Lambda. Если перевод завершается ошибкой SIP 404, ThunderPhone не нашёл пользовательскую часть конечной точки: она должна быть и в URI запроса, и в заголовке To.

Ограничения

  • AWS не документирует способ читать заголовки в BYE, включая X-TP-Handoff-Id, поэтому идентификатор контакта — единственная связь с вызовом.
  • AWS не документирует максимальную длину UUI для коннектора.
  • Синхронный блок Lambda завершается по тайм-ауту через 8 секунд.