Como responder mensagem citada no WhatsApp pela API

Responder uma mensagem específica no WhatsApp pela API — em vez de mandar uma mensagem solta — usa o mesmo MSG_ID da mensagem original numa rota diferente, e isso muda como a conversa fica organizada para quem lê. Este tutorial mostra o passo a passo para responder com texto, imagem, áudio, documento e localização.

Por que usar resposta citada em vez de envio comum

Numa conversa com várias mensagens seguidas — um cliente manda três perguntas de uma vez, por exemplo — responder cada uma citando a pergunta original evita ambiguidade. Sem a citação, quem lê a conversa depois não sabe a qual pergunta aquela resposta se refere.

Isso importa especialmente em atendimento com múltiplos atendentes no mesmo número: quando mais de uma pessoa responde no mesmo chat, a citação evita que uma resposta pareça estar fora de contexto para quem entra na conversa depois.

Pré-requisitos

• Uma instância da API já conectada (QR Code ou pareamento).
• Um webhook configurado recebendo mensagens, porque é de lá que vem o MSG_ID da mensagem que você vai responder.
• A key da sua instância, usada na URL de toda chamada (https://us.api-wa.me/{KEY}/...).

Passo a passo

1. Capture o MSG_ID da mensagem recebida

Toda mensagem recebida chega no seu webhook com um identificador único. Guarde esse valor no momento em que a mensagem chega — é ele que entra na URL da resposta:

{
  "id": "3EB0C767D097B4C5A1F2",
  "from": "5511999999999",
  "text": "Vocês entregam aos sábados?"
}

2. Responda com texto

curl -X POST https://us.api-wa.me/{KEY}/message/3EB0C767D097B4C5A1F2/text \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "text": "Sim, entregamos aos sábados até 14h!"}'

Note a diferença para um envio comum: o MSG_ID entra na própria URL, entre a key e o tipo de conteúdo (text).

3. Responda com imagem, áudio ou documento

O padrão se repete para cada tipo de mídia, só muda o segmento final da URL e o corpo da requisição:

# Responder com imagem
curl -X POST https://us.api-wa.me/{KEY}/message/3EB0C767D097B4C5A1F2/image \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "url": "https://exemplo.com/tabela-horarios.jpg", "caption": "Nossos horários de entrega"}'

# Responder com áudio
curl -X POST https://us.api-wa.me/{KEY}/message/3EB0C767D097B4C5A1F2/audio \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "url": "https://exemplo.com/audio-resposta.mp3"}'

# Responder com documento
curl -X POST https://us.api-wa.me/{KEY}/message/3EB0C767D097B4C5A1F2/document \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "url": "https://exemplo.com/catalogo.pdf", "filename": "catalogo.pdf"}'

4. Responda com localização

Útil quando a pergunta original é sobre endereço ou ponto de retirada:

curl -X POST https://us.api-wa.me/{KEY}/message/3EB0C767D097B4C5A1F2/location \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999999999", "lat": -23.5505, "lng": -46.6333, "name": "Loja Centro"}'

5. Automatize a captura e resposta pelo webhook

Na prática, os passos 1 e 2 acontecem no mesmo handler: seu webhook recebe a mensagem, decide a resposta e já chama a API de volta usando o id que acabou de receber, sem precisar de um passo manual no meio.

app.post('/webhook', async (req, res) => {
  const { id, from, text } = req.body;
  if (text?.toLowerCase().includes('sábado')) {
    await fetch(`https://us.api-wa.me/${KEY}/message/${id}/text`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ to: from, text: 'Sim, entregamos aos sábados até 14h!' }),
    });
  }
  res.sendStatus(200);
});

Respondendo com base no tipo de conteúdo recebido

Um agente de atendimento completo não responde sempre com o mesmo tipo de conteúdo — a escolha depende do que a pergunta pede. Uma regra simples de decisão, aplicada no mesmo handler que já captura o MSG_ID:

async function responderAdequado(id, from, textoRecebido) {
  const base = `https://us.api-wa.me/${KEY}/message/${id}`;

  if (/foto|imagem|catálogo/i.test(textoRecebido)) {
    return fetch(`${base}/image`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ to: from, url: CATALOGO_URL, caption: 'Nosso catálogo atualizado' }),
    });
  }

  if (/endereço|localização|onde fica/i.test(textoRecebido)) {
    return fetch(`${base}/location`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ to: from, lat: -23.5505, lng: -46.6333, name: 'Loja Centro' }),
    });
  }

  return fetch(`${base}/text`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ to: from, text: 'Como posso ajudar?' }),
  });
}

Esse tipo de roteamento simples resolve boa parte das perguntas recorrentes sem precisar de um modelo de IA — só entra em jogo quando a variação da pergunta é grande demais para um conjunto de regras.

Testando a resposta antes de colocar em produção

Antes de automatizar em volume, vale confirmar manualmente que a citação está funcionando como esperado:

1. Mande uma mensagem de teste do seu próprio número para a instância;
2. Capture o id que chega no webhook (log simples já resolve nessa etapa);
3. Chame o endpoint de resposta usando esse id copiado manualmente;
4. Confirme no app que a resposta chegou citando a mensagem original, e não como uma mensagem solta.

Esse teste manual, feito uma vez por tipo de conteúdo (texto, imagem, áudio, documento, localização), evita descobrir um erro de formato só depois que a automação já está respondendo clientes de verdade.

Erros comuns

Usar o endpoint de envio comum por engano. /message/text manda uma mensagem solta; /message/{MSG_ID}/text manda uma resposta citando a original. Os dois endpoints coexistem, e o erro mais comum de quem começa é esquecer o {MSG_ID} na URL — a mensagem sai, só que sem a citação.

Guardar o MSG_ID errado. Se sua aplicação processa várias mensagens em lote, é fácil associar o identificador errado à resposta errada. Vale sempre amarrar o id recebido diretamente à lógica que decide a resposta, no mesmo escopo do handler.

Responder a uma mensagem que já foi apagada. Se a mensagem original foi removida (por você ou pelo remetente) antes da resposta sair, a citação pode não aparecer do jeito esperado. Isso é raro, mas vale considerar em fluxo de resposta com atraso.

Resposta citada em conversa de grupo

O mesmo endpoint funciona também quando a mensagem original veio de um grupo, não só de uma conversa individual — a diferença está no to, que passa a ser o identificador do grupo em vez do número do contato:

curl -X POST https://us.api-wa.me/{KEY}/message/3EB0C767D097B4C5A1F2/text \
  -H "Content-Type: application/json" \
  -d '{"to": "[email protected]", "text": "Boa pergunta! A resposta está fixada no início do grupo."}'

Isso é útil para um bot de moderação ou de FAQ dentro de um grupo automatizado pela API: responder citando a pergunta específica, mesmo com várias mensagens simultâneas no grupo, deixa claro para todo mundo qual pergunta está sendo respondida.

Diferença entre resposta citada e encaminhamento

Vale não confundir os dois conceitos, porque a URL de cada um é parecida mas o efeito é bem diferente:

Responder é a escolha certa quando o contexto da mensagem original importa para quem lê a resposta. Encaminhar é a escolha certa quando o objetivo é levar o mesmo conteúdo para outro destinatário, sem vínculo visual com a conversa de origem — mais detalhe em editar, apagar e encaminhar mensagem pela API.

Próximos passos

Depois de dominar a resposta citada, o próximo recurso que combina bem é a presença "digitando..." pela API, que deixa a resposta automática com um tempo de reação mais natural antes de chegar. Para consolidar o fluxo de webhook que alimenta tudo isso, vale revisar webhook em produção: assinatura, retry e idempotência.