Совершайте исходящие звонки (API)

Запускайте исходящие звонки с ИИ из собственного кода — для опросов, последующих контактов или подтверждений.

Исходящие звонки позволяют передать ThunderPhone номер назначения и конфигурацию агента, чтобы ИИ совершил звонок от вашего имени. Типичные сценарии:

• Подтверждение записей
• Повторные звонки для опросов
• Повторные обращения после пропущенного звонка
• Уведомления в стиле диспетчеризации

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

1. Выберите номер с поддержкой исходящих звонков

   Используйте номер, принадлежащий вам через VoIP-подключение, или запросите разрешение на использование ваших номеров ThunderPhone для исходящих звонков на странице Phone Numbers. Номера ThunderPhone изначально поддерживают только входящие звонки. ThunderPhone рассматривает каждый запрос вручную; после одобрения эти номера могут совершать звонки в пределах утверждённого дневного лимита (сбрасывается в 00:00 UTC) и запускать кампании, а вы можете запросить более высокий лимит. Клиентские VoIP-номера не имеют дневного лимита, поэтому мы рекомендуем их для исходящих звонков. См. Подключение собственных номеров.

2. Создайте агента

   Запрос в стиле исходящих звонков обычно начинается с того, что агент представляется и объясняет цель звонка — «Здравствуйте, вас беспокоит Acme, чтобы подтвердить вашу запись на завтра на 15:00…» Установите для outbound_speak_order значение agent_first (по умолчанию).

3. Поддерживайте положительный баланс

   Исходящие звонки возвращают 402 Payment Required, если баланс ≤ $0.00. Пополните баланс или включите автопополнение в разделе Организация → Настройки оплаты на панели управления. Ваш ключ sk_live_ может проверить баланс с помощью GET /v1/billing, но не может пополнять баланс или изменять настройки автопополнения.

Совершите звонок с сохранённым агентом#

Самый простой способ — указать агента по id:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "agent_id":    12
  }'

Ответ:

{ "call_id": 987654321, "status": "initiated" }

Совершите звонок со встроенной конфигурацией#

Если вам нужна разовая подсказка, которую не стоит сохранять как агента, передайте config. Структура соответствует схеме ответа вебхука call.incoming:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Отслеживание звонка#

Параллельно подпишитесь на вебхук telephony.complete — это самый быстрый способ узнать, что звонок завершён. Если вы не можете принимать входящие вебхуки, опрашивайте GET /v1/calls/{call_id} каждые несколько секунд; после завершения звонка запись включает end_reason, duration_seconds и URL записи.

Если ваш агент настроен на извлечение структурированных данных после звонка, эти данные доставляются отдельно после завершения финализации.

Передача переменных для конкретного звонка сохранённому агенту#

Сохранённые агенты могут использовать в тексте промпта заполнители, такие как {{name}} или {{name|there}}. При совершении исходящего звонка с agent_id передавайте variables со значениями для этого звонка:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Используйте строковые значения с ключами, соответствующими именам заполнителей. Эти переменные применяются к сохранённым агентам; встроенный пример config из этого руководства их не использует.

Сценарии ошибок, которые стоит обработать#

Полный стабильный список кодов соответствия требованиям и обе формы ответа 409 приведены в справочнике по исходящим звонкам. Если активный номер становится неподходящим после принятия запроса, но до совершения звонка, финальная проверка возвращает неповторяемую полезную нагрузку 409.

Управление временем ожидания#

Исходящие звонки, которые длятся долго из-за медленного ответа вызываемого абонента (деревья IVR, очереди), можно ограничить с помощью max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Агент завершает вызов, если за последние N секунд не получал аудио от человека. По умолчанию — 900 секунд (15 минут).

Следующие шаги#