Chat API

Agreements

The following agreements are accepted when using Chat API:

• Personal Account – A web application located in the domain go.callgear.com or go.calglear.ae.
• Operator’s Workspace – An application that allows employees to engage in conversations with customers.
• Adapter – A user service that implements a custom version of the Operator’s Workspace using Chat API method requests and webhooks processing.
• Chat Channel – A connected chat channel (Website Chat, WhatsApp, Instagram, Facebook, Telegram etc.) in the client’s account.
• Adapter Account – A client’s integration of an adapter in the Personal Account.
• Adapter Channel – A connection of a chat channel within the adapter.

Webhook – An HTTP request that Chat API sends to the adapter when an entity changes without direct participation from the adapter itself (e.g., chat creation, message sent by a visitor, system messages, etc.).

Manage Adapters

To begin, you need to register an integration adapter. This can be done by sending a request to the primary Chat API, available at:
https://chats-cg-logic.callgear.ae (UAE) or https://chats-cg-logic.callgear.com (international; from this point forward, all links in the document will default to the .ae domain. If you are outside the UAE and your Callgear account uses the .com domain, please replace .ae with .com wherever necessary). Only authorized users of the Personal Account have access to the API. To obtain an authentication token, you need to 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"
 }
}

All requests to the main Chat API must be authenticated using a token, which is passed in the request header.

POST https://chats-cg-logic.callgear.ae/v1/
Authorization: Bearer 

In the API, adapters are represented by the Adapter entity.

json
{
  "id": 0,
  "type": "string",
  "name": "string",
  "status": "active",
  "supportedchanneltypes": [
    "comagic",
    "telegram",
    "facebook",
    "viber",
    "telegram_private",
    "whatsapp",
    "instagram",
    "waba",
    "sms"
  ],
  "owner": 0,
  "visibility_status": "private",
  "login": "string",
  "password": "string",
  "webhook_url": "string",
  "webhook_version": "string",
  "webhook_token": "string",
  "webhook_auth": {
    "type": "Bearer",
    "token": "string"
  },
  "webhook_kwargs": {}
}

The webhook_auth object defines the authentication method for webhook requests. It allows authentication using a token:

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

Alternatively, you can also use login-password pair:

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

Adapters List

GET /v1/integration/adapter

Returns a list of Adapter entities, including both user-added adapters and system adapters. System adapters are distinguished by having a null value in the owner attribute. System adapters cannot be modified.

Create Adapter

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

Returns the created Adapter entity.

Update Adapter

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

Allows updating the following attributes: name, login, password, status, webhookurl, webhooktoken, webhookauth, supportedchannel_types.

Delete Adapter

DELETE /v1/integration/adapter/{adapter_id}

An adapter can only be deleted if it is not in use.

Chat Channels

Entity channel represents a connected chat channel within a client account.

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

Channels List

GET /v1/integration/channel

Returns a list of Channel entities.

Connect Adapter

The adapter connection is represented by the Account entity.

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

Connections List

GET /v1/integration/account

Returns a list of Account entities.

Create Connection

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

Update Connection

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

Allows updating the following attributes: name, channels, context.

Delete 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 adapter connection by a client.

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

Channel represents the chat channel connection within an account.

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

Adapter Authentication in Chat API

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

Authorization: Bearer 

To obtain a token, the adapter must make the following request:

POST /v1/adapter/login
Content-Type: application/x-www-form-urlencoded
username={adapterlogin}&password={adapterpassword}

The response will contain the token, type, and a Unix timestamp indicating the token’s expiration time.

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

Once the token expires, authentication must be repeated.

Chat API Methods

Create Chat

Creating a chat from an adapter is only possible for channels that allow initiating communication first. Currently, only chat channels with the mnemonic whatsapp support this functionality.

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

Chat Entity Description

The response will contain the sent entity with the attributes:

1. chat_id – Identifier of the conversation.
2. visitor_id – Identifier of the user with whom the conversation is conducted.

Both parameters must be used for sending messages in the chat.

Finish Chat

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

Transfer Chat

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

Send Message

