---
title: "Совершайте исходящие звонки (API)"
description: "Запускайте исходящие звонки с ИИ из собственного кода — для опросов, последующих контактов или подтверждений."
---
Исходящие звонки позволяют передать ThunderPhone номер назначения и
конфигурацию агента, чтобы ИИ совершил звонок от вашего имени. Типичные сценарии:
- Подтверждение записей
- Повторные звонки для опросов
- Повторные обращения после пропущенного звонка
- Уведомления в стиле диспетчеризации
Нужно обзвонить целый список? Функция панели управления
[**Кампании**](/ru/guides/outbound-campaigns)
(`/dashboard/campaigns`) принимает CSV-файл с контактами и самостоятельно
обрабатывает окна звонков с учётом часовых поясов, параллельность и политику
повторных попыток. В этом руководстве рассматриваются отдельные программные звонки.
## Предварительные требования
Используйте номер, принадлежащий вам через
[VoIP-подключение](/api-reference/voip-connections), или запросите разрешение
на использование ваших номеров ThunderPhone для исходящих звонков на странице
Phone Numbers. Номера ThunderPhone изначально поддерживают только входящие звонки. ThunderPhone рассматривает каждый
запрос вручную; после одобрения эти номера могут совершать звонки в пределах
утверждённого дневного лимита (сбрасывается в 00:00 UTC) и запускать кампании,
а вы можете запросить более высокий лимит. Клиентские VoIP-номера не имеют дневного лимита, поэтому мы рекомендуем
их для исходящих звонков. См.
[Подключение собственных номеров](/ru/guides/bring-your-own-numbers).
Запрос в стиле исходящих звонков обычно начинается с того, что агент
представляется и объясняет цель звонка — «Здравствуйте, вас беспокоит Acme, чтобы
подтвердить вашу запись на завтра на 15:00…» Установите для
`outbound_speak_order` значение `agent_first` (по умолчанию).
Исходящие звонки возвращают `402 Payment Required`, если баланс ≤
`$0.00`. Пополните баланс или включите автопополнение в разделе
**Организация → Настройки оплаты** на панели управления. Ваш ключ `sk_live_`
может проверить баланс с помощью
[`GET /v1/billing`](/api-reference/billing#get-billing-account), но
не может пополнять баланс или изменять настройки автопополнения.
## Совершите звонок с сохранённым агентом
Самый простой способ — указать агента по id:
```bash
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
}'
```
Ответ:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` означает лишь, что запрос принят — звонок
**ещё не подключён**. Запрашивайте
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
для получения текущего статуса (`in_progress` → `completed` / `failed`).
## Совершите звонок со встроенной конфигурацией
Если вам нужна разовая подсказка, которую не стоит сохранять как агента,
передайте `config`. Структура соответствует схеме ответа вебхука
[`call.incoming`](/ru/webhooks/call-incoming):
```bash
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`](/ru/webhooks/events) —
это самый быстрый способ узнать, что звонок завершён. Если вы не можете принимать входящие
вебхуки, опрашивайте `GET /v1/calls/{call_id}` каждые несколько секунд; после завершения звонка
запись включает `end_reason`, `duration_seconds` и URL
записи.
Если ваш агент настроен на извлечение структурированных данных после звонка,
эти данные доставляются отдельно после завершения финализации.
### Передача переменных для конкретного звонка сохранённому агенту
Сохранённые агенты могут использовать в тексте промпта заполнители, такие как `{{name}}` или `{{name|there}}`.
При совершении исходящего звонка с `agent_id` передавайте
`variables` со значениями для этого звонка:
```json
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}
```
Используйте строковые значения с ключами, соответствующими именам заполнителей. Эти переменные применяются к
сохранённым агентам; встроенный пример `config` из этого руководства их не использует.
## Сценарии ошибок, которые стоит обработать
| Ошибка | Решение |
|-------|-----|
| `402 Payment Required` | Пополните баланс или включите автопополнение |
| `400` с `code: destination_not_allowed` | ThunderPhone не звонит на этот номер: недействительные номера, номера экстренных служб, номера с повышенной стоимостью, короткие номера или номера в странах под санкциями. С номеров ThunderPhone доступны только обычные номера США и Канады (без номеров с повышенной стоимостью). `reason` указывает причину; см. [заблокированные направления](/api-reference/outbound-calls#blocked-destinations) |
| `409` с `retryable: false` для номера ThunderPhone | Следуйте `code`: запросите исходящие звонки на странице «Номера телефонов», дождитесь рассмотрения заявки или используйте другой подходящий номер |
| `429` с `code: platform_outbound_daily_limit_reached` | Организация исчерпала доступные на сегодня исходящие звонки с номеров ThunderPhone. Дождитесь `resets_at` (00:00 UTC), запросите более высокий лимит на странице «Номера телефонов» или звоните с номера в собственном VoIP-подключении |
| `429` с `code: concurrent_call_limit_reached` | У организации столько же активных звонков, сколько допускает её [лимит одновременных звонков](/api-reference/introduction#call-limits) (по умолчанию 20, включая входящие, исходящие, веб- и тестовые звонки). Повторите попытку через указанное в заголовке `Retry-After` число секунд или после завершения звонка; напишите по email support@thunderphone.com, чтобы увеличить лимит |
| `429` с `code: same_number_too_soon` | Вы звонили на тот же `to_number` менее 10 секунд назад. Повторите попытку через указанное в заголовке `Retry-After` число секунд |
| `409` с `retryable: false` для клиентского VoIP-номера | Исправьте состояние, указанное в `code`; при ошибках верификации выполните [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| Конфликт идемпотентности `409` | Используйте ключ повторно только с исходным нормализованным запросом или отправьте новый ключ |
| `404 from_number is not registered to this organization` | Убедитесь, что `from_number` соответствует активному номеру телефона в вашей организации. Этот ответ также возвращается для номера, который уже подключается, не удалось подключить, отключается или отключён |
| `500` только с полем `detail` | Исходящий транк не настроен. Обратитесь в поддержку; это не проблема состояния номера, которую вы можете исправить |
| `502 Bad Gateway` | Временная ошибка SIP / LiveKit; повторить попытку безопасно |
Полный стабильный список кодов соответствия требованиям и обе формы ответа `409` приведены в
[справочнике по исходящим звонкам](/api-reference/outbound-calls#error-responses).
Если активный номер становится неподходящим после принятия запроса, но до
совершения звонка, финальная проверка возвращает неповторяемую полезную нагрузку `409`.
## Управление временем ожидания
Исходящие звонки, которые длятся долго из-за медленного ответа вызываемого абонента
(деревья IVR, очереди), можно ограничить с помощью `max_hold_seconds`:
```json
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}
```
Агент завершает вызов, если за последние
N секунд не получал аудио от человека. По умолчанию — 900 секунд (15 минут).
---
## Следующие шаги
Все поля запроса и коды ошибок.
Передавайте завершённые исходящие звонки в свою систему.
Автопополнение, чтобы исходящие звонки не завершались ошибкой из-за баланса.
Выполните пробный запуск исходящего агента перед продакшеном.