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

Функции до звонка

Функции до звонка выполняются перед разговором — у исходящих до набора номера, у входящих после соединения, но до первой реплики агента. Их результат ложится в переменные звонка, и агент знает их с первого слова. Когда именно запускается блок и какой у него бюджет — на странице Функции до и после звонка.

Добавить функцию до звонка

В блоке «Функции до звонка» нажмите «+ Добавить» и выберите вид:
  • Своя функция — HTTP-запрос по адресу вашей системы;
  • Код — короткий скрипт на Python в песочнице.
Карточка появится в блоке, справа откроется её форма. Новая функция сразу получает название по виду и номеру — «Функция 1», «Код 1», — его можно поменять.

Общие поля

В заголовке панели — вид функции («Своя функция» или «Код») и пометка «До звонка». Ниже:
  • Название — подпись карточки в блоке. На переменные оно не влияет.
  • Описание — текст для вас и коллег.
  • Когда выполнять — «После предыдущей» или «Параллельно с предыдущей» (см. Порядок и параллельность). У первой функции блока этого поля нет.
Сразу под ними — две подсказки. Первая про общий бюджет блока: 10 с до первой реплики у входящих и web-звонков и 60 с до набора номера у исходящих; что не уложилось, пропускается, а у входящих дорабатывает в фоне. Вторая — про переменные решения call_decision, call_decision_reason и call_retry_after (см. Решение о звонке).

Своя функция (HTTP)

Новая своя функция создаётся в режиме «HTTP (реальный вызов)» с методом POST и пустым URL, а её «Имя» совпадает с идентификатором карточки (cf1). Замените имя понятным префиксом, например crm. Пока адреса нет, переключите режим на «Заглушка (постоянный ответ)».
  • Имя — префикс переменных результата. Функция с именем crm запишет crm_status, crm_success, crm_error, crm_result. Не путайте с полем «Название».
  • Режим выполнения — «Заглушка (постоянный ответ)» или «HTTP (реальный вызов)». Пока собираете сценарий, держите заглушку: наружу ничего не уходит.
  • Метод и URL — метод выбирается из списка: GET, POST, PUT, PATCH, DELETE. В URL, «Параметрах строки запроса», «Заголовках» и теле работает подстановка {{переменная}}.
  • Секреты — ключи в поля не вписывайте: в URL, заголовках, параметрах и теле пишите ссылку {{env.ИМЯ}} на секрет организации, значение подставится при выполнении. В истории звонка запрос сохраняется с замаскированным значением.
  • Тело запроса — есть у всех методов, кроме GET. Тип: json, form или raw. «Content-Type (переопределение)» задаёт заголовок вручную; пустое поле — Content-Type по типу тела.
  • Переменные из ответа (переменная ← JSONPath) — слева имя переменной, которое увидит сценарий, справа путь в JSON-ответе, например $.data.balance. Из ответа в переменные попадает только то, что перечислено здесь.
  • Таймаут, сек — по умолчанию 10, максимум 30. Таймаут действует на каждую попытку.
  • Повторы — по умолчанию 0, то есть повторов нет. Повтор срабатывает на сетевой ошибке, таймауте и ответе 5xx; на 4xx — нет.
  • Пауза между повторами, сек — по умолчанию 0,5 и удваивается с каждым повтором: 0,5 → 1 → 2 с. С повторами и паузами вызов длится дольше и расходует бюджет блока.
  • Проверять TLS-сертификат (tls_verify) — включено по умолчанию.
  • Успешные статусы ответа — по умолчанию 2xx; можно перечислить свои коды и диапазоны, например 200-299, 404. Если ответ объявлен как JSON, но не разбирается, функция завершается ошибкой invalid_json.
Ответ-заглушка и сценарии. Раздел внизу формы задаёт, что функция возвращает в режиме заглушки и при «Проверить с заглушкой»:
  • «HTTP-код заглушки» и «Ответ-заглушка» — JSON с подстановкой {{переменная}};
  • «Сценарии-заглушки» — именованные варианты, добавляются кнопкой «+ Сценарий»: «успех (ответ)» со своим кодом и JSON-ответом, timeout или network — имитация сбоя;
  • «Активный сценарий по умолчанию» — какой сценарий отвечает; «— базовый ответ-заглушка —» берёт код и ответ из полей выше.
Панель своей функции: «Название» вверху и «Имя» — префикс переменных — в блоке «Функция»

Код

  • Код (Python-песочница: vars, metadata, http, now) — vars (словарь переменных звонка), metadata (метаданные звонка), http(...) (запрос с той же политикой адресов, что у своей функции) и now("Asia/Almaty"). Импортов, файлов и print в песочнице нет. Ссылки {{env.ИМЯ}} в http(...) не раскрываются — запросы с секретами делайте своей функцией.
  • Переменные результата (через запятую) — имена, которые ваш код положил в result. Все ключи словаря result становятся переменными звонка, даже если их нет в списке. Имя из списка, которое код не заполнил, сохраняет прежнее значение, а если такой переменной не было — она не появится. Имена vars, result, now, metadata и http заняты самой песочницей: переменная с таким именем в звонок не попадёт, и редактор про это предупредит.
  • Таймаут выполнения, сек — по умолчанию 10, максимум 30.
Панель функции-кода: песочница, переменные результата и таймаут

Переменные, которые появляются после функции

