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

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


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

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

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

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

1. У вашій CRM/ERP ви створюєте webhook або тригер, який відправляє виклик на спеціальний URL ConnectiveOne
2. В параметрах виклику вказується бот, точка входу (Entry Point), ID користувача, канал (месенджер) та додаткові дані
3. 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 запиту

```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 відповіді (опціонально) |

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

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

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

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

```bash
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 токеном:**

```http
Authorization: Bearer YOUR_JWT_TOKEN
```

> 📖 **Документація:** Детальніше про авторизацію читайте в [Використання API](/uk/integrations/how-to/use-api.md).

## Обмеження

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

## Пов'язані статті

- [Запуск сценарію через deeplink](/uk/integrations/explanation/deeplink-launch.md)
- [Підписка користувача на нотифікації](/uk/integrations/how-to/data-transfer/subscribe-user-to-notifications.md)
- [Що таке інтеграції](/uk/integrations/explanation/what-are-integrations.md)