integração · crm
Integração WhatsApp com CRM, com a conversa dentro do card do lead
Faça a integração WhatsApp com CRM que o seu cliente pede: cada mensagem na timeline do lead, etiquetas do WhatsApp espelhando o funil e o histórico antigo importado no dia em que o número conecta.
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
Timeline completa do lead
messages.received e messages.sent chegam no mesmo envelope, com o JID do contato. Inclui o que o vendedor manda pelo celular.
Etiquetas como etapa do funil
Crie e aplique etiquetas pela API e receba labels.association.chat quando alguém muda a etiqueta no app.
Histórico sem planilha
POST /api/v1/history/sync reenvia as mensagens guardadas no formato messages.received, com vazão controlada.
A integração WhatsApp com CRM decide se o seu produto vira o lugar onde o time comercial do seu cliente trabalha ou só mais uma aba aberta ao lado do celular. Vendedor que precisa copiar conversa para o card do lead para de copiar na segunda semana, e o CRM perde a informação mais rica do funil. Quando cada mensagem cai sozinha na timeline, o gestor enxerga a negociação inteira sem pedir print.
Esta página mostra como montar essa integração sobre a D-API, com o exemplo de um CRM de vendas B2B em que cada cliente do seu SaaS conecta o número do time comercial.
O que a integração de WhatsApp com CRM precisa entregar
Quatro coisas fazem o recurso parecer nativo para o usuário final:
- Toda mensagem no lead certo, recebida ou enviada, inclusive as que o vendedor manda pelo celular.
- Status de entrega e leitura, para saber se a proposta foi vista.
- Etapa do funil espelhada nas etiquetas do WhatsApp, nos dois sentidos.
- Histórico anterior importado quando o cliente conecta, para o CRM não começar vazio.
A D-API resolve a parte de conexão e eventos. O seu time fica com o mapeamento entre contato do WhatsApp e lead, que é regra do seu produto.
Conversas na timeline do lead
O resultado para o seu cliente é abrir o card e ver a conversa do jeito que ela aconteceu. A prova técnica está no webhook: messages.received traz o remetente em data.from.jid (o JID, como [email protected]), o texto em data.message, o tipo em data.type e, para mídia, a media_url do arquivo já armazenado.
Três casos precisam de atenção no mapeamento. Mensagens enviadas pela sua integração chegam como messages.sent. Mensagens que o vendedor manda pelo celular chegam como messages.received com fromMe: true. E mensagens de grupo vêm com is_group: true e group_name, que um CRM normalmente descarta ou trata à parte.
app.post('/hooks/whatsapp/:token', async (req, res) => {
if (req.params.token !== process.env.WA_HOOK_TOKEN) return res.sendStatus(401);
res.sendStatus(200);
const { event, sessionId, data, traceId } = req.body;
if (event !== 'messages.received' && event !== 'messages.sent') return;
if (data.is_group) return;
const tenant = await tenants.bySessionId(sessionId);
const contact = data.fromMe ? data.to : data.from;
const phone = contact?.jid?.split('@')[0];
if (!tenant || !phone) return;
const lead = await leads.findOrCreateByPhone(tenant.id, phone, contact.name);
await timeline.upsert({
leadId: lead.id,
externalId: data.id,
direction: data.fromMe ? 'out' : 'in',
type: data.type,
text: data.message,
mediaUrl: data.media_url ?? null,
traceId,
});
});
O upsert pelo data.id absorve as reentregas: o webhook tem até 7 tentativas com backoff exponencial, então o mesmo evento pode chegar mais de uma vez. O messages.sent tem a mesma estrutura do messages.received, com fromMe: true, from sendo o número da sessão e to o contato. Cada campo está no catálogo de eventos de webhook.
Para os ticks de leitura, guarde o messageId que a rota de envio devolve. Quando message.read chegar com o mesmo message_id, marque a proposta como lida.
Funil e etiquetas sincronizados
Muitos vendedores já organizam os contatos com etiquetas no WhatsApp Business. Se o seu CRM usa essas etiquetas como etapa do funil, o vendedor pode mover o lead no app ou no CRM e os dois ficam iguais.
No sentido CRM para WhatsApp, POST /api/v1/labels/upsert cria ou edita a etiqueta (com label_id, name, color ou deleted) e POST /api/v1/labels/attach aplica ou remove a etiqueta de um chat:
curl -X POST https://api.d-api.cloud/api/v1/labels/attach \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "crm-acme-comercial",
"phone": "5511999999999",
"label_id": 25,
"labeled": true
}'
No sentido WhatsApp para CRM, o evento labels.association.chat avisa quando uma etiqueta entra ou sai de uma conversa, com label_id, label_name, chat e labeled. O labels.edit cobre etiqueta criada, renomeada ou excluída. Um detalhe que evita bug: na sincronização feita ao conectar, as etiquetas existentes não geram webhook. Para montar o estado inicial, leia GET /api/v1/labels/list e GET /api/v1/labels/contact-labels uma vez e use os eventos dali em diante. A página sobre etiquetas pela API aprofunda esse fluxo.
Histórico importado quando o cliente conecta
O momento mais crítico de um CRM é o primeiro dia. Se o cliente conecta o número e vê o histórico vazio, a percepção é de ferramenta incompleta. Dá para evitar isso de duas formas.
A primeira é sincronizar ao conectar. A sessão aceita historySync: true na criação, e as mensagens trazidas do aparelho chegam como history.message.upsert e history.message.received. Esses dois eventos só são entregues pelo RabbitMQ, porque o webhook os suprime para evitar uma enxurrada de chamadas.
A segunda funciona com o webhook que você já tem. POST /api/v1/history/sync reenvia em massa o histórico armazenado da sessão para o seu endpoint, no mesmo formato de messages.received, com mídia quando a mensagem tem media_url. Você pode filtrar por intervalo em where.messageTimestamp (gte e lte) e por where.isGroup, e controla a vazão com delivery.maxRps, de padrão 100 e máximo de 500 requisições por segundo. O andamento fica em GET /api/v1/history/sync/{sessionId}/status. Como o seu handler já é idempotente pelo data.id, rodar a importação duas vezes não duplica nada. Mais detalhes em sincronizar histórico de conversas.
Contato válido antes de virar oportunidade
Lead que entra por formulário com telefone errado polui o funil. POST /api/v1/contacts/check recebe uma lista em numbers e responde quais estão no WhatsApp. Rodar essa checagem na entrada do lead economiza uma cadência inteira enviada para um número que nunca vai responder.
Para a lista de conversas dentro do CRM, GET /api/v1/chats aceita sessionId, search por nome ou telefone e paginação de até 100 itens. Para abrir uma conversa que ainda não está no seu banco, GET /api/v1/chats/{chatId}/messages traz as mensagens, também paginadas.
Clientes que exigem API Oficial
Parte da carteira de um CRM vende para empresas com área de compliance, que pedem a Cloud API da Meta. Na D-API, a conexão oficial usa o mesmo sessionId nas rotas de envio e, com webhookMode: "normalized", entrega os eventos no formato da não oficial. O handler acima serve aos dois. A diferença está na janela de 24 horas: fora dela, a primeira mensagem precisa ser um template aprovado, com a tarifa cobrada pela Meta na conta do cliente.
Por onde começar
Comece pelo que o usuário vê primeiro: conecte um número de teste, aponte o webhook para um endpoint que grava messages.received e messages.sent na timeline e confira o resultado num lead real. Em seguida acrescente message.read, depois as etiquetas e, por último, a importação de histórico. Cada etapa já é um recurso que o seu time comercial pode anunciar. A referência dos eventos de etiqueta está na documentação da D-API.
Time D-API. Atualizado em .
Perguntas frequentes
O vendedor pode continuar usando o WhatsApp no celular?
Pode. Na API não oficial o número segue ativo no aparelho. O que ele envia pelo celular chega no webhook como messages.received com fromMe true, então a timeline do CRM fica completa.
Consigo saber se o lead leu a proposta?
Sim. Os eventos message.delivered e message.read trazem o message_id e o remote_jid. Basta guardar o messageId devolvido no envio e atualizar o status quando o evento chegar.
Cada cliente do meu CRM precisa de uma conta na D-API?
Não. As conexões ficam na sua conta, uma sessão por número. Você guarda o sessionId junto do tenant e roteia os eventos por ele.
O CRM pode buscar conversas antigas sob demanda?
Pode. GET /api/v1/chats lista as conversas da sessão com busca por nome ou telefone, e GET /api/v1/chats/{chatId}/messages traz as mensagens paginadas, até 100 por página.