Etiquetas do WhatsApp Business

O WhatsApp Business deixa a equipe marcar conversas com etiquetas: LEAD, CLIENTE, "Pagamento pendente" e as que ela mesma cria no celular. A API DevZap expõe essas etiquetas para o seu sistema. A API oficial da Meta não tem etiquetas.

Pôr e tirar etiqueta exigem o escopo labels:manage; as leituras exigem labels:read, que vem junto com labels:manage. Chaves criadas no painel (*) já têm os dois. Aplicações conectadas por OAuth também: o consentimento inclui etiquetas, e as chaves emitidas antes de 05/10/2026 ganharam o escopo sem precisar reconectar.

Como o DevZap sabe das etiquetas

O WhatsApp não responde a uma pergunta do tipo "quais são as etiquetas". Elas chegam como mudanças de estado, e o DevZap guarda o último estado conhecido:

• Ao vivo: quando alguém mexe numa etiqueta no celular, a mudança chega em segundos.
• A cada conexão: o DevZap baixa o estado completo de novo e compara com o que tinha. É o que pega o que mudou enquanto a instância estava fora, inclusive etiquetas aplicadas no celular antes de você conectar o número.
• Na leitura: se o estado guardado tem mais de 15 minutos, a consulta o atualiza antes de responder (espera no máximo 10 segundos).

O campo syncedAt das respostas diz de quando é o estado completo que você está vendo.

Listar as etiquetas

curl https://SEU_HOST/api/v1/instances/INST-A1B2C3/labels \
  -H "Authorization: Bearer ten_sua_chave"

{
  "success": true,
  "data": [
    { "id": "5", "name": "CLIENTE", "color": 3, "kind": "custom", "chatsCount": 128 },
    { "id": "4", "name": "LEAD", "color": 1, "kind": "custom", "chatsCount": 42 }
  ],
  "syncedAt": "2026-10-05T20:01:28.862Z"
}

• id é o identificador da etiqueta no WhatsApp. Guarde-o: é ele que as outras rotas recebem. O nome pode mudar no celular; o id, não.
• color é uma das 20 cores do WhatsApp (0 a 19).
• kind: custom (criada pela equipe), predefined (uma das etiquetas padrão do WhatsApp Business) ou unknown (etiqueta sem tipo, antiga ou criada por outro sistema).
• chatsCount conta contatos e grupos com a etiqueta.

As listas do app ("Não lidas", "Grupos", "Favoritos") são guardadas pelo WhatsApp do mesmo jeito que as etiquetas, mas não aparecem aqui. Etiquetas apagadas também não.

Com a instância desconectada, a resposta é 400 INSTANCE_NOT_CONNECTED, como nas outras rotas de instância.

Quem tem uma etiqueta

curl "https://SEU_HOST/api/v1/instances/INST-A1B2C3/labels/4/chats?limit=100&offset=0" \
  -H "Authorization: Bearer ten_sua_chave"

{
  "success": true,
  "data": [
    { "chatId": "5511123450000@c.us", "phone": "5511123450000", "isGroup": false },
    { "chatId": "120363012345678901@g.us", "phone": null, "isGroup": true }
  ],
  "pagination": { "total": 2, "limit": 100, "offset": 0 },
  "syncedAt": "2026-10-05T20:01:28.862Z"
}

Um item por contato. O WhatsApp às vezes guarda o mesmo contato pelo telefone e pelo LID (um identificador interno que esconde o número); aqui ele aparece uma vez só. chatId usa o mesmo vocabulário do from do message.received. Quando o WhatsApp ainda não revelou o telefone de um contato, phone vem null e chatId traz o LID (<id>@lid). Etiqueta pode estar em grupo também (isGroup: true).

A paginação vai até 500 itens por página (limit, padrão 100). Etiqueta que não existe, foi apagada ou é uma lista do app responde 404 LABEL_NOT_FOUND.

As etiquetas de um contato

Para perguntar "este cliente é LEAD?" sem listar a etiqueta inteira:

curl https://SEU_HOST/api/v1/instances/INST-A1B2C3/chats/5511123450000/labels \
  -H "Authorization: Bearer ten_sua_chave"

O contato vai no caminho como telefone com DDI e DDD (só dígitos), ou como id de grupo (<id>@g.us): o mesmo formato do to do envio direto. O DevZap confere a grafia no WhatsApp (com ou sem o nono dígito) e procura o contato por todos os jeitos em que ele pode estar guardado. Número sem conta no WhatsApp responde 404 CONTACT_NOT_ON_WHATSAPP.

Pôr e tirar etiqueta

# põe a etiqueta 4 no contato
curl -X PUT https://SEU_HOST/api/v1/instances/INST-A1B2C3/labels/4/chats/5511123450000 \
  -H "Authorization: Bearer ten_sua_chave"

# tira
curl -X DELETE https://SEU_HOST/api/v1/instances/INST-A1B2C3/labels/4/chats/5511123450000 \
  -H "Authorization: Bearer ten_sua_chave"

{
  "success": true,
  "data": {
    "labelId": "4",
    "chat": { "chatId": "5511123450000@c.us", "phone": "5511123450000", "isGroup": false },
    "changed": true
  }
}

As duas são idempotentes: repetir dá o mesmo resultado. Se o contato já tinha a etiqueta (ou já não tinha, no caso de tirar), nada é escrito no WhatsApp e changed vem false. Tirar remove a etiqueta de todos os jeitos em que o contato estiver guardado. A mudança aparece no celular da equipe e gera o webhook correspondente, se assinado.

Criar, renomear e apagar etiquetas continua sendo no celular: a API lê as etiquetas, mostra quem tem cada uma e põe ou tira. Não existe envio de mensagem para todos de uma etiqueta: disparo em massa arrisca o número.

Erros próprios destas rotas:

Saber das mudanças sem consultar

Assine os eventos de etiqueta no webhook da instância (veja Webhooks):

Os eventos saem para mudanças de qualquer origem: a equipe no celular, a própria API, ou a comparação feita ao reconectar. Reconectar sem nada mudado não reenvia nada. Eles não vêm por padrão: o webhook só recebe o que você assinar.

← Todos os guias