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

# Criar etiqueta

> Cria uma nova etiqueta (label) com nome e cor opcional

**Auth:** `TokenAccount` ou `TokenInstance` • **Rate-limit:** `Global` (100/min) • **Idempotente:** não

## Descrição

Cria uma etiqueta na instância. O `id` é alocado pela API (sequencial) e depois propagado ao WhatsApp via app state, pode levar 1 a 2 segundos para aparecer no celular.

<Tip>
  `color` é opcional (default `0`) e aceita um inteiro entre 0 e 10, que corresponde à paleta nativa do WhatsApp Business.
</Tip>

## Exemplos

### Mínimo

Cria a etiqueta apenas com `name`, sem cor. O servidor atribui `color: 0` por padrão e gera um `id` sequencial retornado na resposta.

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

### Com cor

Cria a etiqueta "VIP" usando o tom 5 da paleta do WhatsApp Business via `color: 5` (faixa aceita: 0 a 10), permitindo diferenciar etiquetas visualmente no celular.

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

## Resposta de sucesso

O objeto `tag` traz o `id` gerado pelo WhatsApp (use-o em `tags-atribuir`/`tags-desatribuir`), o `name` salvo, a `color` aplicada (`0` quando o cliente não enviou ou enviou fora da faixa 0–10) e o `type` da etiqueta. `deleted` permanece `false` em criações.

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

## Parâmetros de rota

<ParamField path="instance" type="string" required>
  Nome da instância.
</ParamField>

## Headers

| Nome           | Obrigatório              | Exemplo            | Descrição                      |
| -------------- | ------------------------ | ------------------ | ------------------------------ |
| `Content-Type` | sim                      | `application/json` | ,                              |
| `token`        | sim (ou `Authorization`) | `a1b2c3d4-...`     | TokenAccount ou TokenInstance. |

## Request body

<ParamField body="name" type="string" required>
  Nome da etiqueta. Não pode estar vazio após `TrimSpace`.
</ParamField>

<ParamField body="color" type="int" default="0">
  Cor da etiqueta. Aceita inteiros entre `0` e `10`, cada índice mapeia para uma cor da paleta nativa do WhatsApp Business:

  | `color` | Hex       | Cor             |
  | ------- | --------- | --------------- |
  | `0`     | `#ff9485` | Vermelho coral  |
  | `1`     | `#64c4ff` | Azul céu        |
  | `2`     | `#ffd429` | Amarelo dourado |
  | `3`     | `#dfaef0` | Lilás claro     |
  | `4`     | `#99b6c1` | Cinza azulado   |
  | `5`     | `#55ccb3` | Verde menta     |
  | `6`     | `#ff9dff` | Rosa pink       |
  | `7`     | `#d3a91d` | Mostarda        |
  | `8`     | `#6d7cce` | Azul violeta    |
  | `9`     | `#d7e752` | Verde limão     |
  | `10`    | `#00d0e2` | Ciano           |

  Os valores acima refletem a paleta atual do WhatsApp Business (pode mudar em versões futuras do app, o índice é estável, o tom em si é definido pelo cliente WhatsApp). Valores fora da faixa `0`–`10` são silenciosamente normalizados para `0`.
</ParamField>

## Respostas de erro

| HTTP | `error.message`                         | Quando ocorre      |
| ---- | --------------------------------------- | ------------------ |
| 400  | `Instance name is required`             | `:instance` vazio. |
| 400  | `Invalid request body: <...>`           | JSON malformado.   |
| 400  | `Tag name is required`                  | `name` vazio.      |
| 401  | `Invalid token`                         | ,                  |
| 404  | `Instance not found`                    | ,                  |
| 503  | `Instance is not connected to WhatsApp` | ,                  |

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

## Relacionados

<CardGroup cols={2}>
  <Card title="Listar etiquetas" href="/pt/api/chat/tags-list">
    Conferir o `id` recém-criado.
  </Card>

  <Card title="Atribuir a um chat" href="/pt/api/chat/tags-assign">
    Aplicar a etiqueta após criar.
  </Card>
</CardGroup>