Chat API

Brief guide to Chat API.

Conventions
Adapter Management
List of adapters
Create an adapter
Update an adapter
Delete an adapter
Chat channels
List of channels
Adapter connections
List of connections
Create a connection
Update a connection
Delete a connection
Chat API
Adapter Authentication in Chat API
Chat API Methods
- Create a chat
- Close a chat
- Transfer a chat
- Send a message
- Upload a resource
- Get resource data
Webhooks
- Account created
- Account updated
- Account deleted
- Channel created
- Channel updated
- Channel deleted
- New chat
- Chat updated
- Chat closed
- Chat assigned to an operator
- New message
- Message updated
- Message status updated
- Visitor information updated
Working with the waba channel type
Examples
Change Log

Conventions

Personal Account is a web application hosted under go.callgear.ae.
Operator Workspace is an application that allows employees to handle conversations with customers.
Adapter is a custom service that uses Chat API methods and webhooks to implement its own operator workspace.
Chat channel is a connected chat channel in the client account, such as Website Chat, Telegram, or Viber.
Adapter account is an adapter connection created by the client in the Personal Account.
Adapter channel is a chat channel connected within the adapter.
Webhook is an HTTP request that Chat API sends to the adapter when entities change without the adapter directly initiating those changes, for example when a chat is created or a visitor sends a message.

Adapter Management

To get started, you need to register an integration adapter. This can be done through the Personal Account or by sending a request to the main Chat API available at https://cg-dub-omni-chats-logic.callgear.ae/. Only authorized Personal Account users can access this API. To receive an authentication token, you must send a request:

POST https://go.callgear.ae/api/auth/json_rpc?method=login
{
  "jsonrpc": "2.0",
  "id": "0",
  "method": "login",
  "params": {
    "login": "username",
    "password": "password",
    "project": "usa"
  }
}

Requests to the main Chat API are authenticated using a token passed in the header.

POST https://cg-dub-omni-chats-logic.callgear.ae/v1/
Authorization: Bearer <token>

In the API, the adapter is represented by the Adapter entity.

Parameter name	Type	Description
`id`	`int`	Adapter ID
`type`	`str`	Unique adapter mnemonic, matches the regular expression `^[a-z0-9_]+$`
`name`	`str`	Adapter name
`status`	`enum`	Adapter status. Valid values: `active`, `disabled`
`supported_channel_types`	`enum`	List of channel mnemonics. Valid values: `comagic`, `telegram`, `auto_ru`, `avito`, `realty_yandex`, `viber`, `telegram_private`, `whatsapp`, `waba`, `sms`, `email`
`owner`	`int`	ID of the adapter owner. Can be `null`, in which case the adapter is a system adapter
`visibility_status`	`enum`	Adapter visibility status; for custom adapters only takes the value `private`
`login`	`str`	Login for adapter authorization
`password`	`str`	Password for adapter authorization
`webhook_url`	`str`	Address for webhooks from Chat API
`webhook_version`	`str`	Webhook version. Available versions: `v1`, `v2`; the default version is `v2`.
`webhook_token`	`str`	Chat API authentication token used for webhooks. May not be used together with `webhook_auth`. This attribute is obsolete and is not recommended for use.
`webhook_auth`	`object`	Chat API authentication configuration for webhooks. May not be used together with `webhook_token`.
`webhook_kwargs`	`dict[str, Any]`	An associative array with additional arguments for webhooks. Valid keys: `timeout` with a value of type `float`, to control the waiting time for a response from the adapter; an associative array of additional headers `headers`, of the form `{"name": "value"}`.

The webhook_auth object specifies the authentication method for webhooks using a persistent token or login-password pair.

For persistent token authentication, you must set the value of webhook_auth as follows:

{
  "type": "Bearer",
  "token": "string"
}

In this case, all webhooks will contain a header Authorization: Bearer <token>.

To use a login-password pair, the value of webhook_auth is set as follows:

{
  "type": "Basic",
  "login": "string",
  "password": "string"
}

In this case, all webhooks will contain the header Authorization: Basic <credentials>, where credentials is the Base64-encoded pair <login>:<password>.

List of adapters

GET /v1/integration/adapter

Returns a list of Adapter entities, including both user-created adapters and system adapters. System adapters are identified by the owner attribute set to null. System adapters cannot be modified.

Create an adapter

POST /v1/integration/adapter
{
  "type": "string",             
  "name": "string",             
  "login": "string", 
  "password": "string",
  "webhook_url": "string",
  "webhook_version": "string",
  "webhook_token": "string",
  "webhook_auth": {
    "type": "Bearer",
    "token": "string"
  },
  "supported_channel_types": [  
    "comagic",
    "telegram",
    "whatsapp"
  ]
}

As a result, the Adapter entity is returned.

Update an adapter

