Trigger Call API

Endpoint

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

Заголовки

Тело запроса

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

{
  "phone": "+79991234567"
}

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

{
  "phone": "+79991234567",
  "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","payload":{"name":"Иван","stage":"Согласование цены","product":"CRM Pro","deal_amount":240000},"external_ref":"LEAD_42","external_system":"bitrix"}'

Ответы

Настройка робота 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:

{
  "phone": "{{=Document:PHONE}}",
  "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 при обратном апдейте.

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

• С external_ref: повторные запросы с тем же (организация, external_ref) пока запись активна (pending/in_progress) возвращают 409. Это безопасно для ретраев Bitrix.
• Без external_ref: дедупликация по телефону — пока есть активная запись с тем же номером, новый запрос отклоняется.
• После завершения звонка (completed/failed/no_answer) тот же external_ref снова можно использовать — это нормальный сценарий повторного обзвона.

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

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

• Текущее время попадает в рабочие часы организации (настраиваются в личном кабинете).
• Свободен слот для исходящих (по умолчанию до 3 одновременных звонков).
• Номер не в DNC-листе организации.
• Если попадание в рабочее окно невозможно — звонок ждёт следующего окна.

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

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

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

• pending — ожидает в очереди.
• ringing — идёт дозвон, абонент ещё не ответил.
• talking — абонент ответил, идёт разговор с агентом.
• completed — разговор завершён нормально.
• no_answer — абонент не ответил, сбросил, попали на голосовую почту, или агент не услышал ответа.
• busy — занято.
• failed — ошибка телефонии (нет маршрута, неверный номер, провайдер недоступен).
• skipped — номер был в DNC-листе или пропущен оператором.

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

• booked, interested, callback — успех в разной степени.
• not_interested — клиент отказался.
• voicemail — определён автоответчик (AMD).
• silent — звонок состоялся, но клиент молчал (или это была голосовая почта без AMD).
• hung_up — клиент сбросил до начала разговора.
• error — техническая ошибка.

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

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

На странице /call-list администратор может настроить параметры обзвона для своей организации:

• Макс. попыток (1–10) — сколько раз звонить одному номеру до перевода в failed.
• Время ожидания ответа (10–180 сек) — сколько ждать ответа на звонок.
• Пауза перед повтором (1–1440 мин) — через сколько после no_answer можно перезвонить.
• Пауза между звонками (0–600 сек) — задержка после каждого звонка перед началом следующего.
• Макс. длительность разговора (30–1800 сек) — после этого звонок принудительно завершается.
• Макс. одновременных звонков (1–10) — лимит на одну организацию.
• Определять автоответчик — включает AMD-проверку, чтобы не тратить минуты на голосовую почту.

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

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

• Ключ показывается один раз при создании. Восстановить нельзя — только выпустить новый и отозвать старый.
• Ключи хранятся в виде SHA-256 хешей; даже утечка БД их не раскрывает.
• На организацию можно завести несколько активных ключей (отдельный для prod / dev / каждой CRM).
• Rate-limit: 60/мин и 1000/сутки на каждый ключ. Превышение → 429 с Retry-After.