Skip to content

GetChatHistory Test#

The method returns the chat message history.

To receive incoming messages you need to enable the Receive webhooks on incoming messages and files setting using the SetSettings method or through the console.

To receive the statuses of sent messages you need to enable the Receive notifications about the statuses of sent messages setting using the SetSettings method or through console

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

To receive messages that were sent and received by your phone before connecting the instance, after saving the settings on the instance, you need to do logout and authorize again.

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

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

Request#

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

POST 
{{apiUrl}}/waInstance{{idInstance}}/getChatHistory/{{apiTokenInstance}}

For apiUrl, 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": "11001234567@c.us",
    "count": 10
}

Response#

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
idMessage string Incoming message Id
timestamp integer Message acceptance time in UNIX format
statusMessage string Outgoing message status. Present only for type = outgoing. Possible variants:
noAccount - no WhatsApp account on phone number
notInGroup - not in this group
pending - is sent
sent - sent
delivered - delivered
read - read/seen/heard
yellowCard - suspension of sending messages due to spam activity. Messages sent after receiving the status are stored in the queue to be sent for 24 hours. To continue running the instance, you need to do a reboot of the instance
sendByApi boolean Is the message sent through API. Present only for type = outgoing
typeMessage string Message type, possible variants:
textMessage - text message
imageMessage - image message
videoMessage - video message
documentMessage - document file message
audioMessage - audio message
stickerMessage - sticker message
reactionMessage - reaction message
locationMessage - location message
contactMessage - contact message
extendedTextMessage - link and preview message
pollMessage - poll message
pollUpdateMessage - poll message update. Present only for type = incoming
quotedMessage - quoted message
chatId string Chat Id, where the message has been received
senderId string Message sender Id. Present only for type = incoming
senderName string Message sender name. Present only for type = incoming
senderContactName string Message sender name according to the contact list of the current account. Present only for type = incoming
isForwarded boolean The flag indicates whether the message is forwarded
forwardingScore integer Number of message forwards
textMessage string Text message, if typeMessage=textMessage/extendedTextMessage
downloadUrl string Link to download a file, if if typeMessage = imageMessage/videoMessage /documentMessage/audioMessage/stickerMessage
caption string File caption, if typeMessage = imageMessage/videoMessage /documentMessage/audioMessage/stickerMessage
fileName string File name, if typeMessage = imageMessage/videoMessage /documentMessage/audioMessage/stickerMessage. The field is filled in correctly only for typeMessage = documentMessage, in other cases the file name is generated automatically
jpegThumbnail string base64-coded image preview, if typeMessage = imageMessage /videoMessage/documentMessage/audioMessage/stickerMessage
mimeType string File type according to the Media Types, if typeMessage = imageMessage /videoMessage/documentMessage/audioMessage/stickerMessage
isAnimated boolean The flag indicates whether the file is animated, if typeMessage = imageMessage/videoMessage/documentMessage/audioMessage/stickerMessage
location object Location structure object, if typeMessage = locationMessage
contact object Contact structure object, if typeMessage = contactMessage
extendedTextMessage object Text message object (advanced), if typeMessage = extendedTextMessage/quotedMessage
extendedTextMessageData object Reaction message data object, if typeMessage = reactionMessage
pollMessageData object Poll data structure object, if typeMessage = pollMessage/pollUpdateMessage
quotedMessage object Quoted message data object, if typeMessage = quotedMessage/reactionMessage

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
isForwarded boolean The flag indicates whether the message is forwarded
forwardingScore integer Number of message forwards

Parameters of contact object:

Parameter Type Description
displayName string Contact display name
vcard string VCard structure (contact visit card)
isForwarded boolean The flag indicates whether the message is forwarded
forwardingScore integer Number of message forwards

Parameters of extendedTextMessage object:

Parameter Type Description
text string Link text
description string Link description
title string Link title
previewType string Link preview type. previewType:None value is deprecated
jpegThumbnail string base64-coded image preview
stanzaId string Quoted message ID. Present only for typeMessage= quotedMessage
participant string Recipient/sender chat ID. Present only for typeMessage= quotedMessage
isForwarded boolean The flag indicates whether the message is forwarded
forwardingScore integer Number of message forwards

Parameters of extendedTextMessageData object:

Parameter Type Description
text string Reaction (emoji) to a message

Parameters of pollMessageData object:

Parameter Type Description
stanzaId string Outgoing poll message id. Present only for typeMessage=pollUpdateMessage
name string Poll text
options array Array of poll options. Present only for typeMessage= pollMessage
votes array Array of poll vote. Present only for typeMessage=pollUpdateMessage
multipleAnswers boolean Flag to allow multiple answers

Parameters of options array:

Parameter Type Description
optionName string Poll choice option text

Parameters of votes array:

Parameter Type Description
optionName string Poll choice option text
optionVoters array Array poll vote account id

