Варианты для форм

Выпадающий список в форме Запросить данные может брать варианты из вашего API: тарифы, промокоды, шаблоны. Polygram запрашивает список, когда сотрудник открывает форму.

Настройка в workflow

Автор workflow включает у поля Выбор из списка переключатель Варианты из подключения и заполняет:

Запрос

GET https://crm.example.com/api/v1/tariffs
Authorization: Bearer <ключ подключения>
X-Snippex-User-Id: 3f2c…
Idempotency-Key: form-options:<id формы>:tariff
Accept: application/json, text/plain, */*

• Метод всегда GET, без тела.
• Polygram отправляет постоянные заголовки подключения, заголовки поля, авторизацию, Idempotency-Key вида form-options:<id формы>:<ключ поля> и Accept.
• В адресе и заголовках доступны данные сотрудника, который открыл форму ($me.id, $me.name, $me.email), и данные клиента и диалога: $contact.id, $contact.custom.<поле>, $conversation.id. Переменные запуска ($vars) здесь недоступны.
• Polygram запрашивает список целиком. Фильтр передайте в адресе: /tariffs?active=1.
• Polygram ждёт ответа 10 секунд и сам запрос не повторяет. Приложение сотрудника при ошибке запрашивает список ещё раз, так что запросов может быть два.

Ограничения на адрес те же, что у шага Внешний вызов: только внутри базового адреса, без внутренних адресов и редиректов, см. Запросы Polygram к вашему API.

Ответ

Ответ должен быть JSON-массивом объектов или объектом, в котором массив лежит по itemsPath. Из каждого элемента Polygram берёт подпись по labelPath и значение по valuePath. Пути пишутся через точку, как в ответах.

{
  "items": [
    { "id": 3, "name": "Премиум", "price": 4900 },
    { "id": 5, "name": "Базовый", "price": 1900 },
    { "id": 7, "name": "" }
  ]
}

При itemsPath: items, labelPath: name, valuePath: id сотрудник увидит варианты Премиум, Базовый и 7. Если он выберет Премиум, в $vars.<ключ поля> попадёт "3".

Как разбирается ответ:

• значение и подпись приводятся к строке: из 3 получится "3", объект и массив дают пустую строку;
• элемент без значения пропускается;
• если подписи нет, показывается значение;
• из элементов с одинаковым значением остаётся первый;
• берутся первые 1000 вариантов;
• если по itemsPath лежит не массив, список будет пустым, и ошибкой это не считается.

Значение по умолчанию задаёт автор workflow в поле Значение по умолчанию.

Кеширование

Сервер Polygram хранит полученный список 60 секунд. Ключ кеша составляется из подключения и настроек поля (адрес, пути, заголовки) до подстановки переменных. Поэтому в течение минуты другой сотрудник или другой клиент с той же формой получит тот же список, даже если в адресе или заголовках есть $me.id или $contact.id. Ответы с ошибкой не кешируются.

Ошибки

Ошибкой считается код не 2xx, отсутствие ответа за 10 секунд, ответ больше 1 МБ и запрещённый адрес. Тогда поле в форме становится текстовым, сотрудник вводит значение вручную, и оно уходит в workflow без проверки по списку.

Значение из выпадающего списка при отправке формы тоже не сверяется со списком. Проверяйте его в вашем API, когда workflow его пришлёт.

Форма без запроса

Polygram не запрашивает список, если форма не показывается. Так бывает, когда у формы включено Не показывать, если всё уже известно и все обязательные поля уже заполнены значениями по умолчанию.

Варианты из списка клиента

Варианты можно брать и из поля-списка клиента, для этого есть источник Варианты из списка контакта. Например, из поля crm_accounts: значение из колонки id, подпись из username. Ваш API при этом не вызывается. Если у клиента одна запись, она выбирается сама. Если записей нет, а поле обязательное, workflow останавливается с ошибкой У контакта нет записей для «…» — сначала привяжите аккаунт.