Creating new chat

POST https://amojo.kommo.com/v2/origin/custom/{scope_id}/chats

Description

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

You can also specify the source of the chat, then at the first incoming chat message, the incoming lead will be created in the pipeline which accepts this source.

Headers & Authorization type

The request headers are the same as the ones for all Chat API requests. Information about them is explained in details in the connect a chat channel page.

Header Description
Date Date and time when the request was generated.
Content-type Request data type.
Content-MD5 For the request body
X-Signature Signature of the request as a string.

Example of the body

{
   "conversation_id":"con-8e3e7640-49af-4448-a2c6-d5a421f7f301",
   "user":
   {
      "id":"id-1376265f-86df-4c49-a0c3-a4816df41af0",
      "avatar":"https:\/\/example.com\/users\/avatar.png",
      "name":"Client",
      "profile":
      {
         "phone":"15017627409",
         "email":"client409@example.com"
      },
      "profile_link":"https:\/\/example.com\/profile\/client409"
   }
}

Body parameters

The 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 and some of its fields.

Parameter Data type Description
conversation_id string Chat ID on the integration side
source[external_id]
Optional field 		string Identifier of the chat source on the integration side. If you do not need to specify the source, then the source field does not need to be passed.
user[id]
Mandatory field 		string Chat participant ID on the integration side
user[ref_id]
Optional field 		string Chat participant ID on the Kommo side
user[name]
Mandatory field 		string Chat participant name
user[avatar]
Optional field 		string Url to the chat participant avatar, Url should be available for download
user[profile][phone]
Optional field 		string Chat participant phone number
user[profile][email]
Optional field 		string Chat participant email address
profile_link
Optional field 		string Url to the chat participant profile

Note: 

  1. The user[id] should be unique. If you enter an existing user[id] you will get the existing information related to this user.
  2. The request body should be exactly the same when calculating the Content-MD5 and the X-Signature.

Example in PHP

$secret = 'fb50586ff7b68cd831fe0ef356345903f644c0d2';
$method = 'POST';
$contentType = 'application/json';
$date = date(DateTimeInterface::RFC2822);// in format "Wed, 30 Nov 2022 16:33:21 +0000";
$path = '/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d56b21_52fd2a28-d2eb-4bd8-b862-a67934927b38/chats';

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

$body = [
    'conversation_id' => 'con-8e3e7640-49af-4448-a2c6-d5a421f7f301',
    'user' => [
        'id' => 'id-1376265f-86df-4c49-a0c3-a4816df41af0',
        'avatar' => 'https://example.com/users/avatar.png',
        'name' => 'Client',
        'profile' => [
            'phone' => '15017627409',
            'email' => 'client409@example.com',
        ],
        'profile_link' => 'https://example.com/profile/client409',
    ],
];

$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_52fd2a28-d2eb-4bd8-b862-a67934927b38/chats' \
--header 'Content-Type: application/json' \
--header 'Date: Wed, 30 Nov 2022 16:33:21 +0000' \
--header 'Content-MD5: cba2ef1aac9e2870b6d4cbded5b12c92' \
--header 'X-Signature: 1eed486eab1a90c33de2c49290daeabc14677a08' \
--data-raw '{"conversation_id":"skc-8e3e7640-49af-4448-a2c6-d5a421f7f301","user":{"id":"sk-1376265f-86df-4c49-a0c3-a4816df41af0",
"avatar":"https:\/\/example.com\/users\/avatar.png",
"name":"Client",
"profile":{"phone":"15017627409","email":"client409@example.com"},
"profile_link":"https:\/\/example.com\/profile\/client409"}}'

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 code Case
200 Chat created successfully
404 Channel does not exist
403 Incorrect request signature
400 Invalid data given. Details are available in the request response

Response example

{
   "id": "eb7b1cd6-10e9-4f88-af0b-6581795e15e2",
   "user": {
       "id": "7a6aed88-7bd3-4934-b05f-23f1db1a6514",
       "client_id": "id-1376265f-86df-4c49-a0c3-a4816df41af0",
       "name": "Client",
       "avatar": "https://www.example.com/users/avatar.png",
       "phone": "15017627409",
       "email": "client409@example.com"
   }
}

Response parameters

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

Parameter Description
id Chat ID in Kommo Chat API
user[id] Chat participant ID in Kommo Chat API
user[client_id] Chat participant ID on the integration side, the field is absent for users from Kommo (The field is passed in the request in the user[id] key)
user[name] Chat participant name
user[avatar] Avatar link if it was sent, or empty field
user[phone] Chat participant’s phone number, if it was sent.
user[email] Chat participant’s email address, if it was sent.

Next, Linking chat to contact.