Своя функция всегда пишет служебный набор, даже если маппинг ответа пуст: Плюс всё, что вы перечислили в «Переменных из ответа». При совпадении имён ваша переменная из маппинга побеждает служебную. Функция-код пишет <идентификатор>_success, а <идентификатор>_error — только при сбое. Префикс у неё не «Имя», а идентификатор карточки (cf1, cf2). Плюс ключи result и перечисленные переменные результата. Переменные http_* функция-код не пишет.

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

Функция до звонка может вернуть решение о наборе — для этого её ответ кладут в переменные call_decision, call_decision_reason и call_retry_after. На карточке такой функции появляется значок ⤳ с подсказкой «Эта функция решает, что делать со звонком». Блок до звонка выполняется у всех исходящих — из кабинета, через API и в кампании, — но решение действует только при наборе из кампании. Подробнее — Решение о звонке в кампании.

Порядок и параллельность

Карточки идут сверху вниз в том порядке, в каком их выполняет система. Одна строка — один шаг. Чтобы две функции пошли одновременно, перетащите карточку одной на строку другой; при перетаскивании подсказка покажет «Пойдёт вместе с этой строкой». Строка из двух и более карточек обведена пунктиром и подписана «параллельно · N». Чтобы вернуть очередь — перетащите карточку в зазор между строками («Станет отдельной строкой»). Без мыши то же самое делают:
  • поле «Когда выполнять» в форме функции — «После предыдущей» или «Параллельно с предыдущей»;
  • клавиши на выделенной карточке: Alt+↑ и Alt+↓ переносят карточку отдельной строкой выше или ниже, Alt+→ ставит её в строку выше, Alt+← выводит из общей строки в отдельную.
Что важно знать про строки:
  • Видимость переменных — по строкам, а не по стрелкам. Функция строки k видит переменные всех предыдущих строк целиком, а не только тех, за кем её поставили. Результаты одной строки вливаются в общий набор после того, как строка закончилась полностью, в порядке карточек слева направо — поэтому http_* остаются от последней своей функции строки.
  • Две функции одной строки не могут писать одно и то же. Одинаковый префикс («Имя») или пересекающиеся имена переменных результата внутри одной строки — ошибка: результат зависел бы от того, кто успел первым. В соседних строках это допустимо, там побеждает более поздняя.
  • Сбой не отменяет следующие. Если функция упала или не уложилась в таймаут, зависящая от неё всё равно стартует и увидит <имя>_success = "false".
  • Между блоками «до» и «после» карточка не переносится: у функции нет смены фазы.
Под блоком есть строка «Самая длинная цепочка: N с из 10 с». Это и есть проверка, влезаете ли вы в бюджет: считается не сумма всех таймаутов, а самая длинная цепочка последовательных строк. Три запроса по 4 секунды в одной строке — это 4 секунды, а не 12. Если цепочка длиннее 10 с, появится предупреждение с идентификаторами функций этой цепочки, например cf1 → cf3. Блок функций до звонка: строка-пакет «параллельно · 2» и строка самой длинной цепочки

Проверить, не звоня никому

Одну функцию. Выберите карточку. Внизу панели у своей функции две кнопки: «Проверить» — реальный вызов по вашему адресу — и «Проверить с заглушкой» — тот же прогон, но с принудительным режимом заглушки, наружу ничего не уходит. У функции-кода кнопка одна: «Выполнить код». У функций до звонка рядом стоит «Бюджет пробного вызова» с двумя значениями — «До первой реплики (входящие, web)» и «До набора номера (исходящие)»: так видно, что медленный запрос не проходит по первому бюджету и проходит по второму. Результат показывается под кнопками и на карточке: «Успех», «Ошибка», «Таймаут» или «Пропущена (бюджет исчерпан)», время в миллисекундах, код ответа и список записанных переменных. Если функция до звонка вернула решение о звонке, тут же будет строка «Решение: набирать», «Решение: отменить набор» или «Решение: отложить контакт». Предупреждения: «Значение решения не распознано — набор идёт» и «Время повтора не прочитано — сработает политика ретраев кампании». Весь блок. Когда функций в блоке больше одной, появляется кнопка «Проверить блок». Она прогоняет строки так же, как в звонке, но без поздней доставки: что не уложилось в выбранный бюджет, получает «Таймаут» или «Пропущена (бюджет исчерпан)». Функции в режиме HTTP вызывают ваши реальные адреса. В ответе — «Блок целиком — N ms» и разбивка по строкам: «Строка 1:», «Строка 2:» и статус каждой функции. Это самый быстрый способ убедиться, что параллельность настроена так, как вы задумали. Результат пробного вызова живёт до перезагрузки страницы и в сценарий не сохраняется. Пробный вызов: выбор бюджета, кнопки и карточка результата Прогон всего блока с разбивкой по строкам

Поздняя доставка результата

У входящих и web-звонков функция, не уложившаяся в бюджет до первой реплики, не обрывается. Агент начинает говорить по бюджету, а функция дорабатывает в фоне со своим собственным таймаутом, и результат вливается в идущий разговор — его увидит следующий узел сценария, читающий переменные. Пока результата нет, узлы видят <имя>_success = "false" и <имя>_error = "late". В истории на такую функцию два события: сначала «ждём результат», потом окончательный статус. Уже произнесённая реплика не переигрывается: если агент поздоровался без имени, задним числом он его не подставит. Границы:
  • у исходящих поздней доставки нет — им хватает 60 секунд до набора;
  • в realtime-режиме поздние данные попадают в переменные и в инструменты, но не в уже собранный системный промпт;
  • чат-тест в редакторе остаётся синхронным.