Connecting chat channel

Now after understanding the information we got, let’s connect the chat channel.

First, we need to authorize it to work with the Kommo Chat API.

Authorization

The authorization in the Chat API differs from the authorization used in other Kommo API methods. To work with the Chat API, you do not need to pass an Access Token for authorization but include the following headers in all requests.

Header Description
Date Date and time when the request was generated. The signature will be valid for 15 minutes from this Date. The date should be in the format “Thu, 01 Jan 2023 12:00:00 +0000” (RFC2822)
Content-type Request data type. Currently, only application/json is supported.
Content-MD5 For the request body, it is necessary to calculate the MD5 hash and indicate it in the header in lowercase.
At the same time, it is important to keep in mind that the request body is calculated as a stream of bytes without considering the end of JSON markup, and if there are “\n” or spaces at the end, they will also be taken into account.
For GET requests, MD5 must also be calculated. Even if nothing is passed in the request body, MD5 will be obtained from an empty string.
X-Signature Signature of the request as a string. It is formed from the name of the method (GET/POST) in uppercase, with the values of the headers concatenated by “\n”. Header values ​​come in a specific order. If there is no header, an empty string is specified instead.
Next, add the requested path from the URL without the protocol and domain (without GET parameters) to the line.
The resulting string is calculated using HMAC-SHA1, and as a secret, we use the channel secret obtained during registration. The resulting hash in lowercase is indicated in the X-Signature header.

Request body

Parameter Description
account_id Chat participant ID on the Kommo side (amojo_id)
title Bot name
hook_api_version The Chat API version (V1 or V2 according to the response we get)

 
The request body will be involved in the request twice, once as its body, and another as the body’s MD5 will enter in the signature.

General requirements for Chat API requests

  • All requests to the Chat API must be made to the domain amojo.kommo.com, and have the headers: Date, Content-Type, Content-MD5, X-Signature.
  • It is forbidden to use a secret key in JS. All requests using the secret should be executed only from the backend part of your application.
  • The parameters are passed in the request body in JSON format.
  • The chat API has strict typing, so the expected argument type is reflected in the parameter description. Pay attention to this.

Example in PHP

The following code shows how to get the MD5 and the signature, and then send the request.

$secret = 'fb50586ff7b68cd831fe0ef356345903f644c0d2';
$method = 'POST';
$contentType = 'application/json';
$date = date(DateTimeInterface::RFC2822);// in format "Wed, 23 Nov 2022 19:25:21 +0000"
$path = '/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d56b21/connect';

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

$body = [
	'account_id' => '52fd2a28-d2eb-4bd8-b862-b57934927b38',
	'title' => 'MyKommo',
	'hook_api_version' => 'v2',
];

$requestBody = json_encode($body);
$checkSum = md5($requestBody);

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

$signature = hash_hmac('sha1', $str, $secret);
 
$headers = [
	'Date' => $date,
	'Content-Type' => $contentType,
	'Content-MD5' => strtolower($checkSum),
	'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;

The Result is the request

POST https://amojo.kommo.com/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d56b21/connect 
Date: Wed, 23 Nov 2022 19:25:21 +0000 
Content-Type: application/json 
Content-MD5: fa59c326af78bd12ed820daa497ab999 
X-Signature: 25cbdaf233141f78de42b022cdc3165564a9887d 
{
   "account_id":"52fd2a28-d2eb-4bd8-b862-b57934927b38",
   "title":"MyKommo",
   "hook_api_version":"v2"
}

Example of a result

After getting the method, the URL, the headers and the body, you can run your request anywhere suitable for you. We used an API platform and got the following result.

{
   "account_id": "52fd2a28-d2eb-4bd8-b862-b57934927b38",
   "scope_id": "f62a0162-46a7-430e-b06c-0ef798d56b21_52fd2a28-d2eb-4bd8-b862-b57934927b38",
   "title": "MyKommo",
   "hook_api_version": "v2"
}

The result shows that there is an account scope_id for your channel

Parameter Type Description
account_id string Account Id
scope_id string UUID, scope_id account for your channel