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

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.upsert e history.message.received sã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.

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.