How do I add a number to the blacklist?
Use the add blacklist endpoint with the mobile number and sender scope so future sends can be blocked.
List sender-scoped message blacklist entries for a WhatsApp registered sender.
List Blacklist Entries
Summary
Use Blacklist APIs to list, retrieve, add, update, and soft-delete blocked WhatsApp recipients for sender-scoped protection.
Prerequisites
- Bearer token authentication
- A sender scope for number-level blacklist management
Related documentation
Endpoint: GET /api/v2/message-blacklist. Whats91 exposes sender-scoped blacklist management through /api/v2/message-blacklist only. If a recipient is active in the blacklist for that sender, Whats91 send paths block delivery before Meta is called.
Use Authorization: Bearer w91_public_token_here. For GET compatibility, authToken, auth_token, or token can also be sent in the query string.
GET
/api/v2/message-blacklist| Parameter | Type | Required | Description |
|---|---|---|---|
Authorization | header | Required | Bearer w91_public_token_here. |
senderId | string | Optional | WhatsApp registered sender number. Global tokens can pass any owned sender; number-scoped tokens can only manage their bound sender. |
status | string | Optional | ACTIVE, INACTIVE, or ALL. Default is ACTIVE. |
search | string | Optional | Matches normalized phone, display phone, or reason. |
page | number | Optional | Positive integer page number. Default 1. |
limit | number | Optional | Page size for pagination. Default 50. |
List blacklist entries
curl -X GET "https://graph.whats91.com/api/v2/message-blacklist?senderId=916268662275&page=1&limit=50&status=ACTIVE" \
-H "Authorization: Bearer w91_public_token_here"List response
{
"success": true,
"message": "Blacklist entries retrieved",
"data": {
"senderId": "916268662275",
"phoneNumberId": "1234567890",
"wabaId": "9876543210",
"blacklistEntries": [
{
"blacklistUid": "bl_abc",
"uid": "bl_abc",
"phoneNumberId": "1234567890",
"senderPhoneNumber": "916268662275",
"normalizedPhone": "919876543210",
"displayPhone": "9876543210",
"source": "MANUAL",
"reason": "Customer requested opt-out",
"status": "ACTIVE",
"createdAt": "2026-06-06T08:00:00.000Z",
"updatedAt": "2026-06-06T08:00:00.000Z",
"deactivatedAt": null
}
],
"items": [
{
"blacklistUid": "bl_abc",
"normalizedPhone": "919876543210",
"status": "ACTIVE"
}
],
"pagination": {
"page": 1,
"limit": 50,
"count": 1,
"hasMore": false
}
},
"metadata": {
"apiVersion": "v2",
"requestId": "request-uuid"
}
}items is an alias for generic paginated clients. Internal database IDs, user_id, admin_id, encrypted values, and Redis/cache details are never returned.
| Filter | Accepted values | Use case |
|---|---|---|
| senderId | WhatsApp registered sender number | Resolve the sender whose blacklist should be inspected. |
| status | ACTIVE, INACTIVE, ALL | Review currently blocked numbers, inactive rows, or the complete list. |
| search | Phone or reason text | Find entries by normalized phone, display phone, or opt-out reason. |
| page and limit | Positive integers | Paginate sender-scoped blacklist entries. |
SDK Examples
Use these examples as starting points for server-side implementations.
cURL
curl -X GET "https://graph.whats91.com/api/v2/message-blacklist" \
-H "Authorization: Bearer w91_live_xxx"Node.js
const response = await fetch("https://graph.whats91.com/api/v2/message-blacklist", {
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/message-blacklist");
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/message-blacklist",
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/message-blacklist");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Frequently Asked Questions
Can blacklist entries be updated?
Yes. Use the update endpoint to adjust blacklist metadata or active state where supported.
Does delete permanently remove a blacklist entry?
The public API documents soft removal behavior so historical reporting context can remain available.
Related APIs
Add Number
Add or reactivate a recipient phone number in the sender blacklist.
Update Entry
Update the reason or status for one sender-scoped blacklist entry.
Chat Text
Send Whats91-specific free-form chat text messages inside the customer service window.
Message Status
Retrieve the latest status and lifecycle events for one message.