Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rahul-baberwal/django-meta-whatsapp/llms.txt

Use this file to discover all available pages before exploring further.

The blocked users REST API lets you block and unblock WhatsApp contacts programmatically and retrieve your current block list. Blocks are applied on Meta’s platform and mirrored locally in the WhatsAppBlockedUser model for fast filtering in the inbox UI. All three endpoints use the first active WhatsAppAccount (selected via WhatsAppAccount.objects.filter(is_active=True).first()) and require the X-API-Key header — see Authentication.

​
POST /whatsapp/api/block/

Block a WhatsApp contact. The block is applied on Meta’s platform via the block_users() utility and the result is returned directly.

​
Request Body

{"phone": "+919876543210"}
​
phone
string
required
Phone number of the contact to block, including the country code. Example: "+919876543210".

​
Example

curl -X POST https://yourdomain.com/whatsapp/api/block/ \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+919876543210"}'

​
Success Response

{
  "status": "success",
  "meta_response": {
    "block_users": {
      "added_users": [{"input": "+919876543210", "wa_id": "919876543210"}],
      "failed_users": []
    }
  }
}
If Meta rejects the block (e.g. the contact hasn’t messaged in the past 24 hours), the number appears in failed_users with an error detail rather than added_users. Check meta_response.block_users.failed_users even on a 200 response.

​
DELETE /whatsapp/api/unblock/

Unblock a WhatsApp contact. The unblock is applied on Meta via the unblock_users() utility and the result is returned directly. The local WhatsAppBlockedUser record (if present) is not automatically updated by this endpoint — use the dashboard sync or sync_blocked_users_from_meta() to reconcile local state.

​
Request Body

{"phone": "+919876543210"}
​
phone
string
required
Phone number of the contact to unblock, including the country code with a leading +.

​
Example

curl -X DELETE https://yourdomain.com/whatsapp/api/unblock/ \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+919876543210"}'

​
Success Response

{
  "status": "success",
  "meta_response": {
    "block_users": {
      "removed_users": [{"input": "+919876543210", "wa_id": "919876543210"}],
      "failed_users": []
    }
  }
}

​
GET /whatsapp/api/blocked/

List all currently active blocked users for the first active WhatsAppAccount. Only records where is_active=True are returned — unblocked contacts (historical records with is_active=False) are excluded.

​
Example

curl https://yourdomain.com/whatsapp/api/blocked/ \
  -H "X-API-Key: your-key"

​
Success Response

{
  "blocked_users": [
    {
      "phone_number": "+919876543210",
      "blocked_at": "2024-01-10T09:15:00Z",
      "reason": "spam"
    }
  ]
}

​
Response Fields

​
blocked_users
array
List of all active WhatsAppBlockedUser objects for the account (where is_active=True).
Meta only allows blocking users who have sent a message to your business within the past 24 hours. Attempting to block an older contact will result in their number appearing in the failed_users array in the meta_response, even though the API returns HTTP 200. Always inspect meta_response.block_users.failed_users to confirm the block was applied.
For bulk operations — blocking or unblocking up to 1,000 contacts in a single API call to Meta — use the Python block_users() utility function instead of calling this endpoint in a loop. See Python Utility Functions for full usage and Blocked Users for advanced sync patterns including CSV import and scheduled cleanup jobs.

Build docs developers (and LLMs) love

Get started for freeTalk to us