Coexistence

Keep using the WhatsApp Business app on your phone while your App sends and receives on the same number through the API.

Coexistence lets one WhatsApp number work in two places at once: the WhatsApp Business app on your phone, and the Cloud API through PipesBot. Your team keeps chatting from the app as usual, and your App receives messages and replies on the same number.

This is the default for BYON. If the number you connect is registered on the WhatsApp Business app, PipesBot connects it with Coexistence. You don't need to migrate the number or disconnect it from the app.

Coexistence vs full migration

CoexistenceFull migration
When it happensThe number is still registered on the WhatsApp Business appThe number is new, or is not on the WhatsApp Business app
WhatsApp Business appKeeps working on the phoneStops working for this number
Chat history on the phoneStays on the phone, unchangedNo app, so no history on the phone
APISend and receive through your AppSend and receive through your App
ThroughputFixed at 20 messages per second80 messages per second by default, upgraded automatically by Meta as you grow

Requirements

  • The number must be on the WhatsApp Business app, not personal WhatsApp. Meta requires app version 2.24.17 or newer.
  • The number must belong to a business portfolio (Business Manager) on Meta. You can create or pick one during Embedded Signup.
  • If the number is already connected to another provider, disconnect it in the app first: Settings → Account → Business Platform.
  • The person completing signup needs admin access to that business portfolio.

Connecting a number

  1. Create an App in your PipesBot dashboard.
  2. Start Embedded Signup, from the dashboard or with a signup link generated through the API.
  3. When Meta asks which number to use, choose the option to connect your existing WhatsApp Business app number.
  4. Confirm the connection in the WhatsApp Business app on your phone when it prompts you.

From then on, your App receives inbound messages through webhooks or WebSocket, and you reply through the REST API. Keep using the app on the phone as before.

Don't migrate or disconnect

Never pick migrate or disconnect in Meta's flow to make an existing app number work. Neither is needed for Coexistence, and a number moved off the app this way may not reconnect to it later. If Meta only offers Add a new number and then says the number is already registered to a WhatsApp account, stop and contact us.

Chat history

Your existing chats stay in the WhatsApp Business app on your phone. Connecting the number doesn't delete or change anything there.

By default, your App handles messages from the moment the number is connected. If you want the past chats and the phone's contact list too, turn on chat history and contacts import before the number connects. During signup, WhatsApp asks the business whether to share its chat history. Declining doesn't affect anything else: the number connects and works normally, only the history isn't sent.

Limitations

Meta changes a few things on numbers that use Coexistence:

  • Open the app regularly. If the WhatsApp Business app on the primary phone is inactive for about 14 days, Meta disconnects Coexistence.
  • Throughput is fixed at 20 messages per second, counting inbound and outbound together. You won't notice this at low volume. Meta returns error 130429 when you go over.
  • App features turned off in 1:1 chats: disappearing messages, view-once messages, and live location.
  • Broadcast lists become read-only, and you can't create new ones.
  • Groups keep working in the app, but group messages are not available through the API.
  • Linked devices (WhatsApp Web, desktop) are unlinked when you connect. You can link supported ones again afterwards.

Pricing

Messages your team sends from the WhatsApp Business app stay free. Messages your App sends through the API are billed by Meta at Cloud API rates, charged to the business portfolio that owns the number. PipesBot charges the BYON add-on of $5/number/month and adds no markup per message.

Message echoes

When someone on your team replies from the WhatsApp Business app, your App can receive that reply too. Your system then sees the full conversation, whether a reply was sent from the phone or through the API.

Echoes are off by default and require API v2. Turn them on in your App settings with Forward messages sent from the phone. Each reply is delivered as an envelope with field: "smb_message_echoes". Meta's payload is in whatsapp.message_echoes[], with from set to your number and to set to the customer:

{
  "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",
    "metadata": {
      "display_phone_number": "15550001111",
      "phone_number_id": "123456789012345"
    },
    "contacts": [
      { "wa_id": "5511987654321", "user_id": "BR.10293847561029384" }
    ],
    "message_echoes": [
      {
        "from": "15550001111",
        "to": "5511987654321",
        "to_user_id": "BR.10293847561029384",
        "id": "wamid.HBgUQlIuMTAyOTM4NDc1NjEwMjkzODQVFAARGCBBNTNC",
        "timestamp": "1792852737",
        "type": "text",
        "text": { "body": "Oi" }
      }
    ]
  }
}

