Getting chat history




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 = "" . $path;

$checkSum = md5('');

$str = implode("\n", [

$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 '' \
--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": "",
                "phone": "+18305803077"
            "message": {
                "id": "c57dae8e-de79-468b-a923-9a7c88c733d7",
                "type": "picture",
                "text": "Hello from Kommo",
                "media": "",
                "thumbnail": "",
                "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": "",
                "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.