Parameters of quotedMessage object:

Parameter Type Description
stanzaId string Quoted message ID
participant string Recipient chat ID
typeMessage string Quoted message type

The remaining fields of the quotedMessage object are filled in depending on the type of the quoted message and are identical to the fields described above

Response body example#

[
    {
        "type": "incoming",
        "idMessage": "9DB14F14A253D33F4A9CD84123456789",
        "timestamp": 1706522263,
        "typeMessage": "textMessage",
        "chatId": "120363153000000000@g.us",
        "textMessage": "Hi",
        "senderId": "70000000012@c.us",
        "senderName": "Rachel",
        "senderContactName": "Rachel 2"
    },
    {
        "type": "outgoing",
        "idMessage": "BAE5143000000000",
        "timestamp": 1706761225,
        "typeMessage": "textMessage",
        "chatId": "70000000012@c.us",
        "textMessage": "Hi",
        "statusMessage": "read",
        "sendByApi": true
    },
    {
        "type": "incoming",
        "idMessage": "EAAE5A5CD000000000",
        "timestamp": 1706601620,
        "typeMessage": "imageMessage",  //"videoMessage"/`documentMessage`/`audioMessage`/`stickerMessage`
        "chatId": "120363153000000000@g.us",
        "downloadUrl": "https://api.green-api.com/waInstance1234/downloadFile/EA1BD1AE042DC4F3609867126309D67C.jpg",
        "caption": "What do you think?",
        "fileName": "03963bac-6020-423c-80df-1aa123456789.jpg",
        "jpegThumbnail": "/9j/4AAQSkZJ/aAAgBAwEBPwCVYw//xAApEAACAx/2kOVh/VKAoAH/leFhX//+AAMA/9k=",
        "mimeType": "image/jpeg",
        "isAnimated": false,
        "isForwarded": true,
        "forwardingScore": 1,
        "senderId": "70000000012@c.us",
        "senderName": "Rachel",
        "senderContactName": "Rachel 2"
    },
    {
        "type": "outgoing",
        "idMessage": "3A1EBA0F23004BD415BB",
        "timestamp": 1706601621,
        "typeMessage": "reactionMessage",
        "chatId": "70000000012@c.us",
        "extendedTextMessageData": {
            "text": "😄"
        },
        "quotedMessage": {
            "stanzaId": "B4D7D8A1A7D887D5580F000000000000",
            "participant": "70000000012@c.us",
        },
        "statusMessage": "read",
        "sendByApi": false
    },
    {
        "type": "outgoing",
        "idMessage": "BAE5870000000000",
        "timestamp": 1706761414,
        "typeMessage": "locationMessage",
        "chatId": "70000000012@c.us",
        "location": {
            "nameLocation": "Cafe",
            "address": "Astana",
            "jpegThumbnail": "/9j/4AAQSkZJRgABAQAASABIAAD/4QBYRX",
            "latitude": 51.1280000000000,
            "longitude": 71.4307620000000,
            "forwardingScore": 0,
            "isForwarded": false
        },
        "statusMessage": "read",
        "sendByApi": true
    },
    {
        "type": "incoming",
        "idMessage": "3AA2C1D83560000000000",
        "timestamp": 1706675513,
        "typeMessage": "contactMessage",
        "chatId": "70000000012@c.us",
        "contact": {
            "displayName": "Anastasia",
            "vcard": "BEGIN:VCARD\nVERSION:3.0\nN:;Anastasia;;;\nFN:Anastasia\nTEL;type=CELL;type=VOICE;waid=70000000013:+7 000 000-00-13\nEND:VCARD",
            "forwardingScore": 0,
            "isForwarded": false
        },
        "senderId": "70000000012@c.us",
        "senderName": "Rachel",
        "senderContactName": "Rachel 2"
    },
    {
        "type": "incoming",
        "idMessage": "3A66D7F0B50000000000",
        "timestamp": 1706675928,
        "typeMessage": "extendedTextMessage",
        "chatId": "70000000012@c.us",
        "textMessage": "Hqhqhhqh\nhttps://greenapi.com",
        "extendedTextMessage": {
            "text": "Hqhqhhqh\nhttps://greenapi.com",
            "description": "GREEN API: WhatsApp API on any language PHP, JavaScript, 1C, Python, Java, C#, VBA etc.",
            "title": "GREEN API: send and receive WhatsApp messages",
            "previewType": "None",
            "jpegThumbnail": "/9j/4AAQSkZJRgABAQAAAQABZ",
            "forwardingScore": 0,
            "isForwarded": false
        },
        "senderId": "70000000012@c.us",
        "senderName": "Rachel",
        "senderContactName": "Rachel 2"
    },
    {
        "type": "outgoing",
        "idMessage": "460D84E00000000000",
        "timestamp": 1706762412,
        "typeMessage": "pollMessage",
        "chatId": "70000000012@c.us",
        "pollMessageData": {
            "name": "Choose your favorite color",
            "options": [
                {
                    "optionName": "Red"
                },
                {
                    "optionName": "Green"
                }
            ],
            "multipleAnswers": true
        },
        "statusMessage": "delivered",
        "sendByApi": true
    },
    {
        "type": "incoming",
        "idMessage": "3A0493ED90000000000000",
        "timestamp": 1706676447,
        "typeMessage": "pollUpdateMessage",
        "chatId": "70000000012@c.us",
        "pollMessageData": {
            "name": "Choose your favorite color",
            "stanzaId": "460D84E00000000000",
            "votes": [
                {
                    "optionName": "Red",
                    "optionVoters": [
                        "70000000012@c.us"
                    ]
                },
                {
                    "optionName": "Green",
                    "optionVoters": []
                }
            ],
            "multipleAnswers": true
        },
        "senderId": "70000000012@c.us",
        "senderName": "Rachel",
        "senderContactName": "Rachel 2"
    },
    {
        "type": "outgoing",
        "idMessage": "B1494991277FD000000000000000000000",
        "timestamp": 1706849516,
        "typeMessage": "quotedMessage",
        "chatId": "70000000012@c.us",
        "extendedTextMessage": {
            "text": "Black",
            "stanzaId": "460D84E00000000000",
            "participant": "70000000012@c.us"
        },
        "quotedMessage": {
            "stanzaId": "460D84E00000000000",
            "participant": "70000000012@c.us",
            "typeMessage": "pollMessage",
            "pollMessageData": {
                "name": "Choose your favorite color",
                "options": [],
                "multipleAnswers": true
            }
        },
        "statusMessage": "delivered",
        "sendByApi": false
    },
    {
        "type": "outgoing",
        "idMessage": "21D6C50B400DBCEC30000000000000",
        "timestamp": 1706852882,
        "typeMessage": "quotedMessage",
        "chatId": "70000000012@c.us",
        "extendedTextMessage": {
            "text": "Cool",
            "stanzaId": "79DC2458992097F00000000000000000",
            "participant": "70000000012@c.us"
        },
        "quotedMessage": {
            "stanzaId": "79DC2458992097F00000000000000000",
            "participant": "70000000012@c.us",
            "typeMessage": "imageMessage", //"videoMessage"/`documentMessage`/`audioMessage`/`stickerMessage`
            "downloadUrl": "",
            "caption": "",
            "fileName": "",
            "jpegThumbnail": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAgq7O/wD/2Q==",
            "mimeType": "image/jpeg",
            "isAnimated": false,
            "isForwarded": false,
            "forwardingScore": 0
        },
        "statusMessage": "read",
        "sendByApi": true
    }
]

