How to Use ConnectiveOne API

ConnectiveOne provides REST API for receiving and changing data, launching scenarios, and integrating with external systems. This article explains the basics of working with API. For a complete list of endpoints and details, see API reference.

What Can You Do Through API?

Get data about dialogues, operators, users, tickets
Change dialogue parameters (status, topic, comment)
Launch bot scenarios
Manage data through Custom Data API
Get statistics and analytics

Access to API Documentation

To view all available endpoints:

Open the help menu (help icon in the upper right corner)
Select "API Documentation"

Swagger UI opens with complete documentation and the ability to test endpoints.

💡 Tip: Swagger UI allows not only viewing documentation but also testing API endpoints directly in the interface.

Authorization

Authorization is required to make API requests. ConnectiveOne supports two types of authorization:

API Key (Simplified Authorization)

Used for simple requests. The API key can be obtained in Settings → Bot List → Bot Settings.

Header format:

Authorization: API-Key YOUR_API_KEY

Example curl:

curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/general/KwBots/get \
  -H "Authorization: API-Key YOUR_API_KEY"

JWT Token (Full Authorization)

For enterprise clients, JWT token authorization is available, which includes token refresh functions, expiration setting, and request rate limiting.

Header format:

Authorization: Bearer YOUR_JWT_TOKEN

Obtaining JWT token: Send POST /api/v1/auth/token with a JSON body:

Parameter	Required	Description
`email`	yes	Panel user email
`password`	yes	User password
`expires_in`	no	Token lifetime in seconds, as a number, not a string (`86400`, not `"86400"`). Without it, the lifetime follows the instance settings

By default, expires_in cannot exceed the instance's standard session lifetime.

Longer token lifetime for integrations. If extended token lifetime is enabled for your instance (the ConnectiveOne team turns it on), you can pass expires_in up to the configured value, but no more than 30 days (2592000). This way an integration (for example, an accounting system) renews its token once a day or once a month instead of every hour.

curl -X POST https://engine-instancename.connectiveone.io/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "YOUR_PASSWORD", "expires_in": 2592000}'

If expires_in is above the allowed maximum, you get a 400 error with the allowed range in the message, for example: expires_in must be an integer number of seconds between 1 and 3600 (1h). The maximum is set by the instance configuration.

This token is not renewed via /api/v1/auth/refresh: when it expires, request a new one with the same POST /api/v1/auth/token.

Main Request Types

GET (Receiving Data)

Used to receive data from ConnectiveOne.

Format:

GET https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/get

Example:

curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/get \
  -H "Authorization: API-Key YOUR_API_KEY"

POST (Creating/Updating)

Used to create or update data.

Format:

POST https://engine-{{project_name}}.connectiveone.io/kw/api/{{module-name}}/{{entity-name}}/set

Example:

curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/set \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed",
    "chatroom_id": 123
  }'

Response Format

Successful response:

{
  "status": "success",
  "data": [...]
}

Error:

{
  "status": "error",
  "message": "Error description"
}

Usage Examples

Example 1: Getting Dialogue List

curl -X GET \
  https://engine-instancename.connectiveone.io/kw/api/v1/OpChatRooms/list \
  -H "Authorization: API-Key YOUR_API_KEY"

Example 2: Changing Dialogue Status

curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "closed"
  }'

Example 3: Changing Dialogue Topic and Status

curl -X POST \
  https://engine-instancename.connectiveone.io/kw/api/operator_panel/OpChatRooms/123/ \
  -H "Authorization: API-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": 5,
    "status": "processed",
    "kw_chat_title": "New Title",
    "comment": "Updated via API"
  }'

Available Modules

General Module

Bot list
Registered clients

Operator Panel Module

Dialogues through operator panels
Operators
Topics (subject areas) in operator panels
Quick replies
Skill groups

Custom Data Module

All data from custom modules

API for Launching Scenarios

call_node - launch scenario via API
Entry Point URLs - direct links for launching

Security and Limitations

Security

Use HTTPS for all requests
Keep API keys and tokens in a secure place
Do not share keys in public places or logs
You can configure an IP address list to limit access
Data is stored according to ISO 27001 standard

Limitations

API module is available for enterprise users
Authorization is required for all requests
Rate limiting may be applied depending on the tariff plan
Maximum data size is limited by system settings

Where to Find Complete Documentation?

Swagger UI in system — help menu → API Documentation (/api-docs)
API reference — complete list of endpoints

API reference — complete list of endpoints and parameters
Launch scenario via API call_node
What are integrations — overview of integration types