Выгружает все workflow компании, показывает схему одного, создаёт и меняет workflow. Запустить workflow извне — в статье Запустить workflow.
| Метод | Что делает |
|---|---|
GET /public/workflows |
Список всех workflow |
GET /public/workflows/{id} |
Один workflow со схемой |
POST /public/workflows |
Создать workflow |
PATCH /public/workflows/{id} |
Изменить черновик и настройки, включить или выключить |
POST /public/workflows/{id}/publish |
Опубликовать черновик |
POST /public/workflows/{id}/unpublish |
Снять с публикации |
У workflow, как и в редакторе, две версии схемы:
- черновик (
draft_graph) — его меняютPOSTиPATCH; - опубликованная (
published_graph) — по ней workflow работает.
Изменения черновика начинают работать только после публикации.
Список
GET /public/workflows
Ответ 200:
{
"items": [
{
"id": "cmf7z8y9x0000ab12cd34ef56",
"name": "Создать аккаунт",
"description": null,
"enabled": true,
"published": true,
"published_at": "2026-10-20T09:15:00.000Z",
"trigger_type": "BUTTON",
"once_per_contact": false,
"cancel_on_operator_reply": true,
"role_ids": [],
"runs": { "total": 42, "active": 0, "failed": 1 },
"created_at": "2026-10-01T10:00:00.000Z",
"updated_at": "2026-10-20T09:15:00.000Z"
}
]
}
| Поле | Описание |
|---|---|
enabled |
Workflow включён |
published |
Есть опубликованная версия |
trigger_type |
Запуск опубликованной версии, см. Типы запуска. null, пока workflow не публиковали |
once_per_contact |
Включено Один раз на контакт |
cancel_on_operator_reply |
Включено Останавливать, когда отвечает оператор |
role_ids |
Роли из блока Для кого. Пусто — для всех |
runs |
Запуски: всего, идут сейчас, с ошибкой |
Схемы в списке нет — её отдаёт запрос одного workflow.
Один workflow
GET /public/workflows/{id}
Ответ 200: поля из списка и ещё:
| Поле | Описание |
|---|---|
draft_graph |
Черновик схемы |
published_graph |
Опубликованная схема, null без публикации |
has_unpublished_changes |
Черновик отличается от опубликованной схемы |
draft_errors |
Ошибки черновика, с которыми его не опубликовать. Пусто — можно публиковать |
Проще всего собрать workflow в редакторе, выгрузить этим запросом и взять draft_graph за образец.
Создать
POST /public/workflows
| Поле | Тип | Обязательное | Описание |
|---|---|---|---|
name |
строка | да | Название, до 200 символов |
description |
строка или null |
нет | Описание, до 1000 символов |
draft_graph |
объект | нет | Схема, см. Схема. Без неё workflow создаётся пустым |
once_per_contact |
да/нет | нет | Один раз на контакт. По умолчанию нет |
cancel_on_operator_reply |
да/нет | нет | Останавливать, когда отвечает оператор. По умолчанию да |
role_ids |
массив строк | нет | Роли блока Для кого, до 50 |
publish |
да/нет | нет | Сразу опубликовать и включить |
С "publish": true схема проверяется так же, как кнопкой Опубликовать в редакторе. Если в ней ошибки, workflow не создаётся и приходит 400 со списком ошибок.
Без publish workflow создаётся выключенным черновиком.
Ответ 201: workflow в том же виде, что в запросе одного workflow.
Изменить
PATCH /public/workflows/{id}
Принимает те же поля, что создание, кроме publish, и ещё enabled. Передавайте только то, что меняете.
| Поле | Описание |
|---|---|
draft_graph |
Заменяет черновик целиком. Опубликованная версия не меняется до публикации |
enabled |
Включить или выключить. Включить можно только опубликованный workflow, иначе 400 |
Название, описание, роли и переключатели меняются сразу, без публикации, как и в редакторе.
Ответ 200: workflow в том же виде, что в запросе одного workflow.
Опубликовать и снять с публикации
POST /public/workflows/{id}/publish
POST /public/workflows/{id}/unpublish
Публикация делает черновик рабочей версией и включает workflow. Если в черновике ошибки, приходит 400:
{
"statusCode": 400,
"message": "Draft graph is not valid",
"errors": [{ "nodeId": "n2", "message": "Не соединён с запуском — протяните к нему связь" }]
}
Снятие с публикации убирает рабочую версию: workflow перестаёт запускаться, черновик остаётся.
Оба запроса отвечают 200 с workflow в том же виде, что в запросе одного workflow.
Схема
{
"nodes": [
{
"id": "start",
"type": "TRIGGER",
"position": { "x": 0, "y": 0 },
"data": { "triggerType": "TAG_ADDED", "tagId": "cmtag0000000000000000000" }
},
{
"id": "hello",
"type": "SEND_MESSAGE",
"position": { "x": 0, "y": 200 },
"data": { "body": "Здравствуйте, $contact.name!" }
}
],
"edges": [{ "id": "e1", "source": "start", "target": "hello" }]
}
nodes— шаги.id— любая строка, уникальная внутри схемы.position— место на холсте редактора.edges— связи: из шагаsourceв шагtarget. У шагов с несколькими выходами выход указывается вsourceHandle.
Правила, без которых схему не опубликовать:
- шаг запуска
TRIGGERровно один; - все шаги достижимы от него;
- нет циклов;
- не больше 100 шагов;
- у Условия есть ветка
else; - у каждого шага заполнены обязательные поля.
ID тегов, ролей, шаблонов и сотрудников берите из своей компании. Переменные в текстах, например $contact.name, — те же, что в редакторе.
Типы запуска
Поле data.triggerType шага TRIGGER:
| Значение | Когда срабатывает | Поля data |
|---|---|---|
CONVERSATION_OPENED |
Открыт новый диалог | — |
TAG_ADDED |
Поставили тег | tagId |
TAG_REMOVED |
Сняли тег | tagId |
NO_REPLY_TIMEOUT |
Клиент ждёт ответа дольше заданного | minutes, 1–1440 |
INCOMING_MESSAGE |
Пришло сообщение от клиента | keywords — массив слов, пусто — любое сообщение |
EXTERNAL_REQUEST |
Запрос Запустить workflow | — |
BUTTON |
Сотрудник нажал кнопку в диалоге | label, description, requireField, userIds |
У BUTTON:
label— надпись на кнопке, до 60 символов;description— описание, до 200 символов;requireField— ключ поля карточки: кнопка видна, только если оно заполнено;userIds— сотрудники, которым доступна кнопка. Пусто — всем.
Шаги
type |
Шаг в редакторе | Основные поля data |
Выходы sourceHandle |
|---|---|---|---|
SEND_MESSAGE |
Сообщение | body |
— |
SEND_TEMPLATE |
Шаблон | templateId, variables |
— |
ASSIGN |
Назначить | mode: least_loaded или round_robin, roleId |
— |
ADD_TAG |
Добавить тег | tagId |
— |
REMOVE_TAG |
Удалить тег | tagId |
— |
WAIT |
Ждать | mode: duration (по умолчанию), random или until; minutes (1–10080), maxMinutes для random, unit; untilTime (ЧЧ:ММ) или untilBusinessHours для until; avoid: source (range или business_hours), from, to, shift (earlier или later); timeZone |
— |
BRANCH |
Условие | branches: id, label, groups (или conditions — одна группа «все») |
branch_0, branch_1… по порядку веток, else |
NOTIFY_USER |
Уведомить сотрудника | recipient: initiator, assignee или users, userIds, title, body, level: info, success или error |
— |
HTTP_REQUEST |
Внешний вызов | method, url, connectionId, headers, query, bodyType, body, bodyFields, saveResponse, once |
success, error, already_done |
REQUEST_FORM |
Запросить данные | title, fields, recipient, userIds, timeoutHours |
submitted, cancelled, timeout |
SHOW_INFO |
Показать сотруднику | varKey, title |
— |
Ветка в BRANCH — группы { "match": "all" | "any", "conditions": [...] }: внутри группы выполнены все или любое условие, группы между собой через «И». Условие: field, operator, value или values, для «сколько прошло» — unit, для своих полей и переменных — type (text, number, date, boolean, select, multiselect, ratio), для времени, дня недели и дат — timeZone (например, Asia/Almaty).
Поля: message.last, message.last_inbound, message.last_outbound, conversation.channel_type, conversation.channel, conversation.window, conversation.assignee, conversation.status, contact.tags (id тегов), contact.name, contact.custom.<ключ>, time.now, time.weekday, vars.<имя>, trigger.<путь>. Какие операторы подходят к полю, видно в редакторе; без type своё поле и переменная сравниваются как текст (equals, not_equals, contains, not_contains, exists, not_exists, gt, lt).
Поля каждого шага подробно описаны в статье Workflow и в Запросах к вашему API.
Ошибки
| Код | Когда |
|---|---|
| 400 | Поля не прошли проверку; схема с ошибками при публикации или publish; включение неопубликованного workflow; роль не из вашей компании |
| 401 | Ключ доступа не передан или неверный |
| 404 | Workflow с таким ID не найден |
Пример
Создать и сразу опубликовать workflow: при теге «Оплачено» написать клиенту.
curl -X POST https://api.polygram.chat/api/public/workflows \
-H "X-Api-Key: ak_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Спасибо за оплату",
"publish": true,
"draft_graph": {
"nodes": [
{ "id": "start", "type": "TRIGGER", "position": { "x": 0, "y": 0 },
"data": { "triggerType": "TAG_ADDED", "tagId": "cmtag0000000000000000000" } },
{ "id": "thanks", "type": "SEND_MESSAGE", "position": { "x": 0, "y": 200 },
"data": { "body": "Спасибо за оплату, $contact.name!" } }
],
"edges": [{ "id": "e1", "source": "start", "target": "thanks" }]
}
}'