Chats API methods

In this section we will describe all available methods for working with Chats API.

Table of Contents

General requirements

All Chats API requests should be addressed to the amojo.amocrm.ru or amojo.amocrm.com domains depending on the domain the account is located on.

Authorization

Authorization in Chats API is different from the main amoCRM API.
To be authorized, every request should contain the following headers.

  • Date
  • Content-Type
  • Content-MD5
  • X-Signature

Date
Date and time of the request. The signature will be valid for 15 minutes from the request date

Content-Type
Only application/json is supported at the moment

Content-MD5
The md5 hash should be calculated for the request body and specified in the header in lower case. It’s important to note that the request body is calculated as a byte stream without taking into account the end of the json layout, “\n”, or spaces.
For GET requests, the md5 hash should also be calculated even if the request body is empty (will result in the md5 hash off a null string)

X-Signature
First, we form the string from the method title (GET/POST) in upper case and headers values (as specified in headers) imploded via the “\n” symbol. Headers values should be listed in the specific order. If the header is absent, a null string is specified instead.
Then, we add the request path without domain and protocol.

The resulting string is processed via HMAC-SHA1 using the channel secret as a secret key.
The resulting hash is added to the X-Signature header in lower case.

Example:

<?php

$secret = '5a44c5dff55f3c15a4cce8d7c4cc27e207c7e189';
$method = 'POST';
$contentType = 'application/json';
$date = 'Thu, 29 Oct 2020 11:59:55 +0000';
$path = '/v2/origin/custom/f90ba33d-c9d9-44da-b76c-c349b0ecbe41/connect';

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


$requestBody = '{"account_id":"af9945ff-1490-4cad-807d-945c15d88bec","title":"ScopeTitle","hook_api_version":"v2"}';
$checkSum = md5($requestBody);

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

$signature = hash_hmac('sha1', $str, $secret);

$headers = [
    "Date" => $date,
    "Content-Type" => $contentType,
];
$headers['Content-MD5'] = strtolower($checkSum);
$headers['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;

$curl = curl_init();
curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => $method,
    CURLOPT_POSTFIELDS => $requestBody,
    CURLOPT_HTTPHEADER => $curlHeaders,
]);

$response = curl_exec($curl);
$err = curl_error($curl);
$info = curl_getinfo($curl);
curl_close($curl);
if ($err) {
    $result = "cURL Error #:" . $err;
} else {
    echo "Status: " . $info['http_code'] . PHP_EOL;
    echo $response . PHP_EOL;
}

Note for the existing integrations:
Before, the request signature was calculating differently not allowing to authorize requests without body. The old-style signatures continue to be valid for existing integrations and method that used them.
New methods published in this section only support the new signature format described above. We advise integrators to update the signature they are using at the moment for the existing integrations.

Connecting the chat channel to the account

Method

POST /v2/origin/custom/{channel.id}/connect

Description

After the account is connected to the chat channel, you can start working with messages and receive webhooks for outgoing messages. The chat channel should be connected after every installation of the integration because it disconnects automatically when the integration is uninstalled.

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

All fields are mandatory

Parameter Data type Description
account_id string amojo_id of the account
hook_api_version string The version of the webhook that you receive when an outgoing message is sent. The webhook URL should be specified in the chat channel settings
title string Displayed channel name

An example of the request

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "title": "ChatIntegration",
  "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.

Response code Case
200 Channel connected successfully
404 Channel does not exist
403 Incorrect request signature
400 Invalid data given. Details are available in the request response

Response parameters

Method will return the passed request fields and the scope_id required for working with messages

Response example

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "scope_id": "f90ba33d-c9d9-44da-b76c-c349b0ecbe41_af9945ff-1490-4cad-807d-945c15d88bec",
  "title": "Title",
  "hook_api_version": "v2"
}
        
    

Disconnecting the chat channel from the account

Method

DELETE /v2/origin/custom/{channel.id}/disconnect

Description

After the channel is disconnected, you will stop receiving webhooks for outgoing messages. The “initiate conversation” option will also be disabled in the lead card (upon the expiration of the front-end cache)

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

All fields are mandatory

Parameter Data type Description
account_id string amojo_id of the account

An example of the request

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec"
}
        
    

HTTP response codes.

Response code Case
200 Channel disconnected successfully
404 Channel does not exist
403 Incorrect request signature
400 Invalid data given. Details are available in the request response

Response parameters

Method does not return a body

Creating a new chat

Method

POST /v2/origin/custom/{scope_id}/chats

Description

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

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

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

Parameter Data type Description
conversation_id string Chat ID on the integration side
user[id] string Chat participant ID on the integration side, the field is mandatory
user[ref_id] string Chat participant ID on the amoCRM side, the field is optional.
user[name] string Chat participant name, the field is mandatory
user[avatar] string Url to the chat participant avatar, the field is not mandatory. Url should be available for download
user[profile][phone] string The field is not mandatory
user[profile][email] string The field is not mandatory
profile_link string Url to the chat participant profile, the field is not mandatory

