# Etiquetas de um chat

**Evento:** `chat_labels` · **Transporte:** POST para o seu receptor

Acompanhe alterações nas etiquetas associadas a uma conversa.

## Como processar

A atualização chega no objeto `chat`. O campo `chat.wa_label` representa a associação resultante; normalize a representação recebida antes de aplicar. Uma lista vazia significa que as etiquetas foram removidas.

Não confunda este evento com `labels`, que altera a definição da etiqueta. Em sincronizações, associações também podem chegar em `history` com `event: chat_labels` e metadados de chunks.

## Habilitar este evento

Adicione `chat_labels` à lista `events` do webhook da instância. Preserve os outros eventos de que sua integração precisa.

```json
{
  "enabled": true,
  "url": "https://seu-sistema.example/hooks/whatsapp",
  "events": [
    "chat_labels"
  ]
}
```

Envie essa configuração para [POST /webhook](/reference/updateWebhook.md), usando o header `token`. O JSON acima configura a assinatura; os exemplos de entrega abaixo são o que seu servidor recebe.

## Campos do payload

O envelope comum vem na raiz. Campos condicionais podem estar ausentes ou nulos conforme o evento; não use a tabela como obrigação de presença de todos os campos.

| Campo | Tipo | Significado |
|---|---|---|
| `EventType` | string | **Obrigatório.** Tipo de evento, por exemplo connection ou messages. |
| `owner` | string | **Obrigatório.** Consulte o objeto ou exemplo correspondente. |
| `token` | string | **Obrigatório.** Token da instância; dado sensível. |
| `BaseUrl` | string | **Obrigatório.** Consulte o objeto ou exemplo correspondente. |
| `instanceName` | string | Consulte o objeto ou exemplo correspondente. |
| `chat` | object | Snapshot de chat. Atualize pelos campos recebidos; não trate o evento como lista completa. |
| `chat.id` | string | ID local do chat. |
| `chat.wa_chatid` | string | JID da conversa. |
| `chat.name` | string | Nome disponível. |
| `chat.wa_isGroup` | boolean | Conversa de grupo. |
| `chat.wa_isBlocked` | boolean | Estado de bloqueio no snapshot. |
| `chat.wa_archived` | boolean | Estado de arquivamento. |
| `chat.wa_unreadCount` | integer | Quantidade de mensagens não lidas disponível. |
| `chat.wa_label` | variável | Etiquetas associadas, conforme a projeção do chat. Pode ser texto JSON; normalize antes de usar. |

## Exemplos de entrega

Exemplos ilustrativos com identificadores fictícios. O conteúdo específico e os campos opcionais variam.

### Todas as etiquetas removidas do chat

```json
{
  "EventType": "chat_labels",
  "owner": "5511999999999",
  "token": "INSTANCE_TOKEN",
  "BaseUrl": "https://seu-servidor.example",
  "instanceName": "Atendimento",
  "chat": {
    "id": "r0123456789abcd",
    "wa_chatid": "5511888888888@s.whatsapp.net",
    "wa_label": "[]"
  }
}
```

## Responder ao webhook

Seu receptor deve aceitar o POST JSON e devolver uma resposta `2xx` rapidamente, após validar e registrar o recebimento. O corpo da resposta não é um comando para a API. Processe trabalho demorado separadamente.

O worker não repete automaticamente uma entrega HTTP malsucedida. Consulte [diagnóstico de webhooks](/docs/integrations-webhooks#diagnostico) e implemente a reconciliação necessária. Eventos repetidos ou fora de ordem ainda precisam ser tolerados pelo receptor.

## Referências

- [Introdução, configuração e catálogo](/docs/integrations-webhooks)
- [Autenticação](/docs/authentication)
- [Contrato OpenAPI completo](/openapi-bundled.json)