Connecting chat channel

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

Method URL

POST https://amojo.kommo.com/v2/origin/custom/{channel.id}/connect

Description

To connect a chat channel to an account, you need to make a POST request with the channel id, passing the ID of the account in the request body.

In response, you will receive scope_id for this channel which is unique for each account, which will be used later when sending messages.

After connecting the chat channel to the Kommo account, it will be possible to work with messages and receive hooks about outgoing messages.

The connection must be made after each installation of the integration in the account, since when the integration is disabled, the channel is automatically disabled.

Headers & Authorization type

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.

Example of the body

{
   "account_id":"52fd2a28-d2eb-4bd8-b862-a67934927b38",
   "title":"MyKommo",
   "hook_api_version":"v2"
}

Body parameter

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.

Note: You should write the body in your request exactly the same as written when calculating the headers.

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;

Example of the cURL request

curl --location --request POST 'https://amojo.kommo.com/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d56b21/connect' \
--header 'Date: Wed, 30 Nov 2022 15:20:21 +0000' \
--header 'Content-type: application/json' \
--header 'Content-MD5: fa59c326af78bd12ed820daa497ab999' \
--header 'X-Signature: 25cbdaf233141f78de42b022cdc3165564a9887d' \
--data-raw '{"account_id":"52fd2a28-d2eb-4bd8-b862-b57934927b38","title":"MyKommo","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

Example of the response

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

Next we will create a new chat.