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}.
Follow the steps here to generate an API 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.

Example

delivered

recipientstringOptional

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

Maximum Length :30Copied!

fromstringOptional

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

Minimum Length :8Copied!

Maximum Length :20Copied!

client_referencestringOptional

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

Maximum Length :100Copied!

template_keystringOptional

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

Maximum Length :50Copied!

request_idstringOptional

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.

Example

2026-09-22T00:00:00+05:30

date_todate-timeOptional

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

Example

2026-09-22T23:59:59+05:30

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

Example

countinteger

Number of entries in this page.

Example

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.

Example

+14155550142

tostring

Recipient phone number, with country code.

Example

+919876543210

statusstring

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

Example

delivered

process_statestring

Processing state of the request.

Example

processed

remote_ipstring

IP address the send request was made from.

Example

10.61.232.23

is_batch_requestboolean

request_timestring

When the send request was received (ISO 8601).

time_takeninteger

Processing time in milliseconds.

statusstring

Example

success

- 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

Example

TM_3301

messagestring

Example

Bad Syntax

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).

Example

SERR_110

messagestring

Example

Parameter less than min occurrance

targetstring

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

Example

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