# Blocklist

## Endpoints

- `GET /graph/whatsapp/{version}/{phoneNumberId}/block_users`: [List blocked contacts](https://docs.polymorfa.com/api/graph/blocklist/list-blocked-contacts)
- `POST /graph/whatsapp/{version}/{phoneNumberId}/block_users`: [Block](https://docs.polymorfa.com/api/graph/blocklist/block)
- `DELETE /graph/whatsapp/{version}/{phoneNumberId}/block_users`: [Unblock](https://docs.polymorfa.com/api/graph/blocklist/unblock)

## List blocked contacts

`GET https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/block_users` (Graph API)

Required permission: `sessions:read`

**Protocols:** Meta Cloud API

**Required scope:** `sessions:read`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Query parameters

- `limit` (string, pattern ^[1-9][0-9]{0,4}$). Specifies limit for this query parameter.
- `after` (string, max length 512). Specifies after for this query parameter.
- `before` (string, max length 512). Specifies before for this query parameter.

### Request

```bash
curl "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/block_users" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>"
```

### Responses

#### 200

Blocked users
- `data` (array of object, required). Structured data carried by this object.
  - `messaging_product` (string). Messaging product associated with this Graph API object. Values: `whatsapp`.
  - `wa_id` (string). The person's phone number, when WhatsApp can share it.
  - `user_id` (string). The person's business-scoped user ID.
  - `parent_user_id` (string). The person's parent business-scoped user ID, when the portfolio is enrolled in parent BSUIDs.
- `paging` (object). Structured paging values for this graph graph block users list response.
  - `cursors` (object). Structured cursors values for this paging.
    - `after` (string). Specifies after for this cursor.
    - `before` (string). Specifies before for this cursor.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "data": [
    {
      "messaging_product": "whatsapp",
      "wa_id": "string",
      "user_id": "string",
      "parent_user_id": "string"
    }
  ]
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Block

`POST https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/block_users` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body

- `messaging_product` (string). Always `whatsapp`. Added when omitted. Values: `whatsapp`.
- `block_users` (array of object, required, items 1–1000). 1 to 1,000 people.
  - `user` (string, length 1–32). The person's phone number. Takes precedence over `user_id` when both are present.
  - `user_id` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). The person's business-scoped user ID. Parent business-scoped user IDs (`CC.ENT.…`) are not supported.

### Request

```bash
curl -X POST "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/block_users" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "block_users": [
    {
      "user": "+16505551234",
      "user_id": "US.13491208655302741918"
    }
  ]
}'
```

### Responses

#### 200

Block result
- `messaging_product` (string). Messaging product associated with this Graph API object. Values: `whatsapp`.
- `block_users` (object, required). Structured block users values for this graph graph block users response.
  - `added_users` (array of object). Added users associated with this block user.
    - `input` (string). The phone number or business-scoped user ID from the request.
    - `wa_id` (string). The person's WhatsApp ID. Omitted when the request used a business-scoped user ID.
    - `user_id` (string). The person's business-scoped user ID. Omitted when the request used a phone number.
  - `removed_users` (array of object). Removed users associated with this block user.
    - `input` (string). The phone number or business-scoped user ID from the request.
    - `wa_id` (string). The person's WhatsApp ID. Omitted when the request used a business-scoped user ID.
    - `user_id` (string). The person's business-scoped user ID. Omitted when the request used a phone number.
  - `failed_users` (array of object). Failed users associated with this block user.
    - `input` (string). The phone number or business-scoped user ID from the request.
    - `wa_id` (string). The person's WhatsApp ID. Omitted when the request used a business-scoped user ID.
    - `user_id` (string). The person's business-scoped user ID. Omitted when the request used a phone number.
    - `errors` (array of object). Errors associated with this all of.
      - `message` (string). Human-readable message associated with this result.
      - `code` (integer). Stable machine-readable code for this result.
      - `error_data` (object). Structured error data values for this error.
        - `details` (string). Specifies details for this error data.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "block_users": {
    "added_users": [
      {
        "input": "string",
        "wa_id": "string",
        "user_id": "string"
      }
    ],
    "removed_users": [
      {
        "input": "string",
        "wa_id": "string",
        "user_id": "string"
      }
    ],
    "failed_users": [
      {
        "input": "string",
        "wa_id": "string",
        "user_id": "string",
        "errors": [
          {
            "message": "string",
            "code": 131047,
            "error_data": {
              "details": null
            }
          }
        ]
      }
    ]
  }
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

## Unblock

`DELETE https://api.polymorfa.com/graph/whatsapp/{version}/{phoneNumberId}/block_users` (Graph API)

Required permission: `messages:write`

**Protocols:** Meta Cloud API

**Required scope:** `messages:write`

### Path parameters

- `version` (string, required). Specifies version for this path parameter.
- `phoneNumberId` (string, required). Identifier for the phone number.

### Body

- `messaging_product` (string). Always `whatsapp`. Added when omitted. Values: `whatsapp`.
- `block_users` (array of object, required, items 1–1000). 1 to 1,000 people.
  - `user` (string, length 1–32). The person's phone number. Takes precedence over `user_id` when both are present.
  - `user_id` (string, pattern ^[A-Z]{2}\.[A-Za-z0-9]{1,128}$). The person's business-scoped user ID. Parent business-scoped user IDs (`CC.ENT.…`) are not supported.

### Request

```bash
curl -X DELETE "https://api.polymorfa.com/graph/whatsapp/v26.0/<phoneNumberId>/block_users" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "block_users": [
    {
      "user": "+16505551234",
      "user_id": "US.13491208655302741918"
    }
  ]
}'
```

### Responses

#### 200

Unblock result
- `messaging_product` (string). Messaging product associated with this Graph API object. Values: `whatsapp`.
- `block_users` (object, required). Structured block users values for this graph graph block users response.
  - `added_users` (array of object). Added users associated with this block user.
    - `input` (string). The phone number or business-scoped user ID from the request.
    - `wa_id` (string). The person's WhatsApp ID. Omitted when the request used a business-scoped user ID.
    - `user_id` (string). The person's business-scoped user ID. Omitted when the request used a phone number.
  - `removed_users` (array of object). Removed users associated with this block user.
    - `input` (string). The phone number or business-scoped user ID from the request.
    - `wa_id` (string). The person's WhatsApp ID. Omitted when the request used a business-scoped user ID.
    - `user_id` (string). The person's business-scoped user ID. Omitted when the request used a phone number.
  - `failed_users` (array of object). Failed users associated with this block user.
    - `input` (string). The phone number or business-scoped user ID from the request.
    - `wa_id` (string). The person's WhatsApp ID. Omitted when the request used a business-scoped user ID.
    - `user_id` (string). The person's business-scoped user ID. Omitted when the request used a phone number.
    - `errors` (array of object). Errors associated with this all of.
      - `message` (string). Human-readable message associated with this result.
      - `code` (integer). Stable machine-readable code for this result.
      - `error_data` (object). Structured error data values for this error.
        - `details` (string). Specifies details for this error data.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "block_users": {
    "added_users": [
      {
        "input": "string",
        "wa_id": "string",
        "user_id": "string"
      }
    ],
    "removed_users": [
      {
        "input": "string",
        "wa_id": "string",
        "user_id": "string"
      }
    ],
    "failed_users": [
      {
        "input": "string",
        "wa_id": "string",
        "user_id": "string",
        "errors": [
          {
            "message": "string",
            "code": 131047,
            "error_data": {
              "details": null
            }
          }
        ]
      }
    ]
  }
}
```

#### 400

Bad request
- `error` (object, required). Error details returned when the operation fails.
  - `message` (string, required). Human-readable message associated with this result.
  - `type` (string, required). Type discriminator for this object.
  - `code` (number, required). Stable machine-readable code for this result.
  - `error_subcode` (number). Machine-readable error subcode for this error.
  - `error_data` (any, nullable). Specifies error data for this error.
  - `fbtrace_id` (string, required). Identifier for the fbtrace.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 401

Unauthenticated
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 403

Permission error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 404

Object does not exist
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 429

Rate limited
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```

#### 500

Internal error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "message": "string",
    "type": "string",
    "code": 0,
    "fbtrace_id": "string"
  }
}
```
