integração · rabbitmq
WhatsApp RabbitMQ: os eventos da API direto no broker do seu time
Ligue WhatsApp e RabbitMQ sem endpoint HTTP no meio: cada sessão publica os eventos no exchange do seu broker, e os seus workers consomem com prefetch, ack e dead-letter, inclusive o histórico que o webhook não entrega.
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
Configuração por sessão
Host, porta, usuário, senha, vhost, exchange e o mapa de eventos. Cada cliente do seu SaaS pode ir para um exchange diferente.
Histórico completo
history.message.upsert e history.message.received chegam só pelo RabbitMQ. O webhook suprime esses eventos.
Mesmo parser do webhook
O corpo é o envelope de sempre, com event, sessionId, data, timestamp e traceId, publicado como mensagem persistente.
Teste antes de salvar
POST /api/v1/rabbitmq/test-connection valida as credenciais do broker antes de ligar a publicação.
WhatsApp e RabbitMQ formam uma dupla natural para SaaS que já pensa em eventos. Quando o volume de mensagens dos seus clientes cresce, o endpoint HTTP que recebe webhook vira mais uma peça para escalar, monitorar e proteger. Com a publicação direta no broker, a D-API entrega cada evento numa fila RabbitMQ que o seu time já opera, e os workers consomem no ritmo que o sistema aguenta.
Esta página mostra como ligar a integração, o que exatamente chega no seu broker e como desenhar filas para muitos clientes, com o exemplo de uma plataforma de atendimento que processa as conversas de centenas de empresas.
Por que levar os eventos do WhatsApp para o RabbitMQ
O webhook resolve bem o começo. A fila passa a valer a pena em três situações:
- Controle de vazão. Com prefetch e número de consumidores, o seu time decide quantos eventos processa por vez. Num pico de campanha de um cliente grande, a fila cresce e os workers seguem no ritmo deles.
- Reprocessamento. Evento que falhou vai para uma dead-letter queue e pode ser reprocessado com as ferramentas do próprio broker.
- Histórico completo. Ao conectar, a sessão sincroniza o histórico do aparelho. Os eventos
history.message.upsertehistory.message.receivedsão suprimidos no webhook para evitar uma enxurrada de chamadas e só chegam pelo RabbitMQ.
Se o seu produto importa conversas antigas quando o cliente conecta o número, o terceiro ponto decide a escolha.
Ligar a publicação numa sessão
Primeiro, confirme que a D-API alcança o seu broker. POST /api/v1/rabbitmq/test-connection recebe host, port, username, password e, opcionalmente, vhost, e devolve success e uma mensagem. Rodar esse teste no onboarding evita salvar uma configuração que nunca vai publicar.
Depois, configure a sessão com POST /api/v1/sessions/{sessionId}/rabbitmq-config. Com enabled: true, a validação exige host, port, username e password. Na prática, informe também exchange e o mapa events, porque a publicação só acontece para os eventos marcados ali:
curl -X POST https://api.d-api.cloud/api/v1/sessions/empresa-271/rabbitmq-config \
-H "Authorization: SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"enabled": true,
"host": "mq.seu-saas.com",
"port": 5672,
"username": "dapi-publisher",
"password": "SENHA_DO_BROKER",
"vhost": "/atendimento",
"exchange": "whatsapp.eventos",
"events": {
"messages.received": { "enabled": true },
"messages.sent": { "enabled": true },
"message.read": { "enabled": true },
"history.message.upsert": { "enabled": true },
"history.message.received": { "enabled": true }
}
}'
Sem o mapa events, nada é publicado. Para desligar, envie { "enabled": false }. No SDK Node, o mesmo corpo vai em dapi.sessions.updateRabbitMQConfig(sessionId, config).
O que chega no seu broker
Ao conectar, a D-API declara no seu broker o exchange informado, do tipo direct e durável. A declaração é idempotente, então você pode criá-lo antes com as mesmas propriedades. Cada evento é publicado nesse exchange com routing key vazia, como mensagem persistente, com content-type: application/json e o horário de publicação na propriedade timestamp.
O corpo é o mesmo envelope do webhook: event, sessionId, data, timestamp e traceId. Um parser serve para os dois canais. A diferença fica em data, que chega como foi gerado, sem os campos de conveniência que o webhook acrescenta, como os objetos location e contact já interpretados. Também muda um nome: as mensagens enviadas de outro aparelho durante o histórico chegam como history.messages.sent, enquanto no webhook viram messages.received com fromMe: true. Os payloads de cada evento estão no catálogo de eventos de webhook.
Um consumidor com ack e dead-letter
Crie a fila, faça o bind no exchange com binding key vazia e consuma com ack manual. O exemplo usa Python com pika, mas qualquer cliente AMQP faz o mesmo:
import json, pika
conn = pika.BlockingConnection(pika.URLParameters(RABBITMQ_URL))
ch = conn.channel()
ch.exchange_declare("whatsapp.eventos", exchange_type="direct", durable=True)
ch.queue_declare("atendimento.inbox", durable=True,
arguments={"x-dead-letter-exchange": "whatsapp.dlx"})
ch.queue_bind("atendimento.inbox", "whatsapp.eventos", routing_key="")
ch.basic_qos(prefetch_count=20)
def handle(channel, method, props, body):
evt = json.loads(body)
try:
processar(evt["event"], evt["sessionId"], evt["data"], evt.get("traceId"))
channel.basic_ack(method.delivery_tag)
except Exception:
log.exception("falha no evento", extra={"sessionId": evt["sessionId"], "traceId": evt.get("traceId")})
channel.basic_nack(method.delivery_tag, requeue=False)
ch.basic_consume("atendimento.inbox", handle)
ch.start_consuming()
Com requeue=False, o evento que falhou vai para a dead-letter configurada na fila, em vez de voltar em loop. Mantenha o processamento idempotente pelo data.id da mensagem: o seu próprio reprocessamento a partir da DLQ pode entregar o mesmo evento outra vez.
Desenhar filas para muitos clientes
Como a routing key é vazia, um binding não separa tenants dentro do mesmo exchange. Duas formas resolvem, conforme o quanto você quer isolar.
| Desenho | Como fica | Quando usar |
|---|---|---|
| Exchange compartilhado | Todas as sessões apontam para o mesmo exchange; o consumidor roteia pelo sessionId do corpo |
A maior parte da base, com workers iguais para todos |
| Exchange por cliente | A sessão do cliente grande aponta para um exchange próprio, com filas e consumidores dedicados |
Cliente com volume alto ou SLA próprio no seu produto |
Como a configuração é por sessão, os dois desenhos convivem: a maioria das empresas no exchange compartilhado e os clientes maiores isolados. O vhost ajuda a separar ambientes, como homologação e produção, no mesmo broker.
O que monitorar na fila
Com os eventos no seu broker, a observabilidade também passa a ser sua. Três métricas cobrem quase todo incidente: profundidade da fila principal, que mostra se os workers acompanham o volume; tamanho da dead-letter, que aponta eventos que o seu código não soube tratar; e tempo entre o timestamp do envelope e o fim do processamento, que mede o atraso que o cliente final sente na inbox. Registre o sessionId e o traceId em cada log do consumidor, para chegar ao tenant afetado e conversar com o suporte da D-API sobre o mesmo evento.
Limites que entram no desenho
Dois comportamentos precisam estar no seu runbook. Se o broker ficar inacessível, a D-API reconecta com backoff exponencial, mas o evento daquela publicação não é reenviado. Para reconciliar uma janela de indisponibilidade, GET /api/v1/chats/{chatId}/messages traz as mensagens da conversa, paginadas. E o campo routingKey é aceito na configuração, mas hoje não altera a publicação, então não construa filtros que dependam dele.
Nada impede usar os dois canais na mesma sessão. Um desenho que funciona bem é o fluxo de mensagens no RabbitMQ e o connection.status num webhook acompanhado pelo time de operação, para avisar o cliente quando o número desconecta.
A referência dos eventos de histórico e da diferença entre webhook e RabbitMQ está na documentação da D-API. Para a parte de importação de conversas, veja também sincronizar histórico de conversas.
Time D-API. Atualizado em .
Perguntas frequentes
Posso filtrar eventos por routing key no meu broker?
Hoje não. Os eventos são publicados com routing key vazia, e o campo routingKey da configuração é aceito mas não altera a publicação. Filtre pelo mapa events da configuração ou pelo campo event no consumidor.
O que acontece com os eventos se o meu broker cair?
A D-API reconecta com backoff exponencial, mas o evento daquela publicação não é reenviado. Para reconciliar a janela fora do ar, consulte GET /api/v1/chats/{chatId}/messages.
Preciso escolher entre RabbitMQ e webhook?
Não. Os dois podem rodar juntos na mesma sessão. Um desenho comum é o fluxo de mensagens na fila e connection.status no webhook do time de operação.
Qualquer RabbitMQ serve?
Serve o broker que a D-API alcançar pela rede com as credenciais informadas, seja self-hosted ou gerenciado. Use o teste de conexão para confirmar antes de salvar.