← Back to Blog
product-update byon coexistence message-echoes ai-agents api-v2

WhatsApp Coexistence: message_echoes Explained

Ler em português →

Short version: if your number uses Coexistence, your team can reply from the WhatsApp Business app on the phone while your AI agent replies through the API. Until now the agent only saw its own half of those conversations. PipesBot can now forward every message sent from the phone to your App as a message echo. It’s opt-in, available on API v2 Apps, and media comes along.

The blind spot

Coexistence is why most of our customers can use the Cloud API at all: the number keeps working in the WhatsApp Business app, and the same number answers through the API. Owners keep chatting from the phone, the bot handles the rest.

The catch is that a reply typed on the phone doesn’t go through the API, so your App never heard about it. Picture this:

  1. A customer asks about a delayed order.
  2. The store owner sees it first and answers from the phone: “It ships today, sorry for the wait.”
  3. Ten minutes later the customer writes “great, thanks”, and the bot, with no idea what was said, answers with the delivery FAQ.

The agent had a gap in its memory exactly where a human stepped in. That’s the moment it most needs context.

How echoes work

Meta reports phone-sent messages through a separate webhook field, smb_message_echoes, and the messages themselves arrive in a message_echoes array. Turn on Forward messages sent from the phone in your App settings, and PipesBot delivers each one as a v2 envelope:

{
  "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": "It ships today, sorry for the wait." }
      }
    ]
  }
}

In an echo, from is your business number and to is the customer (with to_user_id when Meta has a BSUID). Images, audio and documents sent from the phone are downloaded and listed in pipes.media, the same way inbound media is. Messages your App sends through the PipesBot API don’t produce echoes, so you won’t see your own sends twice.

The one rule: never reply to an echo

Your bot is built to answer every incoming message. An echo is your own team talking. If it reaches the reply logic, the bot will answer the store owner, in front of the customer.

Check the envelope field before anything else:

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 }); // store, never reply
    }
    return;
  }
  // inbound messages and statuses go here
}

Use the same key you use for inbound messages. If you key users by BSUID, that’s to_user_id with to as the fallback, so the phone reply lands in the same history as the customer’s messages.

This is also why echoes are off by default. No App receives them until you’ve decided where they go.

A few more details:

  • Echoes don’t open or extend the 24-hour service window. Only messages from the customer do.
  • Phone-sent messages stay free. Meta doesn’t bill them, and their statuses come without a pricing object.
  • Deduplicate deliveries on envelope.id. Don’t dedupe on the wamid alone: an echo and its sent, delivered and read statuses share the same wamid. For statuses, key on wamid plus status.

Statuses you didn’t expect

Messages sent from the phone get sent, delivered and read statuses too, and those arrive as normal messages events whether echoes are on or off. So your App may see a status for a wamid it never sent. That’s not an error. With echoes on, the echo carries the same wamid, and you can match them. Statuses can arrive before the echo, so give it a moment before deciding where a message came from.

Why v2 only

Echoes ride on the BYON API v2 envelope, where the field makes an echo impossible to confuse with an inbound message and Meta’s payload arrives intact, quoted replies (context) included. Legacy Apps keep ignoring echoes. If you’re on legacy, the upgrade is in Settings → Upgrade to API v2, but read the migration checklist first: it can’t be undone, it deletes stored conversations and discards legacy queued messages, and your handler has to read v2 envelopes before you switch.

Turn it on

  1. Make sure your App is on API v2.
  2. Add the field check above to your handler.
  3. In your App settings in the dashboard, enable Forward messages sent from the phone.

The Coexistence docs have the full payload reference.

Part of our guide to the official API: WhatsApp Cloud API for AI Agents.