Retrieve Campaign Audience and Delivery Status Data

Use this endpoint to retrieve the full list of recipients for a specific campaign, along with their delivery status. You can filter results by delivery category (e.g., READ, DELIVERED, FAILED) and paginate through large audiences using cursor-based pagination.

Endpoint

GET https://connect.api-wa.co/project-apis/v1/project/{project_id}/campaign/audience/{campaign_id}

Authentication

X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD

Path Parameters

string

required

Your Convo project ID.

string

required

The unique ID of the campaign whose audience you want to retrieve.

Query Parameters

string

Number of results to return per page. Defaults to 20. Maximum is 1000.

string

Sort order for results. Accepts "asc" (ascending) or "desc" (descending). Defaults to "asc".

string

Cursor for fetching the next page of results. Use the value from response.paging.cursors.after.

string

Cursor for fetching the previous page of results. Use the value from response.paging.cursors.before.

string

Filter recipients by their message delivery status. Accepted values:

SENT — Message was sent
DELIVERED — Message was delivered to the device
READ — Message was opened by the recipient
FAILED — Message failed to deliver
REPLIED — Recipient replied to the campaign
CLICKED — Recipient clicked a button or link in the message

string

Comma-separated list of field names to include in the response. Omit to return all fields.

string

ISO 8601 date-time string. Filters audience records updated on or after this date.

string

ISO 8601 date-time string. Filters audience records updated on or before this date.

Request Example

Fetch the first 100 recipients who have read the campaign message:

curl "https://connect.api-wa.co/project-apis/v1/project/YOUR_PROJECT_ID/campaign/audience/64b3e1ac7f2c0a001d8e9f34?category=READ&limit=100" \
  -H "X-API-WA-Project-API-Pwd: YOUR_API_PASSWORD"

Response

integer

The total number of recipients matching the query (across all pages).

array

Array of recipient objects. Each object contains:

Show Recipient Object

string

Unique internal ID for this audience record.

string

The recipient’s WhatsApp phone number in international format (e.g., "919498526285").

string

ISO 8601 timestamp of when the message was sent to this recipient.

string

Display name of the recipient contact.

string

ISO 8601 timestamp of when the message was delivered. Present only if delivered.

string

ISO 8601 timestamp of when the message was read. Present only if read.

object

Pagination metadata for navigating through large result sets.

Show Paging Object

string

Pass this value as the after query parameter to fetch the next page of results.

string

Pass this value as the before query parameter to fetch the previous page of results.

Example Response

{
  "total": 3,
  "data": [
    {
      "_id": "629f8041b45cc338a0a082bc",
      "userNumber": "919498526285",
      "sentAt": "2024-01-07T16:43:41.331Z",
      "userName": "Priya"
    },
    {
      "_id": "629f8041b45cc338a0a08130",
      "userNumber": "919149327854",
      "sentAt": "2024-01-07T16:43:41.332Z",
      "userName": "Mohit"
    }
  ],
  "paging": {
    "cursors": {
      "after": "NjI5ZjgwNDJiNDVjYzMzOGEwYTA4NDFm...",
      "before": "NjI5ZjgwNDFiNDVjYzMzOGEwYTA4MmJj..."
    }
  }
}

Cursor Pagination

This endpoint uses cursor-based pagination to efficiently iterate through large audiences.

Make an initial request without after or before to get the first page.
If there are more results, the response includes a paging.cursors.after value.
Pass that value as the after query parameter in your next request to retrieve the following page.
Repeat until paging.cursors.after is no longer present in the response, indicating you have reached the last page.

Use before to navigate backwards through pages.

Overview

Business & Project

Messages

Contacts

Templates

Campaigns

Webhooks

Catalogue

Media

Retrieve Campaign Audience and Delivery Status Data

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Example Response

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Request Example

​Response

​Example Response

​Cursor Pagination

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Example Response

Cursor Pagination