Pular para o conteúdo principal

​
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.
Etiquetas estão disponíveis apenas em contas WhatsApp Business. Contas pessoais do WhatsApp não suportam etiquetas.
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. 
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
  }'
Resposta: 
{
  "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 CorCor
0Cinza claro
1Verde
2Azul
3Amarelo
4Rosa/Vermelho

​
Listar Etiquetas

Recupere todas as etiquetas da instância. 
curl https://api.wappfy.io/api/instances/inst_abc123/labels \
  -H "X-Api-Key: YOUR_API_KEY"

​
Atualizar uma Etiqueta

Atualize o nome ou cor de uma etiqueta existente. 
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. 
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123/labels/2 \
  -H "X-Api-Key: YOUR_API_KEY"
Excluir uma etiqueta a remove de todos os chats associados. Esta ação não pode ser desfeita.

​
Etiquetas de Chat

​
Obter Etiquetas de um Chat

Recupere todas as etiquetas atribuídas a um chat específico. 
curl https://api.wappfy.io/api/instances/inst_abc123/labels/chats/[email protected] \
  -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. 
curl -X PUT https://api.wappfy.io/api/instances/inst_abc123/labels/chats/[email protected] \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label_ids": ["1", "2"]
  }'
Para remover todas as etiquetas de um chat, passe um array vazio: {"label_ids": []}.

​
Obter Chats por Etiqueta

Recupere todos os chats que possuem uma etiqueta específica atribuída. 
curl https://api.wappfy.io/api/instances/inst_abc123/labels/2/chats \
  -H "X-Api-Key: YOUR_API_KEY"

​
Casos de Uso Comuns

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

​
Referência de Endpoints

MétodoEndpointDescrição
POST/api/instances/{id}/labelsCriar uma nova etiqueta
GET/api/instances/{id}/labelsListar 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}/chatsObter chats por etiqueta

​
Tratamento de Erros

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