---
title: "Block users"
method: POST
path: "/v1/messaging/whatsapp/block-users"
tags: ["WhatsApp"]
---

# Block users

`POST /v1/messaging/whatsapp/block-users`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/whatsapp/block-users`
- Auth: HTTP bearer

Block one or more WhatsApp users on this number. Blocked users cannot
message your number or see that you are online, and your sends to them
return an error.

Meta constraints, surfaced per-user in `failed` (the request itself still
succeeds for the rest of the batch):
- Only users who messaged your business within the last 24 hours can be
  blocked (failures outside the window report "Re-engagement required").
- Up to 1,000 users per request; the blocklist caps at 64,000.
- Other WhatsApp Business accounts cannot be blocked.


**Billing:** Request; paid actions are priced in credits (see GET /v1/messaging/prices) · **Rate limit:** 60/min

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Request body

- object
  - `users` string[], required: Phone numbers (E.164, e.g. "+16505551234") or WhatsApp user IDs to block.
  - `accountId` string, required: WhatsApp account ID

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `failed` object[]: Users that could not be blocked, with reasons.
      - `input` string
      - `errors` string[]
    - `blocked` object[]: Users successfully blocked.
      - `waId` string: Resolved WhatsApp user ID.
      - `input` string: The value you sent.
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)