> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ryzeapi.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Block/unblock contact

> Adds or removes a contact from the blocked list

**Auth:** `TokenAccount` or `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotent:** yes

Blocks or unblocks a contact. The response includes `blocked_count`, the total number of blocked contacts on the account after the operation.

## Examples

### Block

Adds the contact to the blocked list (`block: true`), stopping message sending and receiving in both directions. Previous history is preserved.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/chat/block/$Instance_Name" \
    -H "token: $Token_Instance" \
    -H "Content-Type: application/json" \
    -d '{"number": "5511999999999", "block": true}'
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/chat/block/${process.env.Instance_Name}`, {
    method: "POST",
    headers: {
      "token":        process.env.Token_Instance,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ number: "5511999999999", block: true })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      f"https://ryzeapi.cloud/api/chat/block/{os.environ['Instance_Name']}",
      headers={
          "token":        os.environ["Token_Instance"],
          "Content-Type": "application/json"
      },
      json={"number": "5511999999999", "block": True}
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{"number": "5511999999999", "block": true}`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/block/"+os.Getenv("Instance_Name"), body)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

### Unblock

Removes the contact from the blocked list (`block: false`), unblocking message traffic in both directions. The operation syncs automatically with the phone's app.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://ryzeapi.cloud/api/chat/block/$Instance_Name" \
    -H "token: $Token_Instance" \
    -H "Content-Type: application/json" \
    -d '{"number": "5511999999999", "block": false}'
  ```

  ```javascript JavaScript theme={null}
  await fetch(`https://ryzeapi.cloud/api/chat/block/${process.env.Instance_Name}`, {
    method: "POST",
    headers: {
      "token":        process.env.Token_Instance,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ number: "5511999999999", block: false })
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.post(
      f"https://ryzeapi.cloud/api/chat/block/{os.environ['Instance_Name']}",
      headers={
          "token":        os.environ["Token_Instance"],
          "Content-Type": "application/json"
      },
      json={"number": "5511999999999", "block": False}
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
      "strings"
  )

  func main() {
      body := strings.NewReader(`{"number": "5511999999999", "block": false}`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/block/"+os.Getenv("Instance_Name"), body)
      req.Header.Set("token", os.Getenv("Token_Instance"))
      req.Header.Set("Content-Type", "application/json")
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Success response

```json 200 OK theme={null}
{
  "success": true,
  "message": "Contact blocked successfully",
  "contact_jid": "5511999999999@s.whatsapp.net",
  "blocked_count": 7,
  "blocked": true
}
```

| Field           | Type    | Description                                                          |
| --------------- | ------- | -------------------------------------------------------------------- |
| `contact_jid`   | string  | JID of the affected contact.                                         |
| `blocked`       | boolean | Final state (`true` blocked, `false` unblocked).                     |
| `blocked_count` | int     | Total number of blocked contacts on the account after the operation. |

## Path parameters

<ParamField path="instance" type="string" required>
  Instance name.
</ParamField>

## Headers

<ParamField header="token" type="string" required>
  TokenAccount or TokenInstance.
</ParamField>

## Request body

<ParamField body="number" type="string" required>
  Phone number or JID of the contact. Individual contacts only, does not work with groups.
</ParamField>

<ParamField body="block" type="boolean" required>
  `true` blocks, `false` unblocks.
</ParamField>

## Notes

<Note>
  * Blocking stops sending/receiving messages in both directions; previous history remains.
  * Syncs with the phone's app automatically.
  * There is no specific webhook event for block/unblock in the current model.
</Note>

## Error responses

| HTTP | `error.message`                         | When               |
| ---- | --------------------------------------- | ------------------ |
| 400  | `Invalid request body`                  | Malformed JSON.    |
| 400  | `Number is required`                    | Missing field.     |
| 401  | `Invalid token`                         | ,                  |
| 404  | `Instance not found`                    | ,                  |
| 503  | `Instance is not connected to WhatsApp` | No active session. |