Media in an echo is downloaded and listed in pipes.media, the same as for inbound messages.

Don't reply to echoes

An echo is a message your own team sent. Store it, but don't treat it as a customer message, or your bot will answer itself.

Statuses for messages sent from the phone

Messages sent from the WhatsApp Business app also get sent, delivered and read statuses, and these arrive with field: "messages" like any other status. They are delivered whether echoes are on or off. So your App can receive statuses for a wamid it has no record of. Don't treat that as an error. It is most likely a message sent from the phone, but it can also be an API send whose response your App never got. With echoes on, the echo carries the same wamid, so you can match the two. Statuses can arrive out of order, and even before the echo, so wait a little before deciding where a message came from. In our tests, statuses for messages sent from the app had no pricing object, because those messages are not billed.

Import chat history and contacts

When a number connects with Coexistence, your App can also receive the chats already on the phone (up to 6 months) and the phone's contact list. Use them to fill an inbox or CRM, give a bot context, or both. Both arrive as API v2 envelopes:

  • field: "history": past messages, in chunks.
  • field: "smb_app_state_sync": the contact list, then later contact edits.

Nothing arrives unless the import is requested when the number connects. Meta only sends this data after the partner asks for it, and PipesBot makes that request for you.

Turn it on

Both imports are off by default, independent of each other, and require API v2. There are two places to turn them on:

  • App settings. In your App, under Settings → Webhook Configuration, turn on Import chat history and/or Import contacts. They apply to every number connected while they're on, from the dashboard or from a signup link. On legacy Apps they are disabled.
  • Per signup link. POST /v1/apps/token accepts the optional booleans importHistory and importContacts. When present, they override the App settings for that link, in either direction (false turns off an import the App has on). When absent, the App setting applies.
{
  "redirectUrl": "https://yourapp.com/onboarding/complete",
  "metadata": { "customerId": "cus_123" },
  "importHistory": true,
  "importContacts": false
}

A value that is not a boolean returns 400 with "importHistory must be a boolean" or "importContacts must be a boolean". On a legacy App both values are ignored and nothing is imported.

The number.onboarded event tells you what was requested for that number: data.importHistory and data.importContacts are booleans. If importHistory is true, expect history events (or a decline, below).

What you can get:

  • Only numbers connected while the import is on (App setting or link override). Turning it on later doesn't import anything for numbers already connected.
  • Coexistence numbers only. A fully migrated number has no app history to import.
  • Once per number, within 24 hours of connecting. WhatsApp allows the request once. PipesBot retries temporary Meta errors inside that window, but once WhatsApp accepts the request it can't be repeated.
  • The business decides on the phone. If it declines to share history, you get a single history event with an error instead of messages (see When the business declines). Contacts are requested separately.
  • No group chats. History covers 1:1 chats only.

The Numbers page of your App shows the import state of each number, for example "History imported", "History not shared", "Contacts imported" or "History import expired".

History

History covers up to 180 days, sent in three phases: 0 (day 0 to 1), 1 (day 1 to 90) and 2 (day 90 to 180). Each envelope carries one or more chunks in whatsapp.history[]:

{
  "id": "evt_5a1c7e9b3d2f4a6c8e0b1d2c3f4a5b6d",
  "field": "history",
  "createdAt": "2026-11-01T14:40:05.789Z",
  "pipes": {
    "appId": "app_123",
    "poolNumberId": "pn_123",
    "media": {}
  },
  "whatsapp": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "15550001111",
      "phone_number_id": "123456789012345"
    },
    "history": [
      {
        "metadata": { "phase": 0, "chunk_order": 1, "progress": 40 },
        "threads": [
          {
            "id": "5511987654321",
            "messages": [
              {
                "from": "5511987654321",
                "id": "wamid.HIST1",
                "timestamp": "1792800000",
                "type": "text",
                "text": { "body": "Do you deliver on Sundays?" },
                "history_context": { "status": "READ" }
              },
              {
                "from": "15550001111",
                "to": "5511987654321",
                "id": "wamid.HIST2",
                "timestamp": "1792800060",
                "type": "media_placeholder",
                "history_context": { "status": "DELIVERED" }
              }
            ]
          }
        ]
      }
    ]
  }
}
  • threads[] has one entry per chat, with id set to the customer. Its messages[] use Meta's message format.
  • A message the business sent has from set to your number (metadata.display_phone_number), and carries to. A message from the customer has from set to the customer. Compare from with your number to tell them apart.
  • Every message has history_context.status.
  • metadata.progress is a percentage. 100 means the import is complete.
  • Chunks can arrive out of order. Place them with metadata.phase and metadata.chunk_order, and don't assume the chunk with progress: 100 is the last one you receive.
  • One envelope can carry thousands of messages. Expect large bodies.

