Message Echoes: Seu Agente de IA Agora Vê o Que Você Responde Pelo Celular
Resumo: se o seu número usa Coexistence, sua equipe pode responder pelo app WhatsApp Business no celular enquanto o agente de IA responde pela API. Até agora o agente só via a metade dele dessas conversas. O PipesBot agora pode encaminhar para o seu App toda mensagem enviada pelo celular, como um message echo. É opt-in, está disponível em Apps na API v2, e a mídia vem junto.
O ponto cego
O Coexistence é o motivo pelo qual a maioria dos nossos clientes consegue usar a Cloud API: o número continua funcionando no app WhatsApp Business, e o mesmo número responde pela API. O dono continua conversando pelo celular e o bot cuida do resto.
O problema é que uma resposta digitada no celular não passa pela API, então seu App nunca ficava sabendo dela. Imagine:
- Um cliente pergunta sobre um pedido atrasado.
- A dona da loja vê primeiro e responde pelo celular: “Sai hoje, desculpa a demora.”
- Dez minutos depois o cliente escreve “ótimo, obrigado”, e o bot, sem saber o que foi dito, responde com o FAQ de prazos de entrega.
O agente tinha um buraco na memória exatamente onde um humano entrou na conversa. É justamente o momento em que ele mais precisa de contexto.
Como os echoes funcionam
A Meta informa as mensagens enviadas pelo celular num campo de webhook separado, smb_message_echoes. Ligue Forward messages sent from the phone nas configurações do App, e o PipesBot entrega cada uma como um envelope v2:
{
"id": "evt_9704f2252ffc4c0ea3df9122362d4033",
"field": "smb_message_echoes",
"createdAt": "2026-10-24T14:38:59.607Z",
"pipes": { "appId": "app_123", "poolNumberId": "pn_123", "media": {} },
"whatsapp": {
"messaging_product": "whatsapp",
"message_echoes": [
{
"from": "15550001111",
"to": "5511987654321",
"to_user_id": "BR.10293847561029384",
"id": "wamid.HBgUQlIuMTAyOTM4NDc1NjEwMjkzODQVFAARGCBBNTNC",
"type": "text",
"text": { "body": "Sai hoje, desculpa a demora." }
}
]
}
}
Num echo, from é o seu número comercial e to é o cliente (com to_user_id quando a Meta tem um BSUID). Imagens, áudios e documentos enviados pelo celular são baixados e listados em pipes.media, do mesmo jeito que a mídia recebida. Mensagens que seu App envia pela API do PipesBot não geram echoes, então você não vê seus próprios envios duplicados.
A regra de ouro: nunca responda a um echo
Seu bot foi feito para responder toda mensagem que chega. Um echo é a sua própria equipe falando. Se ele cair na lógica de resposta, o bot vai responder a dona da loja, na frente do cliente.
Confira o field do envelope antes de qualquer coisa:
function handleEnvelope(envelope: { field: string; whatsapp: any }) {
if (envelope.field === "smb_message_echoes") {
for (const echo of envelope.whatsapp.message_echoes ?? []) {
saveToHistory(echo.to_user_id ?? echo.to, { role: "business", message: echo }); // salve, nunca responda
}
return;
}
// mensagens recebidas e status entram aqui
}
Use a mesma chave que você usa para as mensagens recebidas. Se você identifica usuários pelo BSUID, ela é o to_user_id, com to como fallback. Assim a resposta enviada pelo celular cai no mesmo histórico das mensagens do cliente.
É também por isso que os echoes vêm desligados. Nenhum App recebe echoes até você decidir para onde eles vão.
Mais alguns detalhes:
- Echoes não abrem nem estendem a janela de atendimento de 24 horas. Só mensagens do cliente fazem isso.
- Mensagens enviadas pelo celular continuam grátis. A Meta não cobra por elas, e os status delas vêm sem o objeto
pricing. - Deduplique as entregas pelo
envelope.id. Não deduplique só pelowamid: um echo e os statussent,deliveredereaddele têm o mesmowamid. Para status, usewamidmaisstatuscomo chave.
Status que você não esperava
Mensagens enviadas pelo celular também recebem status sent, delivered e read, e eles chegam como eventos messages normais, com os echoes ligados ou não. Então seu App pode ver um status de um wamid que ele nunca enviou. Isso não é erro. Com os echoes ligados, o echo traz o mesmo wamid, e dá para casar os dois. Os status podem chegar antes do echo, então espere um pouco antes de concluir de onde veio a mensagem.
Por que só na v2
Os echoes usam o envelope da BYON API v2, em que o field impede que um echo seja confundido com uma mensagem recebida, e o payload da Meta chega inteiro, inclusive respostas com citação (context). Apps legacy continuam ignorando echoes. Se você está no legacy, o upgrade fica em Settings → Upgrade to API v2, mas leia antes o checklist de migração: ele não tem volta, apaga as conversas salvas e descarta as mensagens legacy na fila, e seu handler precisa ler envelopes v2 antes da troca.
Como ligar
- Confirme que seu App está na API v2.
- Adicione a checagem de
fieldacima no seu handler. - Nas configurações do App no dashboard, ligue Forward messages sent from the phone.
A documentação de Coexistence tem a referência completa do payload.