CHAT DEVELOPMENT
Online chats API
-
All requests to the online chat API must be signed by the secret key of your channel
-
Do not use the channel secret in JS. All requests using the secret must be sent from your server
-
Parameters should be passed in the request body in JSON format
-
The online chat API has strict typing, so the description of the parameters reflects the expected type of argument. Pay attention to this
Forming the sha1 signature
All requests include an X-Signature header with SHA1 signature of the payload data. When you create a signature, the secret of your channel is used as a key, so that such a signature allows you to check the integrity of the payload and its origin.
Example
/*
Example of the formation of SHA1 signature
*/
// The secret of our channel for the signature
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// Request body
$body = json_encode([
'event_type' => 'new_message',
'payload' => [
'timestamp' => 1500035254,
'msgid' => '5968b8c76b84c',
'conversation_id' => 'c5968b8d25082c',
'sender' => [
'id' => 'U1',
'avatar' => 'https://www.kommo.com/version2/images/logo_bill.png',
'name' => 'John',
'profile' => [
'phone' => 79151112233,
'email' => 'email@domain.com',
],
'profile_link' => 'http://example.com',
],
'message' => [
'type' => 'text',
'text' => ''Hello! How much does it cost to develop a website?'
]
]
]);
// Form the signature
$signature = hash_hmac('sha1', $body, $secret);
print($signature); // 894a6bfd9141461c177baa06b9504558bbcab686
Connecting Kommo to a new channel
Before using this method, please read:
To connect an account to the chat channel, you need to perform a POST request by submitting the request for the id of the account to be connected in the body. In response, you will receive a unique scope_id account for this channel, which will be used later when you post messages.
Method URL:
POST /v2/origin/custom/{unique channel id}/connect
Host: amojo.kommo.com
X-Signature:
Content-Type: application / json
Parameters
Parameter | Type | Description |
---|---|---|
account_id | string | UUID, A unique identifier for the account to work with the online chat service. |
Example
/*
Connecting the Kommo account to a new channel of online chats
*/
// The secret of our channel, for fonning the signature
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// ID of our channel
$channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
// Account ID for online chat service
$account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Request body
$body = json_encode([
'account_id' => $account_id
]);
// Form the signature
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://amojo.kommo.com/v2/origin/custom/{$channel_id}/connect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => array(
"Cache-Control: no-cache",
"Content-Type: application/json",
"X-Signature: {$signature}"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Response parameters
In response, 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 |
Example response
{
"account_id": "13fa84f7-6b61-4086-98ed-0a9de19ee15c",
"scope_id": "a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c"
}
Disabling the Kommo account from the channel
If you want the account to no longer receive messages from your channel, you can turn it off.
Before using this method, please read:
To disconnect an account from the chat channel, you need to execute the DELETE request, passing the request for the id of the account to be disabled in the body. In return you will receive 200 OK
Method URL
POST /v2/origin/custom/{unique channel id}/disconnect
Host: amojo.kommo.com
X-Signature:
Content-Type: application / json
Parameters
PARAMETER | TYPE | DESCRIPTION |
---|---|---|
account_id | string | UUID, A unique identifier for the account to work with the online chat service. |
Example
/*
Disconnecting the Kommo account from the online chat channel
*/
// The secret of our channel, for forming the signature
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// ID of our channel
$channel_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0';
// Account ID for online chat service
$account_id = '13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Request body
$body = json_encode([
'account_id' => $account_id
]);
// Form the signature
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://amojo.kommo.com/v2/origin/custom/{$channel_id}/disconnect",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => array(
"Cache-Control: no-cache",
"Content-Type: application/json",
"X-Signature: {$signature}"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Example response
200 OK
Sending a message
Before using this method, please read:
Method URL
POST /v2/origin/custom/{scope id}
Host: amojo.kommo.com
X-Signature:
Content-Type: application / json
Parameters
Parameter | Type | Description |
---|---|---|
event_type | string | The type of the event. Available: new_message |
payload | object | Detail information |
Parameter | Type | Description |
---|---|---|
timestamp require |
int | Time when the message was created, unix |
msgid require |
string | The unique identifier of the message |
conversation_id require |
string | The unique identifier of the correspondence |
sender require |
object | Sender |
message require |
object | Message |
Parameter | Type | Description |
---|---|---|
id require |
string | The unique identifier of the sender |
avatar require |
string | URL to avatar. The link should be accessible to Kommo servers |
name require |
string | Sender’s name |
profile_link | string | An external public link to a user profile, if supported |
profile | object | Additional customer information |
Parameter | Type | Description |
---|---|---|
phone | int | Phone, if there is information it will be added to the social contact profile |
string, Email | Email, if there is information it will be added to the social contact profile |
Parameter | Type | Description |
---|---|---|
type require |
string | The unique identifier of the sender |
text | string | URL to avatar. The link must be available to Kommo servers. Required for type text. |
media | string |
Link to file. Must be available to Kommo servers. Required for types:
|
location | object | Information about the location. Required for location |
contact | object | Information on the contact. Required for contact. |
file_name | string |
The name of the file. Required for types:
|
file_size | int, bytes |
File size. Required for types:
|
Location object description
Parameter | Type | Description |
---|---|---|
lon | float | Longitude |
lat | float | Latitude |
Description of the object contact
Parameter | Type | Description |
---|---|---|
name | string | Name |
phone | string | Telephone |
Example
/*
Connecting the Kommo account to a new channel of online chats
*/
// The secret of our channel, for forming the signature
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// Scope id to post messages to your account
$scope_id = 'a4490ccc-5d7f-11e7-907b-a6006ad3dba0_13fa84f7-6b61-4086-98ed-0a9de19ee15c';
// Request body
$body = json_encode([
'event_type' => 'new_message',
'payload' => [
'timestamp' => time(),
'msgid' => uniqid(),
'conversation_id' => uniqid('c'),
'sender' => [
'id' => 'U1',
'avatar' => 'https://www.kommo.com/version2/images/logo_bill.png',
'name' => 'John',
'profile' => [
'phone' => 79151112233,
'email' => 'email@domain.com',
],
'profile_link' => 'http://example.com',
],
'message' => [
'type' => 'text',
'text' => ''Hello! How much does it cost to develop a website?'
]
]
]);
// Form the signature
$signature = hash_hmac('sha1', $body, $secret);
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "https://amojo.kommo.com/v2/origin/custom/{$scope_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => array(
"cache-control: no-cache",
"content-type: application/json",
"x-signature: {$signature}"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
Webhook
The callback URL that you specified when registering the channel will receive new messages from the Kommo interface.
Each such request contains a JSON object describing the message structure and the X-Signature header containing the signature of the payload data.
Method URL
POST: your webhook url
X-Signature:
Content-Type: application / json
Parameters
Parameter | Type | Description |
---|---|---|
receiver require |
string | id of the recipient |
conversation_id require |
string | The identifier of the correspondence |
type require |
string | The type of the message. Available: text, picture, file |
text | string | The text of the message. Required |
media | string | URL to file. Required for type picture, file |
thumbnail | string | URL in thumbnail. Required for picture type |
file_name | string | The name of the file. Required for type file |
file_size | int | The size of the file in bytes. Required for type file |
Example
/*
Example of processing webhook
*/
// Example of business logic
function save_text_message($to, $chat_id, $text) {
// Save the text message
}
function save_picture_message($to, $chat_id, $fid, $description = NULL) {
// Save the image
}
function save_file_message($to, $chat_id, $fid, $filename, $size, $description = NULL) {
// Save the file
}
function download_file($url) {
// save the file by reference to the disk, return the identifier
return 0;
}
// The secret of our channel, to verify the signature
$secret = 'da39a3ee5e6b4b0d3255bfef95601890afd80709';
// Request data
$body_res = stream_get_contents(STDIN);
if (empty($body_res)) {
throw new RuntimeException('Empty body');
}
// Form the signature
$signature = hash_hmac('sha1', $body_res, $secret);
// Check that this is a POST request
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
throw new RuntimeException('Unsupported request');
}
// Check the signature
if ($body_res !== $_SERVER['HTTP_X_SIGNATURE']) {
throw new RuntimeException('Invalid signature');
}
$message = json_decode($body_res);
if (!$message) {
throw new RuntimeException('Unsupported body');
}
switch ($message['type']) {
case 'text':
save_text_message(
$message['receiver'],
$message['conversation_id'],
$message['text']
);
break;
case 'picture':
$fid = download_file($message['media']);
save_picture_message(
$message['receiver'],
$message['conversation_id'],
$fid,
$message['text']
);
break;
case 'file':
$fid = download_file($message['media']);
save_file_message(
$message['receiver'],
$message['conversation_id'],
$fid,
$message['file_name'],
$message['file_size'],
$message['text']
);
break;
}