When the business declines

If the business chooses not to share its history on the phone, you get one history event with no messages. The error is in history[].errors[], with code 2593109:

{
  "id": "evt_9b3d5f7a1c2e4b6d8f0a1c2b3e4d5f6a",
  "field": "history",
  "createdAt": "2026-11-01T14:40:02.123Z",
  "pipes": {
    "appId": "app_123",
    "poolNumberId": "pn_123",
    "media": {}
  },
  "whatsapp": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "15550001111",
      "phone_number_id": "123456789012345"
    },
    "history": [
      {
        "errors": [
          {
            "code": 2593109,
            "title": "History sync is turned off by the business",
            "message": "History sync is turned off by the business",
            "error_data": { "details": "History sync is turned off by the business" }
          }
        ]
      }
    ]
  }
}

The history can't be requested again for that number.

Media in history

Media in history arrives as type: "media_placeholder", with no media ID, so it can't be downloaded from that event. For media from the last 14 days, Meta then sends a follow-up history event whose whatsapp.messages[] (with no history wrapper) carries the media. PipesBot downloads it and lists it in pipes.media, keyed by Meta's media ID, as for any v2 media. See API v2 envelope. Older media is not sent.

These follow-ups don't open the 24-hour customer service window: they are old messages, not new ones.

Contacts

Contacts arrive as smb_app_state_sync events: first the current list, then a new event whenever the business adds or removes a contact in the app.

{
  "id": "evt_2c4e6a8b1d3f4a5c7e9b0d1c2f3a4b5e",
  "field": "smb_app_state_sync",
  "createdAt": "2026-11-01T14:40:09.321Z",
  "pipes": {
    "appId": "app_123",
    "poolNumberId": "pn_123",
    "media": {}
  },
  "whatsapp": {
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "15550001111",
      "phone_number_id": "123456789012345"
    },
    "state_sync": [
      {
        "type": "contact",
        "contact": {
          "full_name": "Sheena Nelson",
          "first_name": "Sheena",
          "phone_number": "5511987654321"
        },
        "action": "add",
        "metadata": { "timestamp": "1792800000" }
      }
    ]
  }
}

action is add or remove. Upsert contacts by phone_number, and on remove delete the one you stored for that phone_number. Edits can arrive out of order: keep the metadata.timestamp of the last change you applied to each phone_number, and ignore an event older than that, so an old add doesn't bring back a removed contact.

Delivery and handling

History and contact events go to your webhook and your WebSocket connection like other v2 events, with one difference: they are never put in the offline queue. If neither your webhook nor a WebSocket connection accepts one, PipesBot answers Meta with an error and Meta sends it again later. Set a webhook URL, so a closed WebSocket doesn't hold up the import.

  • Never reply to these events. History messages are old, and a contact list is not a conversation. Check field before any reply logic.
  • Deduplicate deliveries on the envelope id (see Deduplicate events). Then upsert history messages by message ID (wamid...) instead of dropping repeats: a media follow-up has the same wamid as its placeholder and adds the media to it. Contacts have no message ID: upsert by phone_number.
  • Store first, process later. Save the raw body, answer 200 quickly, and parse it in a background job. A single chunk can be very large: raise your server's request body limit (Express defaults to 100 KB, see Build a platform).
  • Don't depend on order. Apply history by chunk_order and timestamp, and contact edits by metadata.timestamp.
function handleEnvelope(envelope: { field: string; whatsapp: any }) {
  if (envelope.field === "history" || envelope.field === "smb_app_state_sync") {
    enqueueForImport(envelope); // store the raw envelope, process in a job, never reply
    return;
  }
  // handle messages, statuses, echoes, ...
}

Next steps

On this page