# How to Launch Bot Scenario via API call_node

Call Node API allows launching bot scenarios from external systems (CRM, ERP, your applications). This is useful for sending messages to clients about order status, satisfaction surveys, payment reminders, and other automated scenarios.

---

## When to Use call_node?

Call Node is suitable for such cases:

- **Order/delivery status messages** — client made an order and wants to receive messages that the order is assembled, sent, delivered
- **Satisfaction surveys** — some time after service provision or product delivery, offer the client to rate service quality
- **Payment reminders**
- **Repeat order offers**
- **Integration processes** — for example, directory synchronization

---

## How Does Integration Work?

1. In your CRM/ERP, you create a webhook or trigger that sends a call to a special ConnectiveOne URL
2. In call parameters, you specify bot, entry point (Entry Point), user ID, channel (messenger), and additional data
3. ConnectiveOne, having received the request, launches the scenario for the specified user from the specified point

---

## Quick Launch via Entry Point URL

In any entry point (Entry Point), there is an API URL to which you can send a `POST` or `GET` request.

**Example URL:**

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

**URL structure:**

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

> 💡 **Note:** If you don't pass additional parameters, you launch the process with a random unique chat_id and for the **custom_channel** channel. This is convenient for integration processes.

### Additional Parameters in URL

You can add channel parameters, chat_id, and additional data:

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

Where:
- `{{channel}}` — channel (telegram, viber, facebook, whatsapp, custom_channel, etc.)
- `{{chat_id}}` — chat identifier with a specific client
- `param1=val1&param2=val2` — parameter string

**Example:**

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

This request will launch:
- bot 18
- section 3 in this bot
- for client `398866`
- in Telegram channel
- with parameters `name` and `surname` (available in scenario as `{{name}}`, `{{surname}}`)

---

## Using call_node Method

### Endpoint

```
POST https://engine-{{instance_name}}.connectiveone.io/kw/api/call_node/
```

### JSON Request Format

```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/"
}
```

### Request Parameters

| Parameter | Type | Required | Description |
|-----------|------|:--------:|-------------|
| `connector_alias` | string | ✅ | Unique entry point alias |
| `chat_id` | string | ✅ | Unique chat identifier within the `channel`, saved when subscribing user to notifications |
| `channel` | string | ✅ | Communication channel: `telegram`, `viber`, `facebook`, `whatsapp`, `custom_channel`, etc. |
| `bot_id` | integer | ✅ | Bot ID in ConnectiveOne. Default is 1. You can view ID in **Settings → Bot List** |
| `data` | object | ⚠️ | Additional parameters that the scenario can then process as regular variables (use through `{{variable_name}}`) |
| `callback_url` | string | ❌ | URL for callback response (optional) |

### Response Format

```json
{
  "status": "error" or "success",
  "message": "response message",
  "data": {...response data...}
}
```

---

## Usage Example

### Example curl Request

```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/"
  }'
```

---

## Authorization

Requests may require authorization via JWT token if `ENABLE_JWT_FOR_CRITICAL_ROUTES=true` is enabled in system settings.

**Example with JWT token:**

```http
Authorization: Bearer YOUR_JWT_TOKEN
```

> 📖 **Documentation:** Read more about authorization in [Using API](/en/integrations/how-to/use-api.md).

---

## Limitations

- `chat_id` and `channel` must match a user who previously interacted with the bot
- `connector_alias` must match an existing entry point in scenarios
- Maximum `data` size is limited by system settings
- Scenario execution timeout depends on system settings

---

## Related Articles

- [Launch scenario via deeplink](/en/integrations/explanation/deeplink-launch.md)
- [Subscribe user to notifications](/en/integrations/how-to/data-transfer/subscribe-user-to-notifications.md)
- [What are integrations](/en/integrations/explanation/what-are-integrations.md)