← На главнуюEnglish

Trigger Call API

Программный запуск исходящего AI-звонка из любой CRM или внешней системы. Звонок ставится в очередь и инициируется в рабочие часы организации.

Endpoint

POST https://your-host/api/public/trigger-call

Заголовки

ЗаголовокЗначение
AuthorizationBearer YOUR_API_KEY — ключ, выпущенный в личном кабинете
Content-Typeapplication/json

Тело запроса

ПолеТипОписание
phonestring, requiredНомер в любом формате: +79991234567, 89991234567, 8 (999) 123-45-67. Нормализуется к E.164.
campaignstring, ≤64Кампания обзвона, в которую ставится звонок — по её ключу trigger_key (не по числовому id). Кампания определяет, какой агент позвонит и по какому сценарию. Поле можно не передавать, только если ключ уже привязан к кампании в личном кабинете; иначе запрос отклоняется с 422.
payloadobject, optionalПроизвольный JSON-объект с контекстом. Попадает в промпт голосового агента в блоке <client_context>. Лимит 5 KB; строки длиннее 200 символов обрезаются.
external_refstring, optional, ≤128Идентификатор сущности в вашей CRM (например LEAD_42). Используется для дедупликации и для обновления именно этого лида после звонка.
external_systemstring, optional, ≤32Имя CRM (bitrix, amocrm, custom). Влияет на способ обратного апдейта лида.

Минимальный запрос

{
  "phone": "+79991234567",
  "campaign": "reactivation"
}

Полный запрос

{
  "phone": "+79991234567",
  "campaign": "reactivation",
  "payload": {
    "name": "Иван",
    "stage": "Согласование цены",
    "product": "CRM Pro",
    "deal_amount": 240000
  },
  "external_ref": "LEAD_42",
  "external_system": "bitrix"
}

curl

curl -X POST 'https://your-host/api/public/trigger-call' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+79991234567","campaign":"reactivation","payload":{"name":"Иван","stage":"Согласование цены","product":"CRM Pro","deal_amount":240000},"external_ref":"LEAD_42","external_system":"bitrix"}'

Ответы

КодКогда
202Звонок поставлен в очередь. Тело: {"queued":true,"call_list_entry_id":N}
400Невалидный номер, превышен размер payload (>5 KB), битый JSON.
401Ключ отсутствует, отозван, или формат не соответствует sk_live_….
403У ключа нет scope trigger_call, либо ключ привязан к одной кампании, а в campaign указана другая: привязка ключа жёсткая и телом запроса не переопределяется.
404Кампании с таким campaign нет в вашей организации (либо она архивирована). Ответ одинаков для несуществующего и чужого ключа кампании.
409Дубль внутри той же кампании. Если передан external_ref — уже есть активная запись с тем же ref. Если нет — есть активная запись на тот же телефон.
422Звонок некуда поставить: campaign не передан и ключ не привязан к кампании. Запасной кампании «по умолчанию» нет — иначе клиенту позвонил бы не тот агент.
429Превышен rate-limit: 60 запросов в минуту или 1000 в сутки на ключ. Заголовок Retry-After указывает, сколько ждать.

Настройка робота Bitrix24

В Bitrix24 «исходящий вебхук» из робота воронки шлёт POST с шаблоном тела на наш URL. Это самый простой путь — никаких приложений ставить не нужно.

  1. В Bitrix24 откройте CRM → Воронки → Роботы на нужной стадии.
  2. Добавьте робота «Уведомление по HTTP» или аналогичный «webhook».
  3. Метод: POST. URL: https://your-host/api/public/trigger-call
  4. В заголовках:
    • Authorization: Bearer YOUR_API_KEY
    • Content-Type: application/json
  5. В теле — JSON с подстановками плейсхолдеров Bitrix. Значение campaign возьмите из вкладки «Интеграция» нужной кампании — это её trigger_key, а не числовой id:
{
  "phone": "{{=Document:PHONE}}",
  "campaign": "reactivation",
  "payload": {
    "name": "{{=Document:NAME}}",
    "stage": "{{=Document:STAGE_ID}}",
    "title": "{{=Document:TITLE}}"
  },
  "external_ref": "LEAD_{{=Document:ID}}",
  "external_system": "bitrix"
}

После настройки: при переходе лида на эту стадию робот вызывает наш endpoint, мы ставим звонок в очередь. AI-агент получит контекст из payload в системном промпте, а после успешного звонка результат вернётся обратно в тот же лид (а не создаст дубль) — благодаря external_ref.

amoCRM, Kommo и другие CRM

Endpoint провайдеро-нейтральный. Настройте webhook на стадии воронки или триггер автоматизации с теми же заголовками и телом. Поле external_system подскажет нашему бэкенду, как обращаться к API вашей CRM при обратном апдейте.

Дедупликация и идемпотентность

Дедупликация действует в пределах одной кампании. Один и тот же номер может одновременно находиться в кампании реактивации и в кампании обратного звонка — это разные разговоры разных агентов.

Когда звонок реально уходит

Звонок ставится в очередь моментально. Реально набирается, когда:

Статусы и результаты звонка

После завершения звонка номер в списке обзвона получает оперативный статус и бизнес-результат. Они означают разное и не должны путаться.

Статус (что произошло на уровне телефонии)

Outcome (бизнес-результат)

Важно: голосовая почта и тишина больше не отмечаются как «Завершён». Если AMD определил автоответчик, статус будет no_answer, outcome — voicemail. Это значит, что в карточку лида можно перезвонить, а не считать, что встреча была.

Настройки обзвона

Параметры задаются отдельно для каждой кампании на вкладке «Настройки» страницы /campaigns/{id}. Поэтому реактивация может звонить редко и мягко, а обработка заявок на обратный звонок — часто и настойчиво, хотя это один и тот же аккаунт:

Изменения применяются на ходу — рабочий цикл подхватит новые значения в течение минуты, без рестарта.

Безопасность