Whats91
Developers

List conversation report records for the resolved WhatsApp sender.

List Conversations

Summary

Use Conversations APIs to fetch conversation reports, summaries, by-mobile threads, conversation details, and paginated messages.

Prerequisites

  • Bearer token authentication
  • Conversation filters such as sender, mobile number, date range, status, or labels

Related documentation

SummaryBy MobileReportsSamples

Endpoint: GET /api/v2/reports/conversations. Conversation report APIs are read-only JSON endpoints under https://graph.whats91.com/api/v2/reports/conversations. Do not use /v2/reports/conversations; that twin path is intentionally not exposed for reporting APIs.

Use Authorization: Bearer w91_live_xxxxxxxxxxxxxxxxx. GET endpoints also accept authToken, auth_token, or token as query parameters for compatibility.

Conversation data is always scoped to the authenticated customer. Public APIs do not accept a userId filter.

GET/api/v2/reports/conversations
ParameterTypeRequiredDescription
AuthorizationheaderRequiredBearer w91_live_xxxxxxxxxxxxxxxxx.
senderIdstringOptionalWhatsApp sender phone number. Optional when token scope/default sender resolves it.
pagenumberOptionalPositive integer. Default 1.
limitnumberOptionalPositive integer. Default 50, max 200.
dateFromstringOptionalYYYY-MM-DD. Applies to conversation activity time.
dateTostringOptionalYYYY-MM-DD. Applies to conversation activity time.
searchstringOptionalMatches contact name, phone, or last message.
statusstringOptionalactive, closed, blocked, or all.
archivedbooleanOptionaltrue or false.
unreadOnlybooleanOptionaltrue or false.
mobileNumberstringOptionalRecipient phone filter.
contactPhonestringOptionalRecipient phone filter alias.
lastDirectionstringOptionalinbound or outbound.
labelUidstringOptionalFilter conversations with an assigned label.
includeLabelUidsstringOptionalComma-separated labels to include.
excludeLabelUidsstringOptionalComma-separated labels to exclude.
labelMatchModestringOptionalANY or ALL. Default ANY.
sortBystringOptionallast_message_at, updated_at, created_at, total_messages, or unread_count.
sortOrderstringOptionalASC or DESC.
List unread conversations
curl "https://graph.whats91.com/api/v2/reports/conversations?senderId=919999999999&unreadOnly=true&page=1&limit=50" \
  -H "Authorization: Bearer w91_live_xxx"
List response
{
  "success": true,
  "message": "Conversation reports retrieved",
  "data": {
    "senderId": "919999999999",
    "phoneNumberId": "1234567890",
    "conversations": [
      {
        "conversationId": 194977,
        "contactPhone": "919343841961",
        "contactName": "Prashant Tayal",
        "senderPhoneNumber": "919999999999",
        "phoneNumberId": "1234567890",
        "lastMessageId": "wamid.xxxxx",
        "lastMessageContent": "hi",
        "lastMessageType": "text",
        "lastMessageAt": "2026-06-05T06:08:48.000Z",
        "lastMessageDirection": "inbound",
        "unreadCount": 1,
        "totalMessages": 2,
        "isArchived": false,
        "isPinned": false,
        "isMuted": false,
        "isBlocked": false,
        "status": "active",
        "labels": [
          { "uid": "lbl_support", "labelName": "Support" }
        ],
        "createdAt": "2026-06-05T06:08:48.000Z",
        "updatedAt": "2026-06-05T06:08:50.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 50,
      "total": 1,
      "totalPages": 1,
      "count": 1,
      "hasMore": false
    }
  },
  "metadata": {
    "apiVersion": "v2",
    "requestId": "request-uuid"
  }
}

Common Filters

FilterAccepted valuesNotes
statusactive, closed, blocked, allConversation status filter.
archived and unreadOnlytrue or falseLimit to archived or unread conversations.
lastDirectioninbound, outboundFilter by last message direction.
labelUid, includeLabelUids, excludeLabelUidsLabel UIDsComma-separated values are accepted for include/exclude filters.
labelMatchModeANY, ALLDefault ANY.
sortBylast_message_at, updated_at, created_at, total_messages, unread_countConversation list sort field.
sortOrderASC, DESCSort direction.

SDK Examples

Use these examples as starting points for server-side implementations.

cURL
curl -X GET "https://graph.whats91.com/api/v2/reports/conversations" \
  -H "Authorization: Bearer w91_live_xxx"
Node.js
const response = await fetch("https://graph.whats91.com/api/v2/reports/conversations", {
  method: "GET",
  headers: {
    "Authorization": "Bearer w91_live_xxx",
    "Content-Type": "application/json"
  }
});

const data = await response.json();
console.log(data);
PHP
$ch = curl_init("https://graph.whats91.com/api/v2/reports/conversations");
curl_setopt_array($ch, [
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer w91_live_xxx",
    "Content-Type: application/json"
  ]
]);

$response = curl_exec($ch);
curl_close($ch);
echo $response;
Python
import requests

response = requests.request(
    "GET",
    "https://graph.whats91.com/api/v2/reports/conversations",
    headers={
        "Authorization": "Bearer w91_live_xxx",
        "Content-Type": "application/json",
    }
)

print(response.json())
C#
using var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer w91_live_xxx");

var request = new HttpRequestMessage(HttpMethod.Get, "https://graph.whats91.com/api/v2/reports/conversations");

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Frequently Asked Questions

How do I list conversations?

Use GET /api/v2/reports/conversations with filters such as senderId, date range, status, labels, and pagination.

Can I fetch messages for one conversation?

Yes. Use the conversation messages endpoint with the conversation identifier and pagination parameters.

Can I search by mobile number?

Yes. Use the by-mobile endpoint to fetch conversation threads for a specific recipient number.

Related APIs

Summary

Return aggregate conversation totals for the same conversation filters.

By Mobile

List conversation thread summaries for one recipient mobile number.

Reports

List message reports with pagination, date filters, status filters, and sender scoping.

Samples

Webhook management requests, responses, and event payload samples for common Whats91 webhook flows.