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:

  1. Open the help menu (help icon in the upper right corner)
  2. 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: Use the /api/v1/auth/login endpoint to obtain a JWT 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?

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