Перейти к основному содержанию

Контракт для разработчика

Раздел для того, кто поднимает HTTP-обработчик на стороне клиента.

Запрос от платформы

Адрес, заголовки, параметры и тело собираются из полей формы с подстановкой {{переменная}}. Доступны переменные звонка (from_number, to_number, direction и всё, что настроено в агенте и кампании), результаты функций из предыдущих строк блока и — только в блоке после звонка — call и analysis. Метод задаётся в функции; по умолчанию GET, без тела — параметры уходят в строку запроса. У остальных методов тело отправляется как JSON (по умолчанию), как форма (form) или как есть (raw) с указанным Content-Type. Секреты в поля не вписываются: только ссылкой {{env.ИМЯ}}. Значение подставляется при выполнении из секретов флоу вашей организации; если такого секрета нет, подставляется пустая строка. Ссылка работает в адресе, параметрах строки запроса, заголовках и теле. В истории звонка запрос сохраняется маскированным. Платформа не подписывает запросы и не добавляет заголовков авторизации. Ключ доступа к вашему API передайте сами — в заголовке или параметре через {{env.ИМЯ}}, например Authorization: Bearer {{env.CRM_TOKEN}}. Адрес — только http или https. Запросы на локальные адреса и на адреса внутренней сети — 10.x.x.x, 172.16.x.x–172.31.x.x, 192.168.x.x, 100.64.x.x–100.127.x.x и имена на .local или .internal — платформа отклоняет: запрос не уходит, а <имя>_error равно blocked. Если сервис функции работает во внутренней сети, обратитесь в поддержку: его адрес разрешат для вашей организации. Редиректы выполняются, каждый новый адрес проверяется заново. Сертификат TLS по умолчанию проверяется.

Таймаут, повторы и бюджет

Таймаут запроса — поле функции, по умолчанию 10 с, потолок 30 с. Он действует на одну попытку: с повторами общее время дольше. Повторы по умолчанию выключены. Повторяются только ответы 5xx, сетевые ошибки и таймауты; 4xx не повторяется. Пауза перед каждым следующим повтором удваивается от заданной (по умолчанию 0,5 с: 0,5 → 1 → 2 с). Обработчик должен спокойно переносить повторный запрос с теми же данными. Как таймаут соотносится с бюджетом блока:

Ответ и маппинг

Ответ успешен, если его код входит в «Успешные статусы ответа» функции (по умолчанию 2xx). Ответ не в JSON сохраняется как текст. Из ответа платформа пишет в переменные сценария служебный набор и то, что перечислено в маппинге. <имя> — техническое имя HTTP-функции (поле «Имя»). Маппинг — это словарь «имя переменной → JSONPath в ответе»; имя переменной здесь ключ, а не значение. В форме он и выглядит так: слева имя, справа путь (balance ← $.data.balance). При совпадении имён переменная из маппинга побеждает служебную. Имена задаёт настройщик агента в кабинете, вы их не выбираете — договоритесь заранее, какие поля отдаёте. JSONPath поддерживается в упрощённом виде: $, .ключ, [n], ['ключ']. Фильтров и * нет. Если по пути ничего нет, переменная не записывается.

Решение о звонке

Чтобы остановить набор из кампании, верните поля, которые в маппинге положены в call_decision, call_decision_reason и call_retry_after (значения и последствия — в разделе Решение о звонке в кампании). Как платформа читает эти поля:
  • call_decision — proceed, cancel или retry, без учёта регистра. Другое значение — звонок идёт, в событии предупреждение.
  • call_decision_reason — обрезается до 200 символов.
  • call_retry_after — секунды или момент в ISO-8601; без часового пояса считается UTC. Повтор назначается не ближе чем через 60 с.
  • Решение применяется только при наборе из кампании.
Минимальный обработчик, отменяющий звонок:
В маппинге ответа функции: call_decision ← $.decision, call_decision_reason ← $.reason. Дальше — кампания с одним контактом: телефон не зазвонит, контакт закроется, в разбивке исходов появится «Отменены функцией».

Пробный вызов

Кнопки «Проверить» и «Проверить блок» бьют в эндпоинт кабинета POST /api/flows/{name}/call-functions/run. Тело: {function, phase: "pre"|"post", variables?, mock?, budget?} либо {functions: [...]} для прогона всего блока. Поле budget выбирает бюджет: inbound — до первой реплики, 10 с по умолчанию, или outbound — до набора номера, 60 с по умолчанию; для phase="post" оно игнорируется. В пробном вызове бюджет урезает таймаут в обоих вариантах, фоновой доработки нет. Для phase="post" тело принимает analysis — заглушку результата аналитики. Ответ для одной функции: Ответ для блока: outcomes (по записи на функцию, поля как выше), batches (раскладка по строкам), elapsed_ms, variables_after. Для phase="pre" в обоих случаях добавляется decision — как прочиталось ваше решение: {action, reason, retry_after, retry_at, warning, declared}.

Ключи конфигурации платформы

Эти ключи задаёт администратор платформы; из кабинета организации они не меняются.