Skip to content


The method returns the chat message history.

To obtain the full chat message history:

  1. Receive messages sent from the phone by enabling the Receive webhooks on messages sent from phone setting using the SetSettings method or through the personal account. Messages sent via the API are automatically recorded in the log.

  2. Receive incoming messages by enabling the Receive webhooks on incoming messages and files setting using the SetSettings method or through the personal account.

Messages sent and received before enabling these settings will not be included in the log.

It may take up to 5 minutes for the settings to take effect.

The appearance of messages in the log may take up to 2 minutes. Log methods should only be used for retrieving chat history. For quicker message retrieval, use the notification system.

To receive incoming messages from the phone's history, you need to enable the instance setting Receive webhooks on incoming messages and files using the SetSettings method or through the personal account and scan the QR code; the history will then appear in the logs.

The GetChatHistory method only returns the history that WhatsApp provides to the system.


To get chat history, you have to execute a request at:


For idInstance and apiTokenInstance request parameters, please refer to Before you start section.

Request parameters#

Parameter Type Mandatory Description
chatId string Yes Personal or chat Id the message history of which you need to get
count integer No The number of messages to get. The default is 100

Request body example#

10 last messages request:

    "chatId": "",
    "count": 10


The response contains a list of all received and sent messages in the chat. Message time stamp descending-order sort.

Response parameters#

Array of objects with parameters:

Parameter Type Description
type string Message type: outgoing - outgoing message; incoming - incoming message
timestamp integer Time when the message has been sent in UNIX format
idMessage string Message Id
statusMessage string Outgoing message status. Present only for type = outgoing. Possible variants:
pending - is sent
sent - sent
delivered - delivered
read - read/seen/heard
typeMessage string Message type, possible variants:
textMessage - text message
imageMessage - image message
videoMessage - video message
documentMessage - document file message
audioMessage - audio message
locationMessage - сообщение геолокации
contactMessage - contact message
extendedTextMessage - link and preview message
chatId string Chat Id
senderId string Incoming message sender Id. Present only for type = incoming
senderName string Incoming message sender name. Present only for type = incoming
textMessage string Message text, if typeMessage=textMessage
downloadUrl string Link to download a file, if typeMessage = imageMessage/videoMessage/documentMessage/audioMessage
caption string File caption, if typeMessage = imageMessage/videoMessage/documentMessage
location object Location structure object, if typeMessage=locationMessage
contact object Contact structure object, if typeMessage=contactMessage
extendedTextMessage object Link data structure object, if typeMessage=extendedTextMessage

Parameters of location object:

Parameter Type Description
nameLocation string Location name
address string Location address
latitude double Location latitude
longitude double Location longitude
jpegThumbnail string base64-coded image preview

Parameters of contact object:

Parameter Type Description
displayName string Contact display name
vcard string VCard structure (contact visit card)

Parameters of extendedTextMessage object:

Parameter Type Description
text string Link text
description string Link description
title string Link title
previewType string Link preview type
jpegThumbnail string base64-coded image preview

Response body example#

        "type": "incoming",
        "timestamp": 1603964449,
        "idMessage": "3AADDD555CB0822C0539",
        "typeMessage": "textMessage",
        "chatId": "",
        "senderId": "",
        "senderName": "Andrew Sh",
        "textMessage": "I use Green-API to get this message from you!"
        "type": "outgoing",
        "timestamp": 1603964445,
        "idMessage": "3EB08816FEBCCC3FACD2",
        "statusMessage": "read",
        "typeMessage": "textMessage",
        "chatId": "",
        "textMessage": "I use Green-API to send this message to you!"
        "type": "incoming",
        "timestamp": 1603964444,
        "idMessage": "3AA45F9F285C5249CDFC",
        "typeMessage": "imageMessage",
        "chatId": "",
        "senderId": "",
        "senderName": "Andrew Sh",
        "downloadUrl": "",
        "caption": "Green-API Logo"

GetChatHistory errors#

For a list of errors common to all methods, refer to Common errors section

Request examples#

import requests

url = "{{idInstance}}/getChatHistory/{{apiTokenInstance}}"

payload = "{\r\n\t\"chatId\": \"\",\r\n\t\"count\": 100\r\n}"
headers = {
  'Content-Type': 'application/json'

response = requests.request("POST", url, headers=headers, data = payload)

curl --location '{{idInstance}}/getChatHistory/{{apiTokenInstance}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "chatId": "",
    "count": 10
var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();

var headers = new HttpHeaders();

var jsonBody = "{\"chatId\": \"\",\"count\": 10}";

var requestEntity = new HttpEntity<>(jsonBody, headers);

var response =, HttpMethod.POST, requestEntity, String.class);
var requestUrl = new StringBuilder();

var response =
    .header("Content-Type", "application/json")
    .body("{\"chatId\": \"\",\"count\": 10}")