Pular para o conteúdo
D-APITestar grátis

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.

A gente também é SaaS

SaaS liberado pelo time testa 14 dias grátis, com um grupo de onboarding em que o time técnico da D-API acompanha a integração no seu produto.

Continue por aqui

Liberar seu teste grátis

Responda rapidinho e o time libera seu teste pelo WhatsApp, com o time técnico ajudando na integração.

Seus dados são usados só pra liberar o teste. Sem spam.