Getting chat history

Method

GET https://amojo.kommo.com/v2/origin/custom/{scope_id}/chats/{conversation_id}/history

Description

The method allows you to get a list of messages in a specific chat.

conversation_id can be obtained either when creating a chat via the chat creation method, or from the message webhook.

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.

GET Parameters

Parameter	Data type	Description
offset	int	Offset of the message selection (how many records from the beginning of the selection we skip)
limit	int	Number of returned entities per query (Maximum – 50)

Example in PHP

$secret = 'fb50586ff7b68cd831fe0ef356345903f644c0d2';
$method = 'GET';
$contentType = 'application/json';
$date = date(DateTimeInterface::RFC2822);// in format "Tue, 13 Dec 2022 11:00:00 +0000"
$path = '/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d76a21_52fd2a28-d2eb-4bd8-b862-a67934927b38/chats/30477717-9f3c-4d3f-8101-60327e14dc48/history';
$getParams = '?limit=50&offset=0';
$url = "https://amojo.kommo.com" . $path;

$checkSum = md5('');

$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 . $getParams . PHP_EOL;
foreach ($curlHeaders as $header) {
    echo $header . PHP_EOL;
}

Example of the cURL request

curl --location --request GET 'https://amojo.kommo.com/v2/origin/custom/f62a0162-46a7-430e-b06c-0ef798d76a21_52fd2a28-d2eb-4bd8-b862-a67934927b38/chats/30477717-9f3c-4d3f-8101-60327e14dc48/history?limit=50&offset=0' \
--header 'Date: Tue, 13 Dec 2022 11:00:00 +0000' \
--header 'Content-Type: application/json' \
--header 'Content-MD5: d41d8cd98f00b204e9800998ecf8427e' \
--header 'X-Signature: 2a2593df86235c44943a40ce35409d18bda5778c'

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 Pesponse Codes

Response code	Condition
200	Request completed successfully
204	Chat does not exist or there are no messages
403	Request signature is incorrect
400	Incorrect data transmitted. Details are available in the response body

Response example

{
    "messages": [
        {
            "timestamp": 1670930693,
            "msec_timestamp": 1670930693280,
            "sender": {
                "id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5b89",
                "name": "Lama Saqqour",
                "avatar": ""
            },
            "receiver": {
                "id": "9c2ccde3-a3ab-4695-832c-919dbfc598ea",
                "client_id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a89",
                "name": "Adam",
                "avatar": "https://www.w3schools.com/w3images/avatar2.png",
                "phone": "+18305803077"
            },
            "message": {
                "id": "c57dae8e-de79-468b-a923-9a7c88c733d7",
                "type": "picture",
                "text": "Hello from Kommo",
                "media": "https://amojo.kommo.com/attachments/52fd2a28-d2eb-4bd8-b862-a67934927b38/14723c64-c40d-4efc-9f78-9625adac414c/zDCRN_logo-min.jpg",
                "thumbnail": "https://amojo.kommo.com/attachments/52fd2a28-d2eb-4bd8-b862-a67934927b38/14723c64-c40d-4efc-9f78-9625adac414c/zDCRN_logo-min_320x200.jpg",
                "file_name": "logo-min.png",
                "file_size": 27107
            }
        },
        {
            "timestamp": 1670832082,
            "msec_timestamp": 1670832082680,
            "sender": {
                "id": "9c2ccde3-a3ab-4695-832c-919dbfc598ea",
                "client_id": "b0bc49f0-ec21-4463-965f-1fe1d4cd5a89",
                "name": "Adam",
                "avatar": "https://www.w3schools.com/w3images/avatar2.png",
                "phone": "+18305803077"
            },
            "message": {
                "id": "60595445-a8b2-4a97-b7a9-7101ec25a74f",
                "client_id": "f1065e3b-0ec6-427b-b97c-883329acbaaa",
                "type": "text",
                "text": "Hello Kommo! Have a productive week. ",
                "media": "",
                "thumbnail": "",
                "file_name": "",
                "file_size": 0
            }
        }
    ]
}

Response parameters

Parameter	Data type	Description
timestamp	int	Timestamp when the message was sent
msec_timestamp	int	Timestamp when the message was sent in milliseconds
sender	object	Message sender. Description about the elements of the sender object.
receiver	object	Message receiver. Description about the elements of the receiver object.
message	object	Message body. Description about the elements of the message object.

Sender and receiver entities

Parameter	Data type	Description
id	string	Recipient ID /sender ID of the message in the Chats API
name	string	Recipient name /sender name of the message in the Chats API
client_id	string	Message recipient ID /sender ID on the integration side
avatar	string	Link to the recipient’s/sender’s avatar, if it was passed during creation
phone	string	Recipient’s/sender’s phone number, if it was given during creation
email	string	Email of the recipient/sender, if it was sent during creation

Message entity

Parameter	Data type	Description
id	string	Chat ID on the Chat API side
client_id	string	Chat ID on the integration side
type	string	Message type
text	string	Message text
media	string	Link to the media file
thumbnail	string	Link to media thumbnail
file_name	string	The name of the file from the “media” field.
file_size	string	The size of the file from the “media” field
media_group_id	string	ID of the media group. If the user sends a single message with multiple attachments, we will split the message into several, but the media files will be combined into one group.

When developing chat integrations you will need to update the delivery status of a message.