To send a message in a chat, you need to know the chat identifier chat_id, which can be obtained either when creating the chat or from a webhook received upon chat creation.

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

Message Entity Description

Add Resource

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

The form must contain the following attributes:

The response will contain the requested resource data.

Get Resource Data

GET /v1/adapter/resource/{accountid}/{channelid}/{resourceid}/{resourcetoken}/payload

Webhooks

Webhooks are sent in response to interactions with chat entities to the webhook_url specified in the adapter configuration. Authentication data is included in the Authorization header.

Authorization: {Type} {Credentials}

In cases where the webhook_token attribute is specified when creating the adapter, the Authorization header is formed as follows:

Authorization: Bearer {webhook_token}

Create Account

Available in versions: v1, v2

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

Update Account

Available in versions: v1, v2

PATCH /account/{account_id}
{
 "id": 0,
 "name": "string",
 "adapter_id": 0,
 "client_id": 0,
 "context": {},
 "status": "active"
}

Delete Account

Available in versions: v1, v2

DELETE /account/{account_id}
{
 "id": 0,
 "name": "string",
 "adapter_id": 0,
 "client_id": 0,
 "context": {},
 "status": "active"
}

Create Channel

Available in versions: v1, v2

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

Update Channel

Available in versions: v1, v2

PATCH /channel/{channel_id}
{
 "id": 0,
 "name": "string",
 "type": "comagic",
 "account_id": 0,
 "context": {},
 "status": "active"
}

Delete Channel

Available in versions: v1, v2

DELETE /channel/{channel_id}
{
 "id": 0,
 "name": "string",
 "type": "comagic",
 "account_id": 0,
 "context": {},
 "status": "active"
}

Create Chat

Available in versions: v1, v2

POST /chat
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "visitor_id": 0,
 "visitor_phone": "string",
 "operator_id": 0,
 "initiator": "operator",
 "created_at": "2023-01-01T00:00:00.001Z"
}

Update Chat

Available in versions: v2

PATCH /chat
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "operator_id": 0
}

Close Chat

Available in versions: v1, v2

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

operatorid is optional.

Assign Chat to Operator

Available in versions: v1

POST /chat/operator
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "operator_id": 0
}

Send Message

Available in versions: v1, v2

POST /message
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "id": 0,
 "chat_id": 0,
 "source": "system",
 "operator_id": 0,
 "replytoid": 0,
 "text": "string",
 "created_at": "2023-01-01T00:00:00.001Z",
 "status": "accepted",
 "resource": {
  "id": 0,
  "token": "string",
  "type": "photo",
  "name": "string",
  "size": 0
 },
 "systemmessagemnemonic": "string"
}

The status parameter can have the following values: accepted, delivered, read, sent, error.

Update Message

Update Message Status

Available in versions: v1, v2

POST /message/status
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "chat_id": 0,
 "message_id": 0,
 "status": "accepted"
}

Update Visitor Information

Available in versions: v1, v2

POST /visitor/card
{
 "context": {},
 "account_id": 0,
 "channel_id": 0,
 "visitor_id": 0,
 "visitor_card": {}
}

Visitor Card Object Description

Transition from Webhook v1 to v2

Key Differences:

1. Instead of a webook for chat assignment to an operator, v2 uses a chat update request.
2. A new message update webhook has been added.

Working with WABA Channels

WABA (WhatsApp Business API) channels have specific restrictions:

1. Outbound communications can only be initiated using predefined templates.
2. Conversations can only take place within a time window, which starts when a visitor responds to an operator’s message.

Information about available templates (and their modifications) is sent in webhooks related to the channel in the attribute context["message_templates"], which is a list[MessageTemplate].
To fully support WABA templates, the adapter must implement webhook version v2.

MessageTemplate Structure:

MessageTemplateContent Structure:

MessageTemplateContentHeader Structure:

MessageTemplateContentFooter Structure:

MessageTemplateContentKeyboard Object Structure:

MessageTemplateContentKeyboardRow Object Structure:

Parameter	Type	Description
buttons	list[MessageTemplateContentButton]	List of buttons