PATCH /v1/integration/adapter/{adapter_id}
{
  "name": "string",
  "login": "string",
  "password": "string",
  "status": "active",
  "webhook_url": "string",
  "webhook_version": "string",
  "webhook_token": "string",
  "webhook_auth": {
    "type": "Bearer",
    "token": "string"
  },
  "webhook_kwargs": {},
  "supported_channel_types": [
    "comagic"
  ]
}

The method allows you to change the following entity attributes: name, login, password, status, webhook_url, webhook_version, webhook_token, webhook_auth, supported_channel_types.

Delete an adapter

DELETE /v1/integration/adapter/{adapter_id}

The adapter can only be removed when it is not in use.

Chat channels

The Channel entity represents the connected chat channel in the client account.

{
  "id": 0,
  "type": "comagic",
  "name": "string",
  "is_removed": true,
  "status": "string", 
  "status_reason": "string"
}

Parameter name	Type	Description
`id`	`int`	Channel ID
`type`	`enum`	Channel mnemonic
`name`	`str`	Channel name
`is_removed`	`bool`	Logical delete flag
`status`	`enum`	Status
`status_reason`	`str`	Reason for status change

List of channels

GET /v1/integration/channel

Returns a list of entities of type Channel.

Adapter connections

The adapter connection is represented by the Account entity.

{
  "name": "string",
  "adapter_id": 0,
  "channels": [
    0
  ],
  "context": {},
  "id": 0,
  "status": "string"
}

Parameter name	Type	Description
`id`	`int`	Account ID
`adapter_id`	`int`	Adapter ID
`name`	`str`	Account name
`channels`	`list[int]`	List of channel IDs
`context`	`dict[str, Any]`	Associative array with additional parameters. Valid keys: `is_chat_integration_scenario_created` with a Boolean value, allows you to control the automatic attachment of the "Forwarding to CRM" scenario for connected channels
`status`	`enum`	Connection status. Valid values: `active`, `disabled`

List of connections

GET /v1/integration/account

Returns a list of entities of type Account.

Create a connection

POST /v1/integration/account
{
  "name": "string",
  "adapter_id": 0,
  "channels": [
    0
  ],
  "context": {}
}

Update a connection

PATCH /v1/integration/account/{account_id}
{
  "name": "string",
  "channels": [
    0
  ],
  "context": {}
}

The method allows you to change the following entity attributes: name, channels, context.

Delete a connection

DELETE /v1/integration/account/{account_id}

Chat API

The service is available at https://chat-integration-api-cg.callgear.ae/

Entities

Account - represents the connection of the adapter by the client.

{
  "id": 0,
  "name": "string",
  "adapter_id": 0,
  "client_id": 0,
  "context": {},
  "status": "active"
}

Parameter name	Type	Description
`id`	`int`	Unique account identifier
`name`	`str`	Account name
`adapter_id`	`int`	Adapter ID
`client_id`	`int`	Internal entity identifier, always takes the value `1`
`context`	`dict[str, Any]`	Additional parameters, always contains the key `app_id` with the identifier of the client that connected the adapter
`status`	`enum`	Account status. Possible values: `active`, `disabled`

Channel - represents the connection of the chat channel in the account.

{
  "id": 0,
  "name": "string",
  "type": "comagic",
  "account_id": 0,
  "context": {},
  "status": "active"
}

Parameter name	Type	Description
`id`	`int`	Unique channel identifier
`account_id`	`int`	Unique account identifier
`name`	`str`	Channel name
`type`	`enum`	Chat channel mnemonic. Possible values: `comagic`, `telegram`, `auto_ru`, `avito`, `realty_yandex`, `viber`, `telegram_private`, `whatsapp`, `waba`, `sms`, `email`
`context`	`dict[str, Any]`	Additional options. Always contains the keys `app_id` with a unique identifier of the client who made the connection, as well as `chat_channel_id` - a unique identifier of the connected chat channel
`status`	`enum`	Channel status. Possible values: `active`, `disabled`

Adapter authentication in Chat API

All requests to the Chat API must contain the Authorization header:

Authorization: Bearer <token>

To obtain a token, the adapter must issue a request:

POST /v1/adapter/login
Content-Type: application/x-www-form-urlencoded

username={adapter_login}&password={adapter_password}

The response will contain the token, type and unix timestamp indicating the end of the token's lifetime:

{
  "access_token": "string",
  "token_type": "bearer",
  "expires_at": 0
}

Once the token lifetime has expired, the authentication procedure must be repeated.

Chat API Methods

Creating a chat

Creating a chat from the adapter is only possible for channels that allow you to start communication first. This function is supported by the following channel types: whatsapp, waba, telegram_private, sms, email.

POST /v1/adapter/chat
{
  "account_id": 0,
  "channel_id": 0,
  "visitor_phone": "string",
  "visitor_email": "string",
  "visitor_username": "string",
  "operator_id": 0,
  "initiator": "operator",
  "created_at": "2023-01-01T00:00:00.000Z"
}

