Developer cookbook

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

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

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

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

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

1. Подключите VoIP-номер

   Для исходящих звонков необходимо владеть номером from_number через VoIP-подключение. Демо-номера доступны только для входящих звонков. См. Подключение собственных номеров.

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

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

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

   Исходящие звонки возвращают 402 Payment Required, если баланс ≤ $0.00. Пополните баланс через POST /v1/billing/top-up или включите автопополнение.

Выполните звонок с сохранённым агентом#

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

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":   "+14155550199",
    "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":   "+14155550199",
    "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 записи после завершения звонка.

Режимы ошибок, которые стоит обрабатывать#

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

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

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

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

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