Atendimento e suporte pelo WhatsApp integrado ao seu sistema
Receba as mensagens do WhatsApp por webhook, abra tickets no seu helpdesk e responda pela API com texto, mídia e reações, no número da sua empresa.
Atualizado em
O cliente quer falar com a empresa pelo WhatsApp, e a equipe de suporte quer trabalhar no sistema que já usa: o helpdesk, o CRM ou uma ferramenta interna. Um celular na mesa, passado de mão em mão, não escala e não deixa histórico. A apiwpp liga as duas pontas: o número da empresa fica conectado à API, cada mensagem recebida chega ao seu sistema por webhook e cada resposta sai pela API, do mesmo número.
Um ponto importante antes de começar: a apiwpp não é uma caixa de entrada de atendimento. Ela não tem tela de conversas, fila de atendentes nem distribuição de tickets. Ela é a API que o seu sistema usa para receber e enviar. A interface da equipe é a do seu produto.
Receber mensagens por webhook e abrir tickets
Quando alguém escreve para o número, a apiwpp envia um POST para o endereço de webhook do projeto com o evento message.incoming. O envelope traz o connectionId (qual número recebeu), o externalId que você associou à conexão e, em data, o remetente e o conteúdo:
{
"type": "message.incoming",
"connectionId": "8b1d4e7f-2c3a-4f5b-9e6d-7a8b9c0d1e2f",
"externalId": "suporte",
"timestamp": "2026-09-28T13:05:00.000Z",
"data": {
"jid": "[email protected]",
"phone": "+5511988887777",
"body": "Oi, meu pedido 1234 chegou com a caixa amassada.",
"timestamp": 1790600700,
"raw": { "key": { "remoteJid": "[email protected]", "fromMe": false, "id": "3EB0C767D26A1D8A3F52" } }
}
}
Um fluxo típico no seu servidor:
- Verifique a assinatura HMAC-SHA256 do cabeçalho
X-Sales-Signaturesobre o corpo bruto, como explica a página de webhooks assinados. - Responda 2xx rápido (em até 10 segundos) e processe o evento numa fila sua.
- Encontre ou crie o ticket pelo telefone do remetente (
data.phone): se já existe um ticket aberto para esse cliente, a mensagem entra nele; se não, abra um novo. - Seja idempotente. A entrega é at-least-once: o mesmo evento pode chegar mais de uma vez. Guarde o id da mensagem e ignore repetições.
Mídia recebida (foto do produto, comprovante em PDF, áudio) chega em data.media com uma URL assinada e temporária. Baixe o arquivo quando o evento chegar e guarde no seu sistema, em vez de salvar a URL. Às vezes o WhatsApp entrega só um identificador (LID) sem o telefone; quando o telefone for resolvido, chega o evento contact.resolved, e você completa o cadastro do ticket.
Responder pela API, com mídia e reações
A resposta do atendente sai pelo mesmo POST /connections/{id}/send de qualquer envio. O to é o telefone do cliente, só com dígitos:
{
"to": "5511988887777",
"message": "Sinto muito pelo transtorno! Pode mandar uma foto da caixa? Já vou abrir a troca.",
"typingDelay": 2000,
"clientRef": "ticket-5521-resposta-3"
}
O typingDelay mostra "digitando…" durante o tempo indicado, em milissegundos, antes da mensagem, em qualquer plano. O clientRef com o id do ticket e da resposta evita que um clique duplo do atendente ou uma nova tentativa do seu sistema mande a mesma resposta duas vezes. Veja idempotência com clientRef.
Além de texto, o atendente pode mandar um manual em PDF, uma imagem com o passo a passo ou um áudio, sempre a partir de uma URL https pública; os detalhes estão em envio de mídia. Respostas que se repetem, como horário de funcionamento ou o prazo de troca, podem virar templates com variáveis.
Para confirmar que viu uma mensagem sem escrever nada, reaja com um emoji: POST /connections/{id}/react com o id da mensagem e o emoji. Quando o cliente reage a uma resposta sua, chega o evento message.reaction.
Toda resposta entra na fila do número, que protege contra comportamento de robô. Um detalhe importa no atendimento: por padrão, há pelo menos 30 segundos entre duas mensagens para o mesmo destinatário. Junte a resposta numa mensagem só, em vez de mandar três mensagens curtas seguidas. Quem escreveu para você já é um contato conhecido, então o teto de destinatários novos por dia não bloqueia as respostas. As regras completas estão em fila anti-bloqueio.
Marcar como lida, "digitando" e correções (PRO)
No plano PRO, o seu sistema também controla os sinais que o cliente vê na conversa:
- Marcar como lida:
POST /connections/{id}/readcom até 100 ids de mensagens, quando o atendente abre o ticket. Os tiques azuis aparecem para o cliente. - Presença:
POST /connections/{id}/presencecomcomposing("digitando…"),recording("gravando áudio…"),pausedouavailable, enquanto o atendente escreve. - Editar uma resposta enviada pela API até 15 minutos depois do envio, ou apagar para todos, quando o atendente errou o valor ou o link.
No plano LITE, essas rotas respondem 403 plan_feature_required; o envio, o recebimento, as reações e o typingDelay funcionam nos dois planos. A comparação completa está em preços, e o teste grátis de 7 dias já inclui os recursos do PRO.
Menu de atendimento e vários atendentes
Para triagem, um menu numerado em texto funciona em qualquer plano: "Responda 1 para pedidos, 2 para trocas, 3 para falar com uma pessoa". A resposta chega em message.incoming, o seu sistema lê o número e encaminha o ticket para a fila certa. Botões e listas interativas não estão disponíveis hoje.
A distribuição entre atendentes é do seu sistema: quem pega o ticket, a transferência entre equipes, o SLA interno e o histórico ficam no seu helpdesk. Para a apiwpp, todas as respostas saem do mesmo número, pela mesma API. Se a equipe também responde pelo celular às vezes, ative o evento opcional message.outgoing no projeto: ele informa as mensagens enviadas pelo número, com origin: PHONE para as digitadas no aparelho, e o ticket fica completo.
Se você desenvolve um produto de atendimento para vários clientes, cada um com o próprio número, veja o caso de SaaS e CRMs e o guia como colocar o WhatsApp dentro do seu SaaS ou CRM. Para montar o webhook do zero, o tutorial webhooks do WhatsApp traz o código em Node.js e PHP.
Perguntas frequentes
A apiwpp tem uma tela para os atendentes responderem?
Não. A apiwpp é a API: ela entrega as mensagens recebidas ao seu sistema por webhook e envia as respostas que o seu sistema pede. A tela de conversas, a fila de tickets e a distribuição entre atendentes ficam no seu helpdesk, CRM ou ferramenta interna.
Vários atendentes podem responder pelo mesmo número?
Sim, pelo seu sistema. Todas as respostas saem do mesmo número pela API, e o seu sistema decide qual atendente responde cada ticket. Lembre que a fila espaça as mensagens para o mesmo cliente em pelo menos 30 segundos, no padrão.
Consigo marcar a mensagem do cliente como lida?
Sim, no plano PRO: POST /connections/{id}/read marca até 100 mensagens de uma vez, e POST /connections/{id}/presence mostra "digitando…" enquanto o atendente escreve. No LITE, o typingDelay do envio mostra "digitando…" antes de cada resposta.
Dá para enviar botões ou listas de opções?
Não hoje. Use um menu numerado em texto e leia a resposta do cliente no evento message.incoming. Funciona em qualquer plano e em qualquer versão do WhatsApp.
Recebo as fotos e os documentos que o cliente manda?
Sim. O message.incoming com mídia traz uma URL assinada e temporária do arquivo, com o tipo, o nome e o tamanho. Baixe o arquivo quando o evento chegar e guarde no seu sistema.
Outros casos de uso
Todos: Casos de uso →Coloque o WhatsApp dentro do seu produto: cada cliente pareia o próprio número pela sua tela, as conversas chegam por webhook com o id do cliente e você paga por número conectado.
Envie o aviso de vencimento, a segunda via do boleto e a confirmação de pagamento a quem já é seu cliente, a partir do seu sistema financeiro, sem risco de mandar a mesma cobrança duas vezes.
Mande pelo WhatsApp os avisos que o seu sistema já gera para quem é cliente (conta, serviço, pedido, alerta), com templates, envios sem duplicidade e a confirmação de entrega e leitura no seu webhook.