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

# Crear etiqueta

> Crea una nueva etiqueta con nombre y un color opcional

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

## Descripción

Crea una etiqueta en la instancia. El `id` lo asigna la API (secuencial) y luego se propaga a WhatsApp vía app state, puede tardar 1 a 2 segundos en aparecer en el teléfono.

<Tip>
  `color` es opcional (predeterminado `0`) y acepta un entero entre 0 y 10, que corresponde a la paleta nativa de WhatsApp Business.
</Tip>

## Ejemplos

### Mínimo

Crea la etiqueta solo con `name`, sin color. El servidor asigna `color: 0` por defecto y genera un `id` secuencial devuelto en la respuesta.

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

### Con color

Crea la etiqueta "VIP" usando el tono 5 de la paleta de WhatsApp Business vía `color: 5` (rango aceptado: 0 a 10), permitiendo diferenciar visualmente etiquetas en el teléfono.

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

## Respuesta exitosa

El objeto `tag` lleva el `id` generado por WhatsApp (úsalo en `tags-assign`/`tags-unassign`), el `name` guardado, el `color` aplicado (`0` cuando el cliente no lo envió o lo envió fuera del rango 0–10) y el `type` de la etiqueta. `deleted` se mantiene en `false` en las creaciones.

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

<ParamField path="instance" type="string" required>
  Nombre de la instancia.
</ParamField>

## Cabeceras

| Nombre         | Requerido              | Ejemplo            | Descripción                   |
| -------------- | ---------------------- | ------------------ | ----------------------------- |
| `Content-Type` | sí                     | `application/json` | ,                             |
| `token`        | sí (o `Authorization`) | `a1b2c3d4-...`     | TokenAccount o TokenInstance. |

## Cuerpo de la solicitud

<ParamField body="name" type="string" required>
  Nombre de la etiqueta. No puede estar vacío después de `TrimSpace`.
</ParamField>

<ParamField body="color" type="int" default="0">
  Color de la etiqueta. Acepta enteros entre `0` y `10`, cada índice mapea a un color de la paleta nativa de WhatsApp Business:

  | `color` | Hex       | Color           |
  | ------- | --------- | --------------- |
  | `0`     | `#ff9485` | Rojo coral      |
  | `1`     | `#64c4ff` | Azul cielo      |
  | `2`     | `#ffd429` | Amarillo dorado |
  | `3`     | `#dfaef0` | Lila claro      |
  | `4`     | `#99b6c1` | Gris azulado    |
  | `5`     | `#55ccb3` | Verde menta     |
  | `6`     | `#ff9dff` | Rosa            |
  | `7`     | `#d3a91d` | Mostaza         |
  | `8`     | `#6d7cce` | Azul violeta    |
  | `9`     | `#d7e752` | Verde lima      |
  | `10`    | `#00d0e2` | Cian            |

  Los valores anteriores reflejan la paleta actual de WhatsApp Business (puede cambiar en futuras versiones de la app, el índice es estable, el tono concreto lo define el cliente de WhatsApp). Los valores fuera del rango `0`–`10` se normalizan silenciosamente a `0`.
</ParamField>

## Respuestas de error

| HTTP | `error.message`                         | Cuándo ocurre      |
| ---- | --------------------------------------- | ------------------ |
| 400  | `Instance name is required`             | `:instance` vacío. |
| 400  | `Invalid request body: <...>`           | JSON malformado.   |
| 400  | `Tag name is required`                  | `name` vacío.      |
| 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" }
}
```

## Relacionados

<CardGroup cols={2}>
  <Card title="Listar etiquetas" href="/es/api/chat/tags-list">
    Confirma el `id` recién creado.
  </Card>

  <Card title="Asignar a un chat" href="/es/api/chat/tags-assign">
    Aplica la etiqueta tras crearla.
  </Card>
</CardGroup>