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
  }'

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);

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 Cor	Cor
`0`	Cinza claro
`1`	Verde
`2`	Azul
`3`	Amarelo
`4`	Rosa/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"

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})`);
});

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

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"]
  }'

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"],
    }),
  }
);

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

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.

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.

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.

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.

Primeiros Passos

Guias

Etiquetas

Etiquetas

Criar uma Etiqueta

Cores das Etiquetas

Listar Etiquetas

Atualizar uma Etiqueta

Excluir uma Etiqueta

Etiquetas de Chat

Obter Etiquetas de um Chat

Definir Etiquetas em um Chat

Obter Chats por Etiqueta

Casos de Uso Comuns

Referência de Endpoints

Tratamento de Erros

​Etiquetas

​Criar uma Etiqueta

​Cores das Etiquetas

​Listar Etiquetas

​Atualizar uma Etiqueta

​Excluir uma Etiqueta

​Etiquetas de Chat

​Obter Etiquetas de um Chat

​Definir Etiquetas em um Chat

​Obter Chats por Etiqueta

​Casos de Uso Comuns

​Referência de Endpoints

​Tratamento de Erros

Etiquetas

Criar uma Etiqueta

Cores das Etiquetas

Listar Etiquetas

Atualizar uma Etiqueta

Excluir uma Etiqueta

Etiquetas de Chat

Obter Etiquetas de um Chat

Definir Etiquetas em um Chat

Obter Chats por Etiqueta

Casos de Uso Comuns

Referência de Endpoints

Tratamento de Erros