# Label operations

Exact methods, permissions, request bodies and query fields for label operations.

## Get all labels (WhatsApp Business only)

GET /api/v1/channels/{channel_id}/labels

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get a specific label by ID

GET /api/v1/channels/{channel_id}/labels/{labelId}

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Create or update a label

PUT /api/v1/channels/{channel_id}/labels/{labelId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `name` (string): Maximum 100 characters. See JSON schema for all validation constraints.
- `color` (number): See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "color": {
      "type": "number",
      "minimum": 0,
      "maximum": 19
    }
  },
  "additionalProperties": false,
  "required": []
}
```





## Delete a label

DELETE /api/v1/channels/{channel_id}/labels/{labelId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get every chat carrying a label

GET /api/v1/channels/{channel_id}/labels/{labelId}/chats

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Get labels for a specific chat

GET /api/v1/channels/{channel_id}/labels/chat/{chatId}

Token scope: read. Paid access and a ready, customer-owned session are required. List responses are bounded; use documented pagination parameters.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```





## Add a label to a chat

POST /api/v1/channels/{channel_id}/labels/chat/{chatId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.



- `labelId` (string, required): Maximum 4096 characters. See JSON schema for all validation constraints.



```json
{
  "type": "object",
  "properties": {
    "labelId": {
      "type": "string",
      "maxLength": 4096
    }
  },
  "required": [
    "labelId"
  ],
  "additionalProperties": false
}
```





## Remove a label from a chat

DELETE /api/v1/channels/{channel_id}/labels/chat/{chatId}/{labelId}

Token scope: manage. Paid access and a ready, customer-owned session are required. Supply an Idempotency-Key. Returns an operation ID; inspect /api/v1/operations/{id}. A completed result is recorded; an unconfirmed result is uncertain and never automatically retried.

Upstream permissions and engine support apply. Unsupported operations may return 501; WhatsApp can refuse actions even when a session is connected.







```json
{
  "type": "object",
  "properties": {},
  "additionalProperties": false,
  "required": []
}
```