> ## 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.

# Create label

> Creates a new label with a name and an optional color

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

## Description

Creates a label on the instance. The `id` is allocated by the API (sequential) and then propagated to WhatsApp via app state, it may take 1 to 2 seconds to appear on the phone.

<Tip>
  `color` is optional (default `0`) and accepts an integer between 0 and 10, which corresponds to the native WhatsApp Business palette.
</Tip>

## Examples

### Minimum

Creates the label with `name` only, without color. The server assigns `color: 0` by default and generates a sequential `id` returned in the response.

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

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

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

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

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

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

  func main() {
      body := strings.NewReader(`{"name":"Premium"}`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/tag/"+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>

### With color

Creates the "VIP" label using shade 5 of the WhatsApp Business palette via `color: 5` (accepted range: 0 to 10), enabling visual differentiation between labels on the phone.

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

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

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

  requests.post(
      f"https://ryzeapi.cloud/api/chat/tag/{os.environ['Instance_Name']}",
      headers={
          "token":        os.environ["Token_Instance"],
          "Content-Type": "application/json"
      },
      json={"name": "VIP", "color": 5}
  )
  ```

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

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

  func main() {
      body := strings.NewReader(`{"name":"VIP","color":5}`)
      req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/chat/tag/"+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

The `tag` object carries the `id` generated by WhatsApp (use it in `tags-assign`/`tags-unassign`), the saved `name`, the applied `color` (`0` when the client did not send it or sent it outside the 0–10 range), and the label `type`. `deleted` stays `false` on creations.

```json 200 OK theme={null}
{
  "success": true,
  "message": "Tag created successfully",
  "tag": {
    "id": "3",
    "name": "VIP",
    "color": 5,
    "type": "CUSTOM",
    "deleted": false
  }
}
```

## Path parameters

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

## Headers

| Name           | Required                 | Example            | Description                    |
| -------------- | ------------------------ | ------------------ | ------------------------------ |
| `Content-Type` | yes                      | `application/json` | ,                              |
| `token`        | yes (or `Authorization`) | `a1b2c3d4-...`     | TokenAccount or TokenInstance. |

## Request body

<ParamField body="name" type="string" required>
  Label name. Cannot be empty after `TrimSpace`.
</ParamField>

<ParamField body="color" type="int" default="0">
  Label color. Accepts integers between `0` and `10`, each index maps to a color from the native WhatsApp Business palette:

  | `color` | Hex       | Color         |
  | ------- | --------- | ------------- |
  | `0`     | `#ff9485` | Coral red     |
  | `1`     | `#64c4ff` | Sky blue      |
  | `2`     | `#ffd429` | Golden yellow |
  | `3`     | `#dfaef0` | Light lilac   |
  | `4`     | `#99b6c1` | Bluish gray   |
  | `5`     | `#55ccb3` | Mint green    |
  | `6`     | `#ff9dff` | Pink          |
  | `7`     | `#d3a91d` | Mustard       |
  | `8`     | `#6d7cce` | Violet blue   |
  | `9`     | `#d7e752` | Lime green    |
  | `10`    | `#00d0e2` | Cyan          |

  The values above reflect the current WhatsApp Business palette (it may change in future versions of the app, the index is stable, the actual shade is defined by the WhatsApp client). Values outside the `0`–`10` range are silently normalized to `0`.
</ParamField>

## Error responses

| HTTP | `error.message`                         | When it happens    |
| ---- | --------------------------------------- | ------------------ |
| 400  | `Instance name is required`             | Empty `:instance`. |
| 400  | `Invalid request body: <...>`           | Malformed JSON.    |
| 400  | `Tag name is required`                  | Empty `name`.      |
| 401  | `Invalid token`                         | ,                  |
| 404  | `Instance not found`                    | ,                  |
| 503  | `Instance is not connected to WhatsApp` | ,                  |

```json Error 400 theme={null}
{
  "success": false,
  "error": { "message": "Tag name is required" }
}
```

## Related

<CardGroup cols={2}>
  <Card title="List labels" href="/en/api/chat/tags-list">
    Confirm the newly created `id`.
  </Card>

  <Card title="Assign to a chat" href="/en/api/chat/tags-assign">
    Apply the label after creating it.
  </Card>
</CardGroup>