> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wappfy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Etiquetas

> Crea y gestiona etiquetas de WhatsApp Business para organizar tus chats y contactos.

# Etiquetas

Las etiquetas son una funcionalidad de WhatsApp Business que te permite categorizar y organizar tus chats. A traves de la API de Wappfy, puedes crear etiquetas personalizadas, asignarlas a chats y recuperar chats por etiqueta.

<Note>
  Las etiquetas solo estan disponibles en cuentas de WhatsApp Business. Las cuentas personales de WhatsApp no soportan etiquetas.
</Note>

Todos los endpoints de etiquetas estan asociados a una instancia especifica:

```
/api/instances/{instanceId}/labels/...
```

***

## Crear una etiqueta

Crea una nueva etiqueta con un nombre y un color.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.wappfy.io/api/instances/inst_abc123/labels \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "VIP Customer",
      "color": 1
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels",
    {
      method: "POST",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        name: "VIP Customer",
        color: 1,
      }),
    }
  );

  const label = await response.json();
  console.log(label.data.id);
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": {
    "id": "1",
    "name": "VIP Customer",
    "color": 1
  }
}
```

### Colores de etiquetas

WhatsApp Business soporta un conjunto fijo de colores de etiquetas identificados por numero:

| ID de color | Color      |
| ----------- | ---------- |
| `0`         | Gris claro |
| `1`         | Verde      |
| `2`         | Azul       |
| `3`         | Amarillo   |
| `4`         | Rosa/Rojo  |

***

## Listar etiquetas

Recupera todas las etiquetas de la instancia.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/labels \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  data.forEach((label) => {
    console.log(`${label.id}: ${label.name} (color: ${label.color})`);
  });
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "2", "name": "VIP Customer", "color": 1 },
    { "id": "3", "name": "Pending Payment", "color": 3 },
    { "id": "4", "name": "Resolved", "color": 2 }
  ]
}
```

***

## Actualizar una etiqueta

Actualiza el nombre o el color de una etiqueta existente.

```bash theme={null}
curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Customer",
    "color": 2
  }'
```

***

## Eliminar una etiqueta

Elimina permanentemente una etiqueta. Esto quita la etiqueta de todos los chats a los que estaba asignada.

```bash theme={null}
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY"
```

<Warning>
  Eliminar una etiqueta la quita de todos los chats asociados. Esta accion no se puede deshacer.
</Warning>

***

## Etiquetas de chat

### Obtener etiquetas de un chat

Recupera todas las etiquetas asignadas a un chat especifico.

```bash theme={null}
curl https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Respuesta:**

```json theme={null}
{
  "data": [
    { "id": "1", "name": "New Customer", "color": 0 },
    { "id": "3", "name": "Pending Payment", "color": 3 }
  ]
}
```

### Asignar etiquetas a un chat

Asigna una o mas etiquetas a un chat. Esto reemplaza cualquier etiqueta existente en el chat.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net \
    -H "X-Api-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "label_ids": ["1", "2"]
    }'
  ```

  ```javascript Node.js theme={null}
  await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels/chats/5511999998888@s.whatsapp.net",
    {
      method: "PUT",
      headers: {
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        label_ids: ["1", "2"],
      }),
    }
  );
  ```
</CodeGroup>

<Tip>
  Para quitar todas las etiquetas de un chat, pasa un array vacio: `{"label_ids": []}`.
</Tip>

### Obtener chats por etiqueta

Recupera todos los chats que tienen asignada una etiqueta especifica.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats \
    -H "X-Api-Key: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats",
    {
      headers: { "X-Api-Key": "YOUR_API_KEY" },
    }
  );

  const { data } = await response.json();
  console.log(`${data.length} chats with the "VIP Customer" label`);
  ```
</CodeGroup>

**Respuesta:**

```json theme={null}
{
  "data": [
    {
      "chat_id": "5511999998888@s.whatsapp.net",
      "name": "Maria Silva"
    },
    {
      "chat_id": "5511888887777@s.whatsapp.net",
      "name": "Carlos Oliveira"
    }
  ]
}
```

***

## Casos de uso comunes

<AccordionGroup>
  <Accordion title="Etiquetar nuevos leads automaticamente">
    Usa un webhook para escuchar eventos `message.received`. Cuando un mensaje llega de un contacto desconocido, asigna la etiqueta "Nuevo Lead" a traves de la API. Esto ayuda a tu equipo a identificar y priorizar rapidamente las nuevas conversaciones.
  </Accordion>

  <Accordion title="Seguimiento del estado de tickets de soporte">
    Crea etiquetas como "Abierto", "En progreso" y "Resuelto". Actualiza la etiqueta a medida que tu equipo trabaja en las solicitudes de soporte. Usa el endpoint "Obtener chats por etiqueta" para construir una cola de soporte sencilla.
  </Accordion>

  <Accordion title="Segmentar clientes para envios masivos">
    Etiqueta a los clientes por categoria (por ejemplo, "VIP", "Mayorista", "Minorista"). Al enviar mensajes masivos, obtiene todos los chats de una etiqueta y envia mensajes en un bucle.
  </Accordion>
</AccordionGroup>

***

## Referencia de endpoints

| Metodo   | Endpoint                                     | Descripcion                  |
| -------- | -------------------------------------------- | ---------------------------- |
| `POST`   | `/api/instances/{id}/labels`                 | Crear una nueva etiqueta     |
| `GET`    | `/api/instances/{id}/labels`                 | Listar todas las etiquetas   |
| `PUT`    | `/api/instances/{id}/labels/{labelId}`       | Actualizar una etiqueta      |
| `DELETE` | `/api/instances/{id}/labels/{labelId}`       | Eliminar una etiqueta        |
| `GET`    | `/api/instances/{id}/labels/chats/{chatId}`  | Obtener etiquetas de un chat |
| `PUT`    | `/api/instances/{id}/labels/chats/{chatId}`  | Asignar etiquetas a un chat  |
| `GET`    | `/api/instances/{id}/labels/{labelId}/chats` | Obtener chats por etiqueta   |

***

## Manejo de errores

| Codigo de estado | Descripcion                                              |
| ---------------- | -------------------------------------------------------- |
| `400`            | Color de etiqueta invalido o faltan campos obligatorios. |
| `404`            | Etiqueta o chat no encontrado.                           |
| `409`            | Ya existe una etiqueta con el mismo nombre.              |
| `422`            | Formato de chat ID invalido.                             |