How to Integrate External System via Custom Channel

Custom Channel allows integrating ConnectiveOne with any external system that can send and receive HTTP requests. This is useful for connecting existing bots, CRM systems, or new communication channels.

When to Use Custom Channel?

Custom Channel is suitable for such cases:

Connecting an existing bot from another system to ConnectiveOne
Extending capabilities of an existing bot thanks to ConnectiveOne (for example, connecting operator panel)
Connecting correspondence within CRM to ConnectiveOne
Integrating internal communication systems
Quickly connecting new channels (messengers) for which there is no official integration yet

Prerequisites

Before starting integration, make sure that:

You have a developer team on the external system side with experience in REST API and JSON
You can control request formats that your system sends and receives
You have tried integration through Postman or another HTTP client
You have contacted ConnectiveOne support if you need clarification on request or event formats

How Does Custom Channel Work?

Custom Channel works through a sequence of HTTPS POST requests:

Incoming flow (from external system to ConnectiveOne):

Your system sends POST requests to ConnectiveOne's input_url
ConnectiveOne processes messages through bot scenarios

Outgoing flow (from ConnectiveOne to external system):

ConnectiveOne sends messages and events to your custom_channel_url
Your system processes incoming messages and events

Configuration

Step 1: Configuration in ConnectiveOne

Go to Bot Settings → select the needed bot
Scroll to the Custom Channel section
Configure the following parameters:

custom_channel_url — address of your server where ConnectiveOne will send messages
- For testing, you can use services like https://requestcatcher.com/
custom_channel x-access-token — token that ConnectiveOne will pass in the x-access-token header of each message
- If your service doesn't support this, leave it empty
input_url — auto-generated field, address to which you need to send messages
- This field is generated automatically after configuration
custom_channel kwizbot token — token for signing messages sent to ConnectiveOne
- Specified in the request header as x-auth-token
- If left empty, ConnectiveOne will accept messages without a token

Sending Messages to ConnectiveOne

URL Format

POST https://{{engine_url}}/messengers_host/{{bot_id}}/custom_channel/hooks

Where:

engine_url — engine.instance_name.connectiveone.io or engine-instance_name.connectiveone.io
bot_id — bot ID from the settings page

Example Request

{
  "update_id": 498995546,
  "message": {
    "from": {
      "id": "wregw3ergwergwergw==",
      "first_name": "",
      "last_name": "",
      "username": "Natalia",
      "language_code": "uk",
      "is_bot": false,
      "phone": "888888888888",
      "channel": "viber",
      "dialog_name": "Natalia"
    },
    "chat": {
      "id": "wregw3ergwergwergw==_viber"
    },
    "date": 1696408917974,
    "text": "Kyiv",
    "type": "text"
  }
}

🧑‍💻 Note: To start the bot, you need to send /start as the first message.

Request Parameters

Parameter	Type	Description
`update_id`	int	Unique value
`message.from.id`	string	User ID
`message.from.first_name`	string	User first name in operator panel
`message.from.last_name`	string	User last name
`message.from.username`	string	User nickname
`message.from.language_code`	string	Language code (uk, ru, en)
`message.chat.id`	string	User chat code
`message.text`	string	Message text (for start: `/start`)
`message.type`	string	Message type (text)
`message.from.dialog_name`	string	Chat name for display in operator panel

Receiving Messages from ConnectiveOne

Your service will receive a POST request to custom_channel_url with these headers:

POST /your_url HTTP/1.1
Host: your-service.com
Content-Type: application/json;charset=utf-8
User-Agent: ConnectiveOne
x-access-token: YOUR_TOKEN

Example request body:

{
  "reply_markup": {
    "remove_keyboard": false
  },
  "chat_id": "398866",
  "text": "Notifications bot\nMy chat id: 398866,  channel custom_channel",
  "id": "71577138-fe1e-4ce7-b53e-0cec45ee3534",
  "from": "bot",
  "bot_id": 71,
  "type": "text"
}

Message Types

Incoming Messages (Accepted by ConnectiveOne)

text — text
image — image
text_image — text with image in one message
video — video
audio — audio message
file — file

Outgoing Messages (Sent by ConnectiveOne)

Text messages
Messages with keyboard
Sliders
Files and images (as links)

Event Types

ConnectiveOne sends the following event types:

chat_created — chat created
auto_connected — auto-connection of operator
operator_connected — operator connected
operator_disconnected — operator disconnected
chat_closed_by_operator — chat closed by operator
chat_closed — chat closed
chat_closed_by_timeout — chat closed by timeout
connection_timeout — connection timeout

Example `chat_created` Event

{
  "reply_markup": {
    "remove_keyboard": false
  },
  "chat_id": "34122",
  "text": "Chat created",
  "event_name": "chat_created",
  "client": {
    "id": 572338,
    "first_name": "Test",
    "last_name": "Surname",
    "username": "testuername",
    "language_code": "uk",
    "phone": "+380505776464",
    "channel": "telegram"
  },
  "id": "83317aa1-8ea4-4c05-afed-d7437ff88fbf",
  "from": "bot",
  "bot_id": 4,
  "type": "text"
}

📖 Documentation: If you only need events from the operator panel, consider the alternative through Operator Panel Webhook.

Bot Scenario Configuration

Step 1: Mark Channel in Blocks

In the bot scenario, after the "Section Start" element, you need to mark custom_channel in advanced settings for all blocks that will interact with Custom Channel.

Step 2: Configure Scenario Exit

To end the scenario:

Create a "Message to User" block with a conditional word for exit (for example, /exit)
In constants, specify close_chat_command with value /exit
In block advanced settings:
- Remove marks on all messengers
- Leave the custom_channel mark

Getting Available Operators

Endpoint

POST https://engine-projectname.connectiveone.io/kw/custom_channel/operators_available

Usage Example

curl --location --request POST 'https://engine-projectname.connectiveone.io/kw/custom_channel/operators_available' \
--data ''

Response Format

{
  "status": "success",
  "data": [
    {
      "id": 56,
      "max_dialogs": 30,
      "rooms_count": 0,
      "max_dialog_id": 498
    }
  ]
}

Limitations

Custom Channel works only through HTTPS
Webhook endpoint configuration is required on the external system side
Request timeout depends on system settings
It is recommended to use retry logic for reliability