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


Payload object description

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


Sender object description

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


Description of the profile

Parameter Type Description
phone int Phone, if there is information it will be added to the social contact profile
email string, Email Email, if there is information it will be added to the social contact profile


Object description message

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:

  • picture,
  • video,
  • file,
  • sticker
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:

  • picture,
  • video,
  • file,
file_size int, bytes

File size. Required for types:

  • picture,
  • video,
  • file,

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;
}