Chats API methods

In this section we will describe all available methods for working with Chats API.

Table of Contents

• General requirements
• Connecting the chat channel to the account
• Disconnecting the chat channel from the account
• Creating a new chat
• Sending or imporing messages

General requirements

All Chats API requests should be addressed to the amojo.kommo.com domains depending on the domain the account is located on.

<?php

$secret = '5a44c5dff55f3c15a4cce8d7c4cc27e207c7e189';
$method = 'POST';
$contentType = 'application/json';
$date = 'Thu, 29 Oct 2020 11:59:55 +0000';
$path = '/v2/origin/custom/f90ba33d-c9d9-44da-b76c-c349b0ecbe41/connect';

$url = "https://amojo.kommo.com" . $path;


$requestBody = '{"account_id":"af9945ff-1490-4cad-807d-945c15d88bec","title":"ScopeTitle","hook_api_version":"v2"}';
$checkSum = md5($requestBody);

$str = implode("\n", [
    strtoupper($method),
    $checkSum,
    $contentType,
    $date,
    $path,
]);

$signature = hash_hmac('sha1', $str, $secret);

$headers = [
    "Date" => $date,
    "Content-Type" => $contentType,
];
$headers['Content-MD5'] = strtolower($checkSum);
$headers['X-Signature'] = strtolower($signature);

$curlHeaders = [];
foreach ($headers as $name => $value) {
    $curlHeaders[] = $name . ": " . $value;
}


echo $method . ' ' . $url . PHP_EOL;
foreach ($curlHeaders as $header) {
    echo $header . PHP_EOL;
}
echo PHP_EOL . $requestBody . PHP_EOL;

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_POSTFIELDS => $requestBody,
    CURLOPT_HTTPHEADER => $curlHeaders,
]);

$response = curl_exec($curl);
$err = curl_error($curl);
$info = curl_getinfo($curl);
curl_close($curl);
if ($err) {
    $result = "cURL Error #:" . $err;
} else {
    echo "Status: " . $info['http_code'] . PHP_EOL;
    echo $response . PHP_EOL;
}

Connecting the chat channel to the account

Method

POST /v2/origin/custom/{channel.id}/connect

Description

After the account is connected to the chat channel, you can start working with messages and receive webhooks for outgoing messages. The chat channel should be connected after every installation of the integration because it disconnects automatically when the integration is uninstalled.

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

All fields are mandatory

An example of the request

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "title": "ChatIntegration",
  "hook_api_version": "v2"
}
        
    

Data type header when the request is successful

Content-Type: application/json

Data type header in case of an error

Content-Type: application/json

HTTP response codes.

Response parameters

Method will return the passed request fields and the scope_id required for working with messages

Response example

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "scope_id": "f90ba33d-c9d9-44da-b76c-c349b0ecbe41_af9945ff-1490-4cad-807d-945c15d88bec",
  "title": "Title",
  "hook_api_version": "v2"
}
        
    

Disconnecting the chat channel from the account

Method

DELETE /v2/origin/custom/{channel.id}/disconnect

Description

After the channel is disconnected, you will stop receiving webhooks for outgoing messages. The “initiate conversation” option will also be disabled in the lead card (upon the expiration of the front-end cache)

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

All fields are mandatory

An example of the request

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec"
}
        
    

HTTP response codes.

Response parameters

Method does not return a body

Creating a new chat

Method

POST /v2/origin/custom/{scope_id}/chats

Description

This method allows to create a chat before the first message. It can be useful if a lead with the contact already exists and an incoming lead is not needed. Chat without messages will not be displayed in the account.

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

Method creates a chat for the passed ID. In case the chat for the passed conversaton_id already exists, its ID will be returned. The “user” array is mandatory

An example of the request

        
{
    "conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
    "user": {
        "id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
        "avatar": "https:/example.com/users/avatar.png",
        "name": "Example Client",
        "profile": {
            "phone": "14151112233",
            "email": "example.client@example.com"
        },
        "profile_link": "http://example.com/profile/example.client"
    }
}

        
    

Data type header when the request is successful

Content-Type: application/json

Data type header in case of an error

Content-Type: application/json

HTTP response codes.

Response parameters

Method returns the chat ID and passed chat participant’s data

Response example

        
{
  "id": "6cbab3d5-c4c1-46ff-b710-ad59ad10805f",
  "user": {
    "id": "86a0caef-41ec-49ac-814b-b27da2cea267",
    "client_id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
    "name": "Example Client",
    "avatar": "https:/example.com/users/avatar.png",
    "phone": "14151112233",
    "email": "example.client@example.com"
  }
}
        
    

Sending or imporing messages

Method

POST /v2/origin/custom/{scope_id}

Description

This method allows to pass the client’s message into the Kommo account, in that case, the recipient specification can be skipped. Message can also be imported without the notification if silent: true parameter is passed.
It is possible to import a message from the Kommo manager to the client. For such messages, it’s mandatory to specify the recipient, and the “silent” flag will always have the value “true”.
Messages imported via this method do not trigger a webhook.

When adding several messages in a row, the “silent” flag can be set as “true” for all messages but last and “false” for the last one to notify the Kommo user only once.

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

Method creates a message and, if necessary, a chat for the passed msgid and conversation_id. The structure of the receiver and sender fields is identical.
The sender field is mandatory in any case. If the Kommo user is specified as “sender”, the “receiver” field has to be specified. The sender[id] field is not required in that case.
The message can be addressed from the client to “all” (without the “receiver” field) or from the Kommo user to the client.

An example of the request

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "event_type": "new_message",
  "payload": {
    "timestamp": 1596470952,
    "msgid": "skm-5f2836a8ca468",
    "conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
    "sender": {
      "ref_id": "d8d9f9c4-9611-4794-a136-a253a13e1bb5",
      "name": "Manager"
    },
    "receiver": {
      "id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
      "avatar": "https:/example.com/users/avatar.png",
      "name": "Example Client",
      "profile": {
          "phone": "14151112233",
          "email": "example.client@example.com"
      },
      "profile_link": "http://example.com/profile/example.client"
    }
    "message": {
      "type": "text",
      "text": "Do you need any assistance?"
    },
    "silent": true
  }
}

        
    

Data type header when the request is successful

Content-Type: application/json

Data type header in case of an error

Content-Type: application/json

HTTP response codes.

Response parameters

Method returns the amojo_id of the message that will appear in the chat feed when processed

Response example

        
{
  "new_message": {
    "msgid": "1bf6a765-ec6f-4680-8cd5-6f2d31f78ebc"
  }
}