API de WhatsApp para CRM: a conversa dentro do card do lead

O que o usuário do seu CRM já está pedindo

No Brasil, boa parte da venda consultiva acontece no WhatsApp. Se o CRM não mostra essas conversas, o funil registrado é uma ficção: o lead avançou, esfriou ou fechou numa conversa que ninguém além do vendedor viu. Quando o vendedor sai da empresa, o histórico vai embora com o celular dele.

Por isso WhatsApp virou item de checklist em avaliação de CRM. As quatro funcionalidades que aparecem em quase toda conversa de venda do seu produto são estas:

• Inbox dentro do CRM: uma tela de conversas onde o vendedor lê e responde sem trocar de aplicativo.
• Histórico no card do lead: cada mensagem enviada ou recebida fica na linha do tempo do contato, ao lado de ligações, e-mails e mudanças de etapa.
• Vários vendedores e vários números: um número compartilhado pelo time ou um número por vendedor, com o gestor vendo tudo.
• Contatos sincronizados: quem mandou mensagem pela primeira vez vira lead automaticamente, com nome e telefone já preenchidos.

Como a arquitetura fica no seu CRM

A API de WhatsApp cuida da conexão com o WhatsApp. O CRM cuida do que já é dele: contas, usuários, permissões e o pipeline. A fronteira entre os dois é simples:

• Cada cliente do CRM (cada conta) tem uma ou mais conexões. Uma conexão é um número de WhatsApp, identificado por um sessionId que você escolhe.
• Mensagem recebida vira evento. A D-API chama o webhook do CRM com o evento messages.received, que traz o sessionId, o remetente e o conteúdo.
• Resposta do vendedor vira requisição. Quando alguém responde na inbox, o CRM chama a rota de envio com o sessionId daquela conta.

Na D-API, cada conexão roda em ambiente isolado, com credenciais, webhook e IP próprios. Se o número de um cliente cai ou é bloqueado, os outros clientes do CRM seguem funcionando. Esse é o tipo de incidente que, num CRM, vira chamado de todos os clientes ao mesmo tempo quando a infraestrutura é compartilhada.

Exemplo: provisionar a conexão quando o cliente ativa o WhatsApp

O momento certo de criar a conexão é quando o administrador da conta clica em "Conectar WhatsApp" nas configurações do CRM. Com o SDK de Node, o provisionamento e a exibição do QR Code ficam assim:

import { DApi } from 'd-api-sdk'

const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY })

export async function conectarWhatsapp(contaId, usuarioId) {
  const sessionId = 'crm-' + contaId + '-' + usuarioId

  await dapi.sessions.create({
    sessionId,
    connectionMode: 'qr',
    webhookUrl: 'https://app.seucrm.com.br/webhooks/whatsapp',
    metadata: { contaId, usuarioId, plano: 'pro' },
  })

  const { qrCodeImage } = await dapi.sessions.getQRCode(sessionId)
  return qrCodeImage // exibido na tela de configurações do CRM
}

O sessionId carrega o id da conta e do vendedor. Quando o webhook chega, o CRM sabe para qual conta e qual carteira a mensagem vai sem nenhuma tabela de tradução. O campo metadata guarda o que mais for útil para auditoria ou suporte.

Do webhook ao card do lead

O handler do webhook é onde a integração ganha cara de CRM. Um fluxo que funciona bem, na ordem:

1. Validar o sessionId e responder 200 rápido; o processamento vai para uma fila interna.
2. Normalizar o telefone de from.jid e procurar o contato na conta. Se não existir, criar o lead com o nome de from_name e origem "WhatsApp".
3. Gravar a mensagem na linha do tempo do lead. Se fromMe for verdadeiro, ela saiu do próprio número, por exemplo, digitada pelo vendedor no celular.
4. Atribuir a conversa: se o lead já tem dono, notifica o dono; se não, aplica a regra de rodízio da conta.
5. Para mídia, baixar pelo endpoint de download e anexar ao card, em vez de guardar só o link.

Dois detalhes evitam bug em produção. Mensagem editada chega como messages.received com type igual a edited_message, então o CRM deve atualizar o registro existente em vez de criar outro. E a entrega do webhook tem até 7 tentativas com backoff, o que significa que o mesmo evento pode chegar de novo: use o id da mensagem como chave única. O guia de webhook de WhatsApp detalha o envelope e os eventos.

Roteiro de implementação para o time do CRM

1. Semana 1, conexão: tela de configurações com QR Code, criação da conexão por API e indicador de status alimentado pelo evento connection.status.
2. Semana 2, entrada: webhook, criação automática de lead e histórico no card.
3. Semana 3, inbox: tela de conversas, resposta pelo CRM, envio de arquivo e atribuição por vendedor.
4. Semana 4, piloto: liberar para um grupo pequeno de clientes, medir desconexões e ajustar o aviso de reconexão.

O prazo varia com o tamanho do time, mas a parte difícil costuma ser a inbox, não a API. Nos 14 dias grátis falando com o time comercial, os seus devs implementam com suporte do nosso time num grupo de WhatsApp.

Um número por conta ou um por vendedor?

Não existe resposta única, e o CRM deveria deixar o cliente escolher. Número compartilhado dá ao gestor controle total e evita que o contato fique "preso" a uma pessoa. Número por vendedor respeita a relação que cada um construiu, mas multiplica conexões e exige regra clara para quando alguém sai. A página sobre múltiplos números no WhatsApp explica as implicações de operar vários números na mesma conta.

Se o seu CRM também atende pós-venda com fila e SLA, vale ver como isso muda em WhatsApp para helpdesk. O modelo de contratação para quem revende WhatsApp dentro do próprio produto está em API de WhatsApp para SaaS, e os valores por conexão em preços.