etiquetas e listas
Etiquetas WhatsApp API para o funil do seu SaaS aparecer no celular do cliente
Com as etiquetas WhatsApp API da D-API, o seu SaaS cria etiquetas, aplica nas conversas e recebe um webhook sempre que alguém muda uma etiqueta no celular. O funil do CRM e o WhatsApp do seu cliente passam a mostrar a mesma coisa.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Duas mãos de sincronização
O seu sistema aplica etiquetas pela API, e as mudanças feitas no aplicativo chegam por webhook. Nenhum lado fica desatualizado.
Etiqueta em conversa e em mensagem
Os eventos cobrem a etiqueta aplicada à conversa inteira e a etiqueta marcada numa mensagem específica, com o message_id.
Estado completo sob demanda
Liste todas as etiquetas da conta e as etiquetas de cada contato a qualquer momento, inclusive depois de uma reconexão.
As etiquetas WhatsApp API resolvem um problema que todo CRM e toda plataforma de atendimento conhece: o vendedor organiza o funil no sistema, mas continua respondendo pelo celular, onde as conversas não têm a menor ideia de em que etapa estão. Com a D-API, a etapa do funil vira uma etiqueta no WhatsApp do seu cliente, e a etiqueta que alguém aplica no celular volta para o seu sistema. Os dois lados passam a contar a mesma história.
Nas versões recentes do aplicativo, as etiquetas aparecem como Listas. As rotas ficam em /api/v1/labels e fazem parte da API não oficial.
Exemplos de etiquetas num SaaS
Antes da mecânica, vale ver onde o recurso gera valor.
CRM de vendas. Cada etapa do pipeline, como “Novo lead”, “Proposta enviada” e “Fechado”, vira uma etiqueta. Quando o card muda de coluna, a conversa no celular do vendedor muda de etiqueta junto.
Plataforma de atendimento. Etiquetas como “Aguardando cliente” e “Escalado para o financeiro” deixam o supervisor filtrar as conversas no próprio WhatsApp, sem abrir o painel.
Software de clínica. “Retorno pendente” e “Exames entregues” ajudam a recepção a saber quem precisa de contato, mesmo atendendo pelo celular da clínica.
Delivery. A lista “Novo pedido”, que o próprio app sugere, pode ser lida pelo seu sistema para abrir o pedido automaticamente.
Criar e editar etiquetas pela API
POST /api/v1/labels/upsert cria uma etiqueta ou edita uma que já existe. O label_id é obrigatório e precisa ser um inteiro positivo; ele identifica a etiqueta na conta.
curl -X POST https://api.d-api.cloud/api/v1/labels/upsert \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "crm-acme-vendas",
"label_id": 25,
"name": "Proposta enviada",
"color": 3
}'
Para renomear ou trocar a cor, repita a chamada com o mesmo label_id e os novos valores. Para excluir, envie deleted: true. Guarde no seu banco o mapeamento entre a etapa do funil e o label_id de cada cliente, porque cada conta de WhatsApp tem o próprio conjunto de etiquetas.
Aplicar e remover etiquetas nas conversas
POST /api/v1/labels/attach associa a etiqueta à conversa com um telefone. Com labeled: true a etiqueta é aplicada; com labeled: false, removida.
{
"sessionId": "crm-acme-vendas",
"phone": "5511999999999",
"label_id": 25,
"labeled": true
}
No fluxo do CRM, o gatilho é a mudança de etapa do card: remova a etiqueta da etapa anterior e aplique a da nova. Duas chamadas, e o vendedor vê a conversa no lugar certo assim que abre o WhatsApp.
Receber mudanças de etiqueta por webhook
O sentido inverso é o que fecha a sincronização. Quando alguém cria, edita ou exclui uma etiqueta, ou aplica uma etiqueta no celular, a D-API envia um evento.
| Evento | Quando |
|---|---|
labels.edit |
Etiqueta criada, editada ou excluída |
labels.association.chat |
Etiqueta aplicada ou removida de uma conversa |
labels.association.message |
Etiqueta aplicada ou removida de uma mensagem |
{
"event": "labels.association.chat",
"sessionId": "crm-acme-vendas",
"timestamp": "2026-09-30T16:36:26.764Z",
"data": {
"label_id": "25",
"label_name": "Proposta enviada",
"label_color": 3,
"chat": "[email protected]",
"labeled": true,
"from_full_sync": false,
"ts": 1790786186704
}
}
Com esse evento, o seu sistema move o card para a etapa correspondente, mesmo que a mudança tenha sido feita pelo vendedor no celular. Note que o label_id chega como texto, e que o chat pode vir como LID (...@lid) quando o número do contato não é conhecido pela sessão.
O labels.association.message tem os mesmos campos e acrescenta o message_id. Ele aparece quando alguém marca uma mensagem específica, e não a conversa inteira. Numa plataforma de atendimento, isso permite transformar a mensagem etiquetada como “Reclamação” num ticket, com o texto exato que o cliente mandou. Para quem quer levar essa lógica a um CRM próprio, a página de integração com CRM mostra o desenho completo.
O labels.edit traz detalhes sobre o tipo da lista. list_type vale custom para as criadas pelo usuário e assume valores como unread, favorites, groups e predefined para as listas do próprio WhatsApp. is_immutable: true marca as listas do sistema, que não podem ser renomeadas nem excluídas, e order_index informa a posição da lista no app.
Estado completo depois de conectar
Os webhooks entregam mudanças. Ao conectar, a sessão sincroniza todas as etiquetas e associações da conta, mas essa carga inicial não gera webhooks, para não reenviar o mesmo estado a cada reconexão.
Por isso, o estado completo vem das rotas de leitura. GET /api/v1/labels/list devolve todas as etiquetas da sessão, e GET /api/v1/labels/contact-labels devolve as etiquetas de um contato, pelo telefone. As duas aceitam includeDeleted=true para incluir as excluídas. E POST /api/v1/labels/sync pede uma sincronização completa das etiquetas, útil quando você suspeita que algo ficou para trás.
O padrão que funciona bem: ao receber o connection.status de conectado, leia /labels/list e reconcilie com o seu banco. Daí em diante, mantenha tudo atualizado pelos webhooks. A documentação da D-API traz todos os campos dos eventos.
Cuidados para quem atende muitos clientes
Num SaaS multi-tenant, as etiquetas são por conta de WhatsApp. O mesmo nome “Proposta enviada” pode ter label_id diferente em cada cliente, e um cliente pode já ter etiquetas próprias com os ids que você pretendia usar. Antes de criar as etiquetas do seu funil, leia a lista da conta e escolha ids livres.
Trate o webhook como fonte de verdade para mudanças feitas no celular e evite loops. Se o seu sistema aplica uma etiqueta e, ao receber o labels.association.chat correspondente, aplica de novo, você gera chamadas desnecessárias. Compare com o estado salvo antes de agir.
Para fechar o ciclo do CRM, combine as etiquetas com a API de contatos, que traz nome, foto e perfil comercial de cada conversa, e com as rotas de conversas para arquivar ou fixar. A lista completa de eventos está em eventos de webhook, e a visão geral da plataforma na página da API de WhatsApp.
Time D-API. Atualizado em .
Perguntas frequentes
Etiquetas e Listas do WhatsApp são a mesma coisa?
Sim. Nas versões recentes do aplicativo, as etiquetas aparecem como Listas. Pela API, as duas são tratadas como etiquetas, com o tipo informado em list_type.
Consigo ver etiquetas que foram apagadas?
Sim. As rotas de listagem aceitam includeDeleted=true e passam a trazer também as etiquetas excluídas, com deleted true.
O label_id é número ou texto?
Nas rotas de criação e associação ele é enviado como número inteiro positivo. Nos webhooks ele chega como texto, então converta antes de comparar.
Os eventos de etiqueta cobrem conversas de grupo?
Cobrem. O campo chat dos eventos de associação traz o JID da conversa, que termina em @s.whatsapp.net para contato e em @g.us para grupo.