An example of the request

        
{
    "conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
    "user": {
        "id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
        "avatar": "https:/example.com/users/avatar.png",
        "name": "Example Client",
        "profile": {
            "phone": "14151112233",
            "email": "example.client@example.com"
        },
        "profile_link": "http://example.com/profile/example.client"
    }
}

        
    

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 parameters

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

Response example

        
{
  "id": "6cbab3d5-c4c1-46ff-b710-ad59ad10805f",
  "user": {
    "id": "86a0caef-41ec-49ac-814b-b27da2cea267",
    "client_id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
    "name": "Example Client",
    "avatar": "https:/example.com/users/avatar.png",
    "phone": "14151112233",
    "email": "example.client@example.com"
  }
}
        
    

Sending or imporing messages

Method

POST /v2/origin/custom/{scope_id}

Description

This method allows to pass the client’s message into the amoCRM account, in that case, the recipient specification can be skipped. Message can also be imported without the notification if silent: true parameter is passed.
It is possible to import a message from the amoCRM manager to the client. For such messages, it’s mandatory to specify the recipient, and the “silent” flag will always have the value “true”.
Messages imported via this method do not trigger a webhook.

When adding several messages in a row, the “silent” flag can be set as “true” for all messages but last and “false” for the last one to notify the amoCRM user only once.

Limitations

A correct request signature in the X-Signature header is required

Request header

Content-Type: application/json

Request parameters

Method creates a message and, if necessary, a chat for the passed msgid and conversation_id. The structure of the receiver and sender fields is identical.
The sender field is mandatory in any case. If the amoCRM user is specified as “sender”, the “receiver” field has to be specified. The sender[id] field is not required in that case.
The message can be addressed from the client to “all” (without the “receiver” field) or from the amoCRM user to the client.

Parameter Data type Description
payload[account_id] string amojo_id of the account
payload[timestamp] int Message timestamp in the format of Unix Timestamp
payload[conversation_id] string Chat ID on the integration side
payload[silent] bool Defines whether the message will trigger a notification in the amoCRM account
receiver[id] string Chat participant ID on the integration side, the field is mandatory
receiver[ref_id] string Chat participant ID on the amoCRM side, the field is optional.
receiver[name] string Chat participant name, the field is mandatory
receiver[avatar] string Url to the chat participant avatar, the field is not mandatory. Url should be available for download
receiver[profile][phone] string The field is not mandatory
receiver[profile][email] string The field is not mandatory
profile_link string Url to the chat participant profile, the field is not mandatory
payload[sender][ref_id] string amojo_id of amoCRM user, is not a mandatory field
sender[id] string Chat participant ID on the integration side, the field is mandatory
sender[ref_id] string Chat participant ID on the amoCRM side, the field is optional.
sender[name] string Chat participant name, the field is mandatory
sender[avatar] string Url to the chat participant avatar, the field is not mandatory. Url should be available for download
sender[profile][phone] string The field is not mandatory
sender[profile][email] string The field is not mandatory
profile_link string Url to the chat participant profile, the field is not mandatory
message[msgid] string Chat message ID on the integration side
message[type] string Message type, one of the following: text, file, video, picture, voice, audio, sticker
message[text] string The field is mandatory for the “text” type, can be empty for other types
message[media] string Url to the file, video, picture, voice, audio, or sticker. Url should be available for download
message[file_name] string The name of the file from the “media” field url, the field is optional. Ignored for the “voice” type
message[file_size] int The size of the file from the “media” field, the field is optional
message[contact][name] string Only for the contact, the field is mandatory. Contact name
message[contact][phone] string Only for the contact, the field is mandatory. Contact phone
message[location][lat] float Only for the location, the field is mandatory. Latitude
message[location][lon] float Only for the location, the field is mandatory. Longtitude

An example of the request

        
{
  "account_id": "af9945ff-1490-4cad-807d-945c15d88bec",
  "event_type": "new_message",
  "payload": {
    "timestamp": 1596470952,
    "msgid": "skm-5f2836a8ca468",
    "conversation_id": "skc-8e3e7640-49af-4448-a2c6-d5a421f7f217",
    "sender": {
      "ref_id": "d8d9f9c4-9611-4794-a136-a253a13e1bb5",
      "name": "Manager"
    },
    "receiver": {
      "id": "sk-1376265f-86df-4c49-a0c3-a4816df41af9",
      "avatar": "https:/example.com/users/avatar.png",
      "name": "Example Client",
      "profile": {
          "phone": "14151112233",
          "email": "example.client@example.com"
      },
      "profile_link": "http://example.com/profile/example.client"
    }
    "message": {
      "type": "text",
      "text": "Do you need any assistance?"
    },
    "silent": true
  }
}

        
    

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 Message is accepted for processing
403 Incorrect request signature
400 Invalid data given. Details are available in the request response

Response parameters

Method returns the amojo_id of the message that will appear in the chat feed when processed

Response example

        
{
  "new_message": {
    "msgid": "1bf6a765-ec6f-4680-8cd5-6f2d31f78ebc"
  }
}