← Voltar ao Blog
novidades byon coexistence message-echoes agentes-ia api-v2

Message Echoes: Seu Agente de IA Agora Vê o Que Você Responde Pelo Celular

Read in English →

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:

  1. Um cliente pergunta sobre um pedido atrasado.
  2. A dona da loja vê primeiro e responde pelo celular: “Sai hoje, desculpa a demora.”
  3. 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ó pelo wamid: um echo e os status sent, delivered e read dele têm o mesmo wamid. Para status, use wamid mais status como 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

  1. Confirme que seu App está na API v2.
  2. Adicione a checagem de field acima no seu handler.
  3. 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.