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

> Crie e gerencie etiquetas do WhatsApp Business para organizar suas conversas e contatos.

# Etiquetas

Etiquetas são um recurso do WhatsApp Business que permite categorizar e organizar suas conversas. Através da API da Wappfy, você pode criar etiquetas personalizadas, atribuí-las a chats e recuperar chats por etiqueta.

<Note>
  Etiquetas estão disponíveis apenas em contas WhatsApp Business. Contas pessoais do WhatsApp não suportam etiquetas.
</Note>

Todos os endpoints de etiquetas são vinculados a uma instância específica:

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

***

## Criar uma Etiqueta

Crie uma nova etiqueta com nome e cor.

<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": "Cliente VIP",
      "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: "Cliente VIP",
        color: 1,
      }),
    }
  );

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

**Resposta:**

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

### Cores das Etiquetas

O WhatsApp Business suporta um conjunto fixo de cores identificadas por número:

| ID da Cor | Cor           |
| --------- | ------------- |
| `0`       | Cinza claro   |
| `1`       | Verde         |
| `2`       | Azul          |
| `3`       | Amarelo       |
| `4`       | Rosa/Vermelho |

***

## Listar Etiquetas

Recupere todas as etiquetas da instância.

<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} (cor: ${label.color})`);
  });
  ```
</CodeGroup>

***

## Atualizar uma Etiqueta

Atualize o nome ou cor de uma 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": "Cliente Premium",
    "color": 2
  }'
```

***

## Excluir uma Etiqueta

Exclua permanentemente uma etiqueta. Isso remove a etiqueta de todos os chats aos quais estava atribuída.

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

<Warning>
  Excluir uma etiqueta a remove de todos os chats associados. Esta ação não pode ser desfeita.
</Warning>

***

## Etiquetas de Chat

### Obter Etiquetas de um Chat

Recupere todas as etiquetas atribuídas a um chat específico.

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

### Definir Etiquetas em um Chat

Atribua uma ou mais etiquetas a um chat. Isso substitui quaisquer etiquetas existentes no 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 remover todas as etiquetas de um chat, passe um array vazio: `{"label_ids": []}`.
</Tip>

### Obter Chats por Etiqueta

Recupere todos os chats que possuem uma etiqueta específica atribuída.

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

***

## Casos de Uso Comuns

<AccordionGroup>
  <Accordion title="Etiquetando novos leads automaticamente">
    Use um webhook para ouvir eventos `message.received`. Quando uma mensagem chegar de um contato desconhecido, atribua a etiqueta "Novo Lead" via API. Isso ajuda sua equipe a identificar e priorizar rapidamente novas conversas.
  </Accordion>

  <Accordion title="Rastreando status de tickets de suporte">
    Crie etiquetas como "Aberto", "Em Andamento" e "Resolvido". Atualize a etiqueta conforme sua equipe trabalha nos atendimentos. Use o endpoint "Obter Chats por Etiqueta" para construir uma fila de suporte simples.
  </Accordion>

  <Accordion title="Segmentando clientes para broadcasts">
    Etiquete clientes por categoria (ex: "VIP", "Atacado", "Varejo"). Ao enviar mensagens em massa, busque todos os chats de uma etiqueta e envie mensagens em sequência.
  </Accordion>
</AccordionGroup>

***

## Referência de Endpoints

| Método   | Endpoint                                     | Descrição                    |
| -------- | -------------------------------------------- | ---------------------------- |
| `POST`   | `/api/instances/{id}/labels`                 | Criar uma nova etiqueta      |
| `GET`    | `/api/instances/{id}/labels`                 | Listar todas as etiquetas    |
| `PUT`    | `/api/instances/{id}/labels/{labelId}`       | Atualizar uma etiqueta       |
| `DELETE` | `/api/instances/{id}/labels/{labelId}`       | Excluir uma etiqueta         |
| `GET`    | `/api/instances/{id}/labels/chats/{chatId}`  | Obter etiquetas de um chat   |
| `PUT`    | `/api/instances/{id}/labels/chats/{chatId}`  | Definir etiquetas em um chat |
| `GET`    | `/api/instances/{id}/labels/{labelId}/chats` | Obter chats por etiqueta     |

***

## Tratamento de Erros

| Código | Descrição                                                 |
| ------ | --------------------------------------------------------- |
| `400`  | Cor de etiqueta inválida ou campos obrigatórios faltando. |
| `404`  | Etiqueta ou chat não encontrado.                          |
| `409`  | Uma etiqueta com o mesmo nome já existe.                  |
| `422`  | Formato de chat ID inválido.                              |