Як запустити сценарій бота через API call_node

Call Node API дозволяє запускати сценарії ботів з зовнішніх систем (CRM, ERP, ваші застосунки). Це корисно для відправки повідомлень клієнтам про статус замовлення, опитування задоволеності, нагадування про оплату та інші автоматизовані сценарії.

Коли використовувати call_node?

Call Node підходить для таких кейсів:

Повідомлення про статус замовлення/доставки — клієнт зробив замовлення та бажає отримувати повідомлення про те, що замовлення скомплектоване, відправлене, доставлене
Опитування задоволеності — через деякий час після надання послуги або доставки товару пропонувати клієнту оцінити якість послуги
Нагадування про необхідність оплати
Пропозиція повторити замовлення
Інтеграційні процеси — наприклад, синхронізація довідників

Як працює інтеграція?

У вашій CRM/ERP ви створюєте webhook або тригер, який відправляє виклик на спеціальний URL ConnectiveOne
В параметрах виклику вказується бот, точка входу (Entry Point), ID користувача, канал (месенджер) та додаткові дані
ConnectiveOne отримавши запит запускає сценарій для зазначеного користувача з зазначеної точки

Швидкий запуск через Entry Point URL

У будь-якій точці входу (Entry Point) є API URL, на який можна відправити POST або GET запит.

Приклад URL:

https://engine-instancename.connectiveone.io/kw/api/call_node/18/3

Структура URL:

https://engine-instancename.connectiveone.io/kw/api/call_node/{{bot_id}}/{{node_id}}

💡 Примітка: Якщо ви не передаєте додаткові параметри, ви запускаєте процес з випадковим унікальним chat_id та для каналу custom_channel. Це зручно для інтеграційних процесів.

Додаткові параметри в URL

Можна додати параметри каналу, chat_id та додаткові дані:

https://engine-instancename.connectiveone.io/kw/api/call_node/18/3/{{channel}}/{{chat_id}}?param1=val1&param2=val2

Де:

{{channel}} — канал (telegram, viber, facebook, whatsapp, custom_channel тощо)
{{chat_id}} — ідентифікатор чату з конкретним клієнтом
param1=val1&param2=val2 — рядок параметрів

Приклад:

https://engine-instancename.connectiveone.io/kw/api/call_node/18/3/telegram/398866?name=Vasya&surname=Cool

Цей запит запустить:

бот 18
секцію 3 в цьому боті
для клієнта 398866
в каналі Telegram
з параметрами name та surname (доступні в сценарії як {{name}}, {{surname}})

Використання методу call_node

Endpoint

POST https://engine-{{назва інстансу}}.connectiveone.io/kw/api/call_node/

Формат JSON запиту

{
  "chat_id": "398866372",
  "channel": "telegram",
  "bot_id": 1,
  "connector_alias": "crm_entry_point",
  "data": {
    "phone": "380961234567",
    "name": "Sergey",
    "order_id": "12345",
    "order_status": "delivered"
  },
  "callback_url": "https://callback-getter.site/"
}

Параметри запиту

Параметр	Тип	Обов'язковий	Опис
`connector_alias`	string	✅	Унікальний аліас точки входу
`chat_id`	string	✅	Унікальний ідентифікатор чата в межах каналу `channel`, який зберегли при підписці користувача на нотифікації
`channel`	string	✅	Канал комунікації: `telegram`, `viber`, `facebook`, `whatsapp`, `custom_channel` тощо
`bot_id`	integer	✅	ID бота в ConnectiveOne. За замовчуванням 1. Можна подивитись ID в Налаштування → Список ботів
`data`	object	⚠️	Додаткові параметри, які потім сценарій зможе обробити як звичайні змінні (використовувати через `{{ім'я змінної}}`)
`callback_url`	string	❌	URL для callback відповіді (опціонально)

Формат відповіді

{
  "status": "error" або "success",
  "message": "повідомлення з відповіддю",
  "data": {...дані відповіді...}
}

Приклад використання

Приклад curl запиту

curl -X POST 'https://{{engine-url}}/kw/api/call_node/' \
  -H 'Content-Type: application/json' \
  -d '{
    "chat_id": "999999999",
    "channel": "telegram",
    "bot_id": 1,
    "connector_alias": "node_alias",
    "data": {
      "phone": "380111111111",
      "name": "Randomname"
    },
    "callback_url": "https://callback-getter.site/"
  }'

Авторизація

Для виконання запитів може бути необхідна авторизація через JWT токен, якщо в налаштуваннях системи увімкнено ENABLE_JWT_FOR_CRITICAL_ROUTES=true.

Приклад з JWT токеном:

Authorization: Bearer YOUR_JWT_TOKEN

📖 Документація: Детальніше про авторизацію читайте в Використання API.

Обмеження

chat_id та channel повинні відповідати користувачу, який раніше взаємодіяв з ботом
connector_alias повинен відповідати існуючій точці входу в сценарії
Максимальний розмір data обмежений налаштуваннями системи
Timeout виконання сценарію залежить від налаштувань системи