Get WhatsApp logs

Returns the agent's WhatsApp message logs, newest first, with pagination and filtering by delivery attributes (status, recipient, sender number) and request attributes (client reference, template, request id, date range).
Requires an API token with the WhatsApp scope. Rate limited to 40 requests per minute.

Endpoint

get /whatsapp/logs

Copy full URL

Request URL

https://cpaas.zoho.com/v1.1/whatsapp/logs Copied!

Request Parameters

- Request Headers

ApiKeyAuthAPI Key

API key of an agent. Send the header as Authorization: Zoho-enczapikey {apiKey}. The agent and account are derived from the key.

- Query Parameters

offsetintegerOptional

Zero-based offset for pagination.

Default Value :0Copied!

limitintegerOptional

Maximum number of log entries to return.

Default Value :10Copied!

statusstringOptional

Returns the WhatsApp message logs based on the provided message status. Common values: delivered, read, sent, undelivered, failed, processed, process_failed.

recipientstring(length <= 30)Optional

Returns the WhatsApp message logs based on the provided recipient phone number (with country code).

Maximum Length :30Copied!

fromstring(length: 8-20)Optional

Returns the WhatsApp message logs based on the provided sender phone number (with country code).

Minimum Length :8Copied!

Maximum Length :20Copied!

client_referencestring(length <= 100)Optional

Returns the WhatsApp message logs based on the provided client reference supplied at send time.

Maximum Length :100Copied!

template_keystring(length <= 50)Optional

Returns the WhatsApp message logs based on the provided WhatsApp template key.

Maximum Length :50Copied!

request_idstring(length <= 200)Optional

Returns the WhatsApp message logs based on the provided request id returned by the send WhatsApp message API.

Maximum Length :200Copied!

date_fromdate-timeOptional

Start of the date range - an ISO 8601 date-time with UTC offset.

date_todate-timeOptional

End of the date range - an ISO 8601 date-time with UTC offset.

Sample Request

Curl

Java

Python

Deluge

Copied!

curl --request GET \
  --url 'https://cpaas.zoho.com/v1.1/whatsapp/logs?offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&status=delivered&recipient=SOME_STRING_VALUE&from=SOME_STRING_VALUE&client_reference=SOME_STRING_VALUE&template_key=SOME_STRING_VALUE&request_id=SOME_STRING_VALUE&date_from=2026-09-22T00:00:00+05:30&date_to=2026-09-22T23:59:59+05:30' \
  --header 'Authorization: REPLACE_KEY_VALUE'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.io.IOException;
import java.net.http.HttpTimeoutException;

public class Main {
  public static void main(String[] args) {

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://cpaas.zoho.com/v1.1/whatsapp/logs?offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&status=delivered&recipient=SOME_STRING_VALUE&from=SOME_STRING_VALUE&client_reference=SOME_STRING_VALUE&template_key=SOME_STRING_VALUE&request_id=SOME_STRING_VALUE&date_from=2026-09-22T00:00:00+05:30&date_to=2026-09-22T23:59:59+05:30"))
        .header("Authorization", "REPLACE_KEY_VALUE")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("cpaas.zoho.com")

headers = { 'Authorization': "REPLACE_KEY_VALUE" }

conn.request("GET", "/v1.1/whatsapp/logs?offset=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&status=delivered&recipient=SOME_STRING_VALUE&from=SOME_STRING_VALUE&client_reference=SOME_STRING_VALUE&template_key=SOME_STRING_VALUE&request_id=SOME_STRING_VALUE&date_from=2026-09-22T00:00:00+05:30&date_to=2026-09-22T23:59:59+05:30", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    parameters = "offset=value" + "&" + "limit=value" + "&" + "status=value" + "&" + "recipient=value" + "&" + "from=value" + "&" + "client_reference=value" + "&" + "template_key=value" + "&" + "request_id=value" + "&" + "date_from=value" + "&" + "date_to=value";

    headersMap = Map();
    headersMap.put("Authorization", "REPLACE_KEY_VALUE");
    headersMap.put("Accept", "application/json");

    response = invokeUrl
    [
        url: "https://cpaas.zoho.com/v1.1/whatsapp/logs" + "?" + parameters
        type: GET
        headers: headersMap
        connection: connection_name
    ]

    info response;

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Response containing a page of WhatsApp message logs.

Show Sub-Attributes

metadataJSON Object

Show Sub-Attributes

offsetinteger

countinteger

Number of entries in this page.

dataJSON Array

Show Sub-Attributes

object

A WhatsApp message log entry.

message_iduuid

Unique identifier of the message.

request_idstring

Identifier of the send request.

client_referencestring

Client reference supplied at send time, if any.

template_keyuuid

Key of the WhatsApp template used.

agent_idstring

Identifier of the sending agent.

channel_idstring

Identifier of the WhatsApp channel the message was sent through.

channel_namestring

Name of the WhatsApp channel.

waba_idstring

WhatsApp Business Account id of the channel.

fromstring

Sender phone number, with country code.

tostring

Recipient phone number, with country code.

statusstring

Message status (e.g. delivered, read, sent, undelivered, failed, process_failed).

process_statestring

Processing state of the request.

remote_ipstring

IP address the send request was made from.

is_batch_requestboolean

request_timestring

When the send request was received (ISO 8601).

time_takeninteger

Processing time in milliseconds.

statusstring

- HTTP code 401

Response Body - application/json

JSON Object

Error response wrapper. The top-level code identifies the error class: TM_3201 mandatory field missing (400), TM_3301 bad syntax (400), TM_4001 access denied (401), TM_3601 request denied (403).

Show Sub-Attributes

errorJSON Object

Show Sub-Attributes

codestring

messagestring

detailsJSON Array

Show Sub-Attributes

object

A single validation or denial detail inside the error envelope.

codestring

Detail-level error code, e.g. SERR_110 (required parameter missing), GE_102 (mandatory field missing), WA_103 (invalid template), WSE_107 (sender number belongs to a different agent), SERR_157 (invalid API token).

messagestring

targetstring

The field the detail refers to, when applicable (e.g. from, to, template_key | template_alias).

target_value

The offending value, when applicable.

request_idstring

Identifier of the failed request, when available.

Sample Response: HTTP 200

Copied!

  {
    "metadata": {
      "offset": 0,
      "count": 1
    },
    "data": [
      {
        "message_id": "37aa68e0-b680-11f1-91b5-d2a30e0412c2",
        "request_id": "37aa68e0-b680-11f1-91b5-d2a30e0412c2",
        "template_key": "d0109d00-b191-11f1-95b1-aaa8828ce996",
        "agent_id": "28bc4428feb773",
        "channel_id": "21144000000003001",
        "channel_name": "Example WhatsApp Channel",
        "waba_id": "1102793358413684",
        "from": "+14155550142",
        "to": "+919876543210",
        "status": "delivered",
        "process_state": "processed",
        "is_batch_request": false,
        "request_time": "2026-09-22T17:52:03+05:30",
        "time_taken": 817
      }
    ],
    "status": "success"
  }

▼ Show full

Sample Response: HTTP 401

Copied!

  {
    "error": {
      "code": "TM_4001",
      "details": [
        {
          "code": "SERR_157",
          "message": "Invalid API Token found"
        }
      ],
      "message": "Access Denied"
    }
  }

▼ Show full