Description of the Chat entity:

Parameter name	Type	Description
`account_id`	`int`	Account ID
`channel_id`	`int`	Channel ID
`operator_id`	`int`	Operator ID. The operator must be registered in their Personal Account and have the appropriate privileges
`initiator`	`enum`	Initiator mnemonic. Possible values: `operator`, `visitor`, `autoinvite`, `chat_channel`. Allowed values: `operator`
`visitor_phone`	`Optional[str]`	Phone number of the user with whom the conversation will be conducted (used for channels like `whatsapp`, `waba`, `sms`, `telegram_private`)
`visitor_email`	`Optional[str]`	Email address of the user with whom the conversation will be conducted (used for channel type `email`)
`visitor_username`	`Optional[str]`	Short name of the user with whom the conversation will be conducted, in the format `@username` (used for channel type `telegram_private`)
`created_at`	`str`	Date and time in `ISO 8601` format

When creating a chat, one of the attributes visitor_phone, visitor_email or visitor_username must be passed, depending on the type of channel in which the communication is initialized. The response will return the sent entity with the attributes chat_id, which is the request identifier, and visitor_id, which is the identifier of the user with whom the conversation is being conducted. Both parameters should be used later when sending chat messages.

Ending chat

POST /v1/adapter/chat/close
{
  "context": {},
  "account_id": 0,
  "channel_id": 0,
  "chat_id": 0,
  "operator_id": 0,
  "reason": "closed_by_timeout"
}

Parameter name	Type	Description
reason	`enum`	Reason for termination. Possible values: `closed_by_timeout`, `invite_rejected`, `closed_by_operator`, `closed_by_visitor`, `visitor_banned`, `external_window_closed`, `visitor_disconnected`, `visitor_session_expired`, `closed_by_scenario`. Allowed values: `closed_by_operator`
operator_id	`int`	Operator ID. The parameter is optional; it must be passed if `closed_by_operator` is passed in the value of the `reason` parameter

Chat transfer

POST /v1/adapter/chat/transfer
{
  "context": {},
  "account_id": 0,
  "channel_id": 0,
  "chat_id": 0,
  "from_operator_id": 0,
  "to_operator_id": 0
}

Parameter name	Type	Description
from_operator_id	`int`	Current chat operator ID
to_operator_id	`int`	Operator ID to whom the chat will be assigned

Sending message

To send a message to a chat, you need the chat_id. You can get it either from the create-a-chat response or from the new-chat webhook.

POST /v1/adapter/message
{
  "account_id": 0,
  "channel_id": 0,
  "chat_id": 0,
  "operator_id": 0,
  "reply_to_id": 0,
  "text": "string",
  "created_at": "2023-01-01T00:00:00.000Z",
  "source": "system",
  "resource": {
    "id": 0,
    "token": "string",
    "type": "photo",
    "name": "string",
    "size": 0
  }
}

Description of the Message entity:

Parameter name	Type	Description
`account_id`	`int`	Account ID
`channel_id`	`int`	Channel ID
`chat_id`	`int`	Chat ID
`operator_id`	`int`	Operator ID
`reply_to_id`	`int`	Optional message ID for quoting
`text`	`str`	Message text
`created_at`	`str`	Date and time in `ISO 8601` format
`source`	`enum`	Mnemonic of the message sender. Valid values: `operator`
`resource`	`Resource`	Object `Resource` with a description of the resource (file) attached to the message
`context`	`Optional[dict[str, Any]]`	Optional object with additional information

Adding resource

POST /v1/adapter/resource
Content-Type: multipart/form-data

...

The form must contain the following attributes:

Parameter name	Type	Description
`account_id`	`int`	Account ID
`channel_id`	`int`	Channel ID
`type`	`enum`	Resource type. Possible values: `photo`, `video`, `audio`, `voice`, `document`
`file`	`bytes`	Transferred file

The response returns the Resource entity:

Parameter name	Type	Description
`id`	`int`	Resource ID
`token`	`str`	Resource token
`type`	`enum`	Resource type. Possible values: `photo`, `video`, `audio`, `voice`, `document`
`name`	`str`	File name
`size`	`int`	File size in bytes

Retrieving resource data

GET /v1/adapter/resource/{account_id}/{channel_id}/{resource_id}/{resource_token}/payload

Webhooks

Webhooks are sent to the webhook_url address specified in the adapter settings. webhook_url is used as the base URL: the final address of each webhook is formed by appending a path specific to the event or entity, for example /account or /chat. Authentication data is passed in the Authorization header:

Authorization: {Type} {Credentials}

If the webhook_token attribute is specified when creating an adapter, the Authorization header is formed as follows:

Authorization: Bearer {webhook_token}