Novo O Safe Mode aquece números novos para reduzir o risco de banimento no WhatsApp. Saiba mais →

Maytapi/Documentação//webhook

/webhookEventos em tempo real em JSON

API de webhooks do WhatsApp

Receba no seu próprio servidor as mensagens do WhatsApp, as confirmações de entrega e leitura e as mudanças de status da sessão no momento em que acontecem. Configure uma URL e todos os números conectados enviam seus eventos para ela em JSON.

  • mensagens recebidas
  • confirmações de entrega e leitura
  • status da sessão
  • uma URL para todos os números
Webhooks do WhatsApp para confirmações de entrega e leitura
Configurações de webhook no console da Maytapi e a mensagem recebida no WhatsApp entregue ao webhook
Eventos

Quatro tipos de evento, um só endpoint

Todo evento tem um campo type, então um único endpoint pode encaminhar mensagens, confirmações e mudanças de status de todos os seus números.

  • type: message

    Mensagens recebidas

    Texto, imagens, vídeo, áudio, documentos, localizações e cartões de contato enviados ao seu número, com o remetente e o id da conversa.

  • type: ack

    Confirmações de entrega e leitura

    Saiba quando uma mensagem enviada foi entregue, chegou ao celular, foi vista, reproduzida ou apagada.

  • type: status

    Status da sessão

    Seja avisado quando um celular fica ativo, aguarda leitura do QR, fica ocioso ou informa um erro.

  • live chat

    Eventos do chat ao vivo

    Usando a API junto com o LiveChat, os eventos dos atendentes chegam ao mesmo webhook.

  • phone_id

    Roteamento de vários números

    Cada evento traz product_id e phone_id, então um endpoint atende todos os números da sua conta.

  • reply

    URL de resposta pronta

    As mensagens recebidas trazem uma URL reply: responder ao cliente é uma única requisição POST.

Configuração

Configure seu webhook com uma requisição

Envie seu endpoint HTTPS para /setWebhook uma vez. A partir daí, cada celular conectado ao seu produto envia seus eventos para essa URL em JSON.

  • ✓Uma URL para todos os números conectados
  • ✓JSON simples via HTTPS POST
  • ✓Altere quando quiser pelo painel ou pela API
curl -X POST "https://api.maytapi.com/api/$PID/setWebhook" \
  -H "x-maytapi-key: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhook": "https://example.com/maytapi/webhook"}'
Ao vivo

Mensagens e confirmações na hora

O cliente escreve e seu servidor fica sabendo. Você envia uma mensagem e as confirmações de entrega e leitura chegam em segundos, sem consultas periódicas.

  • ✓Retorne HTTP 200 para confirmar o evento
  • ✓Processe eventos de forma assíncrona em alto volume
  • ✓Use msgId para associar confirmações às mensagens enviadas
message"type": "text", "text": "Meu pedido já foi enviado?"
ack · delivered"ackCode": 1, "ackType": "delivered"
ack · reached"ackCode": 2, "ackType": "reached"
ack · seen"ackCode": 3, "ackType": "seen"
status"status": "active"
Payloads

Como é um evento

Os eventos são objetos JSON compactos. O campo type diz como tratá-lo; product_id e phone_id dizem a qual conta e número ele pertence.

  • ✓message: texto, mídia, localização, vCard e mais
  • ✓ack: progresso da entrega com ackCode e ackType
  • ✓status: active, qr-code, idle, phone-error, loading, disabled
{
  "type": "message",
  "product_id": "1a2b3c4d-…",
  "phone_id": 12345,
  "user": {
    "id": "55119xxxxxx67@c.us",
    "name": "Customer",
    "phone": "55119xxxxxx67"
  },
  "message": {
    "id": "3EB081AF26FADE6416D8",
    "type": "text",
    "text": "Is my order shipped?",
    "fromMe": false
  },
  "conversation": "55119xxxxxx67@c.us",
  "receiver": "55119xxxxxx21",
  "timestamp": 1574081887,
  "reply": "https://api.maytapi.com/api/1a2b3c4d-…/12345/sendMessage"
}
Confirmações

Entrega e leitura, código por código

Os eventos ack mostram até onde cada mensagem enviada chegou. Se não precisar deles, desative com /setAckPreference e receba só as mensagens recebidas.

  • ✓Áudios também avisam quando são reproduzidos
  • ✓Mensagens apagadas também são informadas
ackTypeackCodeSignificado
delivered1Entregue aos servidores do WhatsApp
reached2Chegou ao celular do destinatário
seen3Vista pelo destinatário
played4Mensagem de voz reproduzida
deleted5Apagada pelo usuário
Resposta

Responda a partir do mesmo evento

As mensagens recebidas trazem uma URL reply pronta. Confirme o webhook rapidamente e depois envie sua resposta — um padrão simples para respostas automáticas e chatbots.

  • ✓Funciona com qualquer linguagem ou framework
  • ✓Ignore suas próprias mensagens com message.fromMe
app.post("/maytapi/webhook", express.json(), async (req, res) => {
  res.sendStatus(200); // acknowledge first

  const event = req.body;
  if (event.type !== "message" || event.message.fromMe) return;

  await fetch(event.reply, {
    method: "POST",
    headers: { "x-maytapi-key": TOKEN, "Content-Type": "application/json" },
    body: JSON.stringify({
      to_number: event.conversation,
      type: "text",
      message: "Thanks! We received your message."
    })
  });
});
Casos de uso

O que as equipes constroem com o webhook

  • Sincronização com CRM e helpdesk

    Cada mensagem recebida no WhatsApp vira automaticamente um ticket ou registro no seu CRM.

  • Chatbots e agentes de IA

    Passe as mensagens recebidas ao seu bot ou agente de IA e responda em tempo real pela URL reply.

  • Rastreio de entregas

    Guarde as confirmações de entrega e leitura para saber quais avisos de pedido os clientes realmente viram.

  • Monitoramento de sessões

    Avise sua equipe quando um número precisar de nova leitura de QR ou informar um erro.

  • Automações sem código

    Aponte o webhook para o n8n ou Make e crie fluxos sem escrever um backend.

  • Caixa compartilhada

    Encaminhe conversas de vários números para a pessoa certa da equipe.

FAQ

Perguntas frequentes sobre webhooks do WhatsApp

Pergunte o que quiser ao nosso suporte pelo WhatsApp. O tempo médio de resposta é inferior a 24 horas.

Central de ajuda →
O que é um webhook do WhatsApp?

Um webhook é uma URL no seu servidor que a Maytapi chama com uma requisição HTTPS POST sempre que algo acontece no seu número de WhatsApp: uma nova mensagem, uma confirmação de entrega ou leitura ou uma mudança de status da sessão.

Quais eventos chegam ao meu webhook?

Mensagens recebidas (type: message), confirmações de entrega e leitura (type: ack), mudanças de status da sessão (type: status) e, se você usa a API com o LiveChat, eventos do chat ao vivo.

Preciso de uma URL HTTPS pública?

Sim. O webhook precisa ser acessível pela internet. Durante o desenvolvimento, você pode expor seu servidor local com um túnel como o ngrok.

Um webhook pode atender vários números?

Sim. O webhook é configurado por produto e cada evento traz o phone_id, então um único endpoint atende todos os números da sua conta.

Posso desativar as confirmações de entrega e leitura?

Sim. Chame /setAckPreference com ack_delivery igual a false e seu webhook receberá apenas mensagens recebidas e mudanças de status.

Comece a usar a API do WhatsApp

Pegue sua chave e envie a primeira mensagem em dez minutos

Sem aprovação, sem templates, sem cartão. Todos os endpoints liberados por três dias.