> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

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

<Note>
  Нужно обзвонить целый список? Функция панели управления
  [**Кампании**](/ru/guides/outbound-campaigns)
  (`/dashboard/campaigns`) принимает CSV-файл с контактами и сама
  обрабатывает окна звонков с учётом часовых поясов, параллельность и
  правила повторных попыток. В этом руководстве рассматриваются отдельные программные звонки.
</Note>

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

<Steps>
  <Step title="Подключите VoIP-номер">
    Для исходящих звонков необходимо владеть номером `from_number` через
    [VoIP-подключение](/api-reference/voip-connections). Демо-номера
    доступны только для входящих звонков. См.
    [Подключение собственных номеров](/ru/guides/bring-your-own-numbers).
  </Step>

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

  <Step title="Поддерживайте положительный баланс">
    Исходящие звонки возвращают `402 Payment Required`, если баланс ≤
    `$0.00`. Пополните баланс через
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    или включите [автопополнение](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

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

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

```bash theme={null}
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
  }'
```

Ответ:

```json theme={null}
{ "call_id": 987654321, "status": "initiated" }
```

<Warning>
  `status: "initiated"` означает лишь, что запрос принят — звонок
  **ещё не соединён**. Опросите
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call),
  чтобы получить текущий статус (`in_progress` → `completed` / `failed`).
</Warning>

## Выполните звонок со встроенной конфигурацией

Если вам нужен разовый промпт, который не стоит сохранять как агента,
передайте `config`. Его структура соответствует схеме ответа
[вебхука `call.incoming`](/ru/webhooks/call-incoming):

```bash theme={null}
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`](/ru/webhooks/events) —
это самый быстрый способ узнать о завершении звонка. Если вы не можете принимать входящие
вебхуки, опрашивайте `GET /v1/calls/{call_id}` каждые несколько секунд; запись
содержит `end_reason`, `duration_seconds` и URL записи после завершения звонка.

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

| Ошибка                                                    | Решение                                                                                                          |
| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `402 Payment Required`                                    | Пополните баланс или включите автопополнение                                                                     |
| `403` исходящие звонки заблокированы (демо-номер)         | Подключите VoIP-номер                                                                                            |
| `403` исходящие звонки заблокированы (непроверенный VoIP) | Выполните [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization`  | Убедитесь, что `from_number` соответствует номеру телефона, которым вы владеете                                  |
| `502 Bad Gateway`                                         | Временная ошибка SIP / LiveKit; повторная попытка безопасна                                                      |

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

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

```json theme={null}
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

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

***

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

<CardGroup cols={2}>
  <Card title="Справочник по исходящим звонкам" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Все поля запроса и коды ошибок.
  </Card>

  <Card title="Получение call.complete" icon="bolt" href="/ru/webhooks/call-complete">
    Передавайте завершённые исходящие звонки в свою систему.
  </Card>

  <Card title="Биллинг" icon="credit-card" href="/api-reference/billing">
    Автопополнение, чтобы исходящие звонки не прерывались из-за баланса.
  </Card>

  <Card title="Тестирование исходящих агентов" icon="flask" href="/ru/guides/test-agents">
    Протестируйте исходящего агента в режиме пробного запуска перед продакшеном.
  </Card>
</CardGroup>