Звонки по сигналу

​

Как это работает

1. Внешняя система отправляет POST с номером телефона и данными лида (один из двух режимов приёма — ниже)
2. Агентика проверяет лимиты, дедупликацию, окно расписания и схему полей сигнала
3. Звонок проходит те же проверки, что и одиночный звонок через публичный API: слоты параллелизма, квота, контроль исходящих вызовов
4. Каждая попытка фиксируется в журнале сигналов (принята, отложена, начата или отклонена — с кодом и причиной); как прошёл разговор, смотрите в запуске воркфлоу. При «занято»/«без ответа» планируются перезвоны

​

Два режима приёма сигнала

​

API-режим

curl -X POST https://your-agentika-instance/api/v1/public/signals/8f14e45f-ea9b-4cd3-a3d2-1c9f7b6a5d43 \
  -H "X-API-Key: dg_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+79001234567",
    "external_id": "lead-12345",
    "context": { "customer_name": "Мария", "source": "website-form" }
  }'

​

Webhook-режим

curl -X POST https://your-agentika-instance/api/v1/public/signals/t/sig_your_signal_token \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+79001234567",
    "external_id": "lead-12345"
  }'

​

Контракт сигнала

{
  "parameters": [
    { "name": "customer_name", "type": "string", "required": true },
    { "name": "debt_amount", "type": "number", "required": false }
  ],
  "context_mapping": [
    { "name": "customer_name", "value_template": "{{customer_name}}" },
    { "name": "debt_summary", "value_template": "Долг: {{debt_amount}} руб." }
  ]
}

{
  "phone_number": "+79001234567",
  "external_id": "lead-12345",
  "context": { "source": "website-form" },
  "customer_name": "Мария",
  "debt_amount": 4200
}

{
  "status": "initiated",
  "workflow_run_id": 1287,
  "workflow_run_name": "WR-SIGNAL-7-42"
}

{
  "status": "scheduled",
  "scheduled_for": "2026-09-30T07:00:00Z",
  "workflow_run_id": null,
  "deduplicated": false
}

​

Дедупликация

{
  "status": "initiated",
  "workflow_run_id": 1287,
  "workflow_run_name": "WR-SIGNAL-7-42",
  "deduplicated": true
}

• Шлите external_id — ваши повторы безопасны в окне: повторные отправки на вашей стороне (таймауты, рестарты) не приведут к двойному звонку клиенту.
• После истечения окна тот же external_id означает новый звонок — «лид вернулся».
• Сигнал без external_id у триггеров с защитными настройками v2 (все новые триггеры; у старых — после «Применить безопасные настройки») дедуплицируется по номеру телефона (в нормализованном виде E.164) — в пределах окна, но не дольше 5 минут, даже если окно триггера длиннее: через 5 минут тот же номер снова получит звонок. Старые триггеры без этих настроек по номеру не дедуплицируют — как и раньше. Тестовые сигналы из карточки триггера в дедупликации по номеру не участвуют.
• Тот же external_id с другим номером — не дубликат: номер лида изменился, Агентика примет сигнал как новый (и отметит это в своих логах), а не выбросит его молча.
• Триггер без окна дедупликации не дедуплицирует ничего: каждый POST — отдельный звонок.

​

Окна звонков

• Отложить до открытия окна (по умолчанию у новых триггеров, out_of_window_policy: "defer") — сигнал принимается (202, "status": "scheduled", в scheduled_for — время открытия окна) и Агентика сама позвонит, когда окно откроется. Поля сигнала и номер проверяются сразу: невалидный сигнал получит 422, а номер вне белого списка направлений — 403 сейчас, а не упадёт ночью. Повтор сигнала в окне дедупликации ответит 200 с тем же scheduled_for.
• Отклонить ("reject", поведение триггеров, созданных до появления настройки) — ответ 423 Locked с заголовком Retry-After, который подсказывает, через сколько секунд окно откроется; повторять сигнал должен отправитель.

​

Перезвоны

​

Стоп-лист (DNC)

​

Отмена звонка

• webhook-режим: DELETE /api/v1/public/signals/t/{token}/requests?external_id=… (или idempotency_key=…, или source_ref=… — ровно один параметр);
• API-режим: DELETE /api/v1/public/signals/{signal_uuid}/requests/{request_id} с заголовком X-API-Key;
• из интерфейса — кнопка «Отменить» в журнале сигналов.

​

Коды ответов

​

Лимиты

​

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

• Токен webhook-режима — секрет: показывается один раз, в базе хранится только хеш, в логи и ответы не попадает. Компрометация — сразу «Сгенерировать новый токен»: старый инвалидируется мгновенно, восстановления нет.
• Секрет в URL — остаточный риск: URL может утекать в логи прокси на стороне отправителя. Передавайте сигнал только по HTTPS и не логируйте полный URL; опциональная HMAC-подпись запроса планируется в следующей версии API. На стороне Агентики токен в журналы доступа не пишется: API-логи не содержат путей запросов, nginx OSS-инсталляции маскирует токен (/api/v1/public/signals/t/***), а в Kubernetes для этого пути журнал доступа ingress отключён. Журнал ошибок ingress-nginx (таймауты и обрывы соединения с бэкендом) по-прежнему пишет строку запроса вместе с токеном — обращайтесь с ним как с журналом, содержащим секреты.
• Единый 404 для несуществующих, выключенных и чужих триггеров — перечислить чужие триггеры перебором нельзя; лимит запросов с одного IP дополнительно затрудняет подбор токена.
• Подмена атрибуции невозможна: организация выводится из секрета (ключа или токена), а не из тела запроса; серверные ключи контекста перетирают присланные.

​

Изменения поведения (signal calls v2)

• Пути шаблонов context_mapping: неразрешимый префикс пути ({{lead.contact.name}} без lead или lead.contact) теперь отклоняет сигнал 422; раньше переменная молча оставалась пустой. Проверьте шаблоны, если отправитель шлёт неполные объекты.
• Дедупликация по номеру (сигнал без external_id) работает только у триггеров с защитными настройками v2 и не дольше 5 минут; у старых триггеров поведение не изменилось.
• Поля v2 в теле сигнала (idempotency_key, source_ref/purpose, scheduled_at, local_time, timezone, call_at) действуют только у триггеров с защитными настройками v2; у старых триггеров это обычные пользовательские поля, как и раньше. Заголовок Idempotency-Key работает у всех триггеров.
• Ответ, после которого нужно повторить (423, 429, 5xx), освобождает ключ идемпотентности: повтор с тем же ключом будет новым сигналом, а не дубликатом отказа. Повтор, пока идёт автоматический перезвон, возвращает состояние последней попытки.
• Отложенные сигналы с номером вне белого списка направлений отклоняются сразу (403), а не принимаются как scheduled.
• Конец слота 24:00 снова принимается и означает «до полуночи».
• Права: создавать, менять (включая consent_basis, лимиты, service_call), удалять триггеры, перевыпускать токен, отправлять тестовый сигнал и отменять звонки может только владелец организации; участники видят триггеры и журнал. Все изменения настроек записываются в журнал аудита (секреты маскируются).
• Выключенный триггер больше не проваливает свои запланированные звонки сразу, а придерживает их до expire_after_seconds; удаление триггера мягкое — журнал и снимки согласий сохраняются.

​

Тестовый сигнал

​

Дальше

• Кампании — массовый обзвон по списку контактов
• API-ключи — ключи для API-режима
• Рецепты n8n и Make — «Google Таблица / CRM → звонок» без кода
• Запуск агента одиночным звонком — разовый вызов без триггера