Документация

Исходящие звонки

Документация

Исходящие звонки — это когда агент звонит людям сам, а не ждёт звонка. Два способа запуска покрывают почти все реальные потребности:

  • Через API — POST /v1/calls из вашего кода, по одному звонку за раз. Самый распространённый путь для продакшен-интеграций.
  • CSV-пакетом — загрузите список контактов через API, и платформа сама дозирует темп обзвона. Создан для кампаний и серий напоминаний.

Оба в итоге запускают один и тот же сценарий в одном и том же движке. Чтобы попробовать сценарий вживую, используйте Test call в браузере на странице Overview проекта — он проверяет того же агента, никому не звоня.

Запуск через API

POST /v1/calls
Authorization: Bearer <project-api-key>
Idempotency-Key: <your unique id>
Content-Type: application/json

{
  "scenarioId": "0d7e0f5a-…",
  "phone": "+34123456789",
  "parameters": {
    "customer_name": "Maria",
    "appointment_at": "2026-05-15T18:00:00Z"
  }
}

Поля:

  • scenarioId — идентификатор исходящего сценария в вашем проекте. Обязательное.
  • phone — номер назначения в формате E.164. Обязательное.
  • parameters — опциональный набор пар «ключ — значение», который сценарий может читать во время звонка. Передавайте через него контекст конкретного звонка (имя клиента, время записи, номер заказа).
  • callerIdNumber — опционально; какой из ваших подтверждённых номеров показывать как исходящий.
  • Idempotency-Key — рекомендуем: ваш уникальный идентификатор этого звонка. Повтор того же ключа в течение 24 часов возвращает исходный ответ без повторного набора — это важно при повторе неудавшегося API-запроса. Повторное использование ключа с другим телом возвращает 409.

Звонок ставится в очередь и набирается сразу; отложенный запуск на заданное время — в планах (пока планируйте на своей стороне). В ответе приходит идентификатор сессии — статус и результаты получайте через GET /v1/sessions/{id}.

API-ключи выпускаются во вкладке API keys проекта. Ключи ограничены по правам — давайте ключу только те права, которые ему нужны (outbound:trigger, sessions:read). Для ротации выпустите новый ключ и отзовите старый.

Запуск CSV-пакетом

POST /v1/calls/bulk
Authorization: Bearer <project-api-key>
Content-Type: multipart/form-data

scenarioId=<uuid>
callerIdNumber=+1…        (optional)
csv=@contacts.csv

В CSV нужна как минимум колонка phone; каждая остальная колонка становится параметром строки, доступным сценарию.

phone,customer_name,appointment_at
+34123456789,Maria,2026-05-15T18:00:00Z
+34987654321,Carlos,2026-05-15T19:00:00Z

До 100 000 строк / 10 МБ на пакет. Платформа дозирует темп обзвона (по умолчанию 5 звонков в минуту — поднимается для проекта по запросу), чтобы вы не перегрузили собственный транк или оператора на стороне назначения.

Отслеживайте прогресс через API:

  • GET /v1/calls/batches — список ваших пакетов
  • GET /v1/calls/batches/{id} — живые счётчики: в очереди / идёт / завершено / не удалось / брошено
  • POST /v1/calls/batches/{id}/cancel — остановить оставшиеся строки

Исходы и причины неудач

Каждый состоявшийся исходящий звонок получает исход (success / реальный разговор / spam) точно так же, как входящий. Звонки, которые так и не стали разговором, вместо этого несут типизированную причину неудачи:

  • no_answer — гудки прошли, никто не взял трубку.
  • busy — линия была занята.
  • voicemail_detected — обнаружен автоответчик; по умолчанию агент кладёт трубку, а не разговаривает с машиной (оставлять голосовые сообщения — в планах).
  • invalid_number — номер назначения не обслуживается.
  • caller_id_unauthorized — оператор на стороне назначения отклонил наш идентификатор звонящего.
  • provider_error — ошибка телефонного провайдера (редко).
  • internal_error — ошибка платформы (редко; расследуется).

Всё это видно в записях сессий, счётчиках пакетов и ваших событиях вебхуков.

Соответствие требованиям — ваша ответственность

Исходящие звонки регулируются законом. Конкретные правила зависят от страны назначения, времени суток и того, на что согласился абонент. Платформа даёт вам записи и полные журналы сессий для аудита; соблюдение TCPA (США), GDPR (ЕС) или местных норм — ваша ответственность.

Практические рекомендации:

  • Получайте согласие до звонка — и храните подтверждение. Не звоните тем, кто не просил, чтобы им звонили.
  • Сверяйте со своим списком запрета звонков до запуска — платформа сегодня не ведёт DNC-список за вас, поэтому фильтруйте списки контактов до того, как они попадут в POST /v1/calls.
  • Раскрывайте использование AI там, где это требуется — добавьте раскрытие в приветствие сценария. С каждым годом его требует всё больше юрисдикций.
  • Соблюдайте правила по времени суток — запускайте звонки в подходящие местные часы; платформа не контролирует «тихие часы» по странам.
  • Следите за долей дозвонов — если вы запускаете много звонков, которые срываются или сразу вешают трубку, репутация вашего номера у операторов деградирует. Сбавьте темп.

Ограничения частоты запросов

  • 100 изменяющих запросов в минуту на API-ключ (включая POST /v1/calls)
  • 5 наборов в минуту — темп пакетного обзвона на проект (поднимается по запросу)
  • Более высокие лимиты доступны — напишите на sales@aitelier.org.