GetChatHistory errors#

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

Request examples#

import requests

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

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

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

print(response.text.encode('utf8'))

curl --location '{{apiUrl}}/waInstance{{idInstance}}/getChatHistory/{{apiTokenInstance}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "chatId": "11001234567@c.us",
    "count": 10
}'

var restTemplate = new RestTemplate();
var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/waInstance").append({{idInstance}})
    .append("/getChatHistory/")
    .append({{apiTokenInstance}});

var headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);

var jsonBody = "{\"chatId\": \"11001234567@c.us\",\"count\": 10}";

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

var response = restTemplate.exchange(requestUrl.toString(), HttpMethod.POST, requestEntity, String.class);
System.out.println(response);

var requestUrl = new StringBuilder();
requestUrl
    .append({{apiUrl}})
    .append("/waInstance").append({{idInstance}})
    .append("/getChatHistory/")
    .append({{apiTokenInstance}});

var response = Unirest.post(requestUrl.toString())
    .header("Content-Type", "application/json")
    .body("{\"chatId\": \"11001234567@c.us\",\"count\": 10}")
    .asString();

System.out.println(response);

Sub GetChatHistory()
    Dim url As String
    Dim RequestBody As String
    Dim http As Object
    Dim response As String

    ' The apiUrl, idInstance and apiTokenInstance values are available in console, double brackets must be removed
    url = "{{apiUrl}}/waInstance{{idInstance}}/getChatHistory/{{apiTokenInstance}}"

    ' chatId - personal or group chat identifier whose message history you want to receive, count - number of messages to receive, default value 100
    RequestBody = "{""chatId"":""71234567890@c.us"",""count"":10}"

    Set http = CreateObject("MSXML2.XMLHTTP")

    With http
        .Open "POST", url, False
        .setRequestHeader "Content-Type", "application/json"
        .send RequestBody
    End With

    response = http.responseText

    Debug.Print response

    ' Outputting the answer to the desired cell
    Range("A1").Value = response

    Set http = Nothing
End Sub