← Back to Blog
product-update coexistence byon api openclaw

What's New in PipesBot: Coexistence History Import, a Numbers API and App Mode for OpenClaw

Ler em português →

Short version: when a customer connects a number they already use in the WhatsApp Business app (Coexistence), PipesBot can now ask WhatsApp for that number’s chat history and contacts and deliver them to your webhook. You can also list every number connected to your App with GET /v1/numbers, including the metadata you attached when you created the onboarding link. The OpenClaw channel plugin gained an App mode for BYON numbers, with a trusted-senders list, and the dashboard now shows announcements and a What’s new feed.

Last week’s sandbox send limit, the Webhooks tab, 7-day webhook retention and the new dashboard look are covered in last week’s post.

Why Coexistence matters more now

Two recent changes from Meta make Coexistence (one number used in the WhatsApp Business app and through the API at the same time) the default path for many businesses:

More customers will arrive with a number that already has years of conversations on it. This week’s work is about bringing that context to your agent.

Import chat history and contacts on Coexistence numbers

Until now, the “share chat history” choice a business made during Embedded Signup was ignored. Now PipesBot acts on it.

Turn it on

  • Per App: in the dashboard, under Settings, there are two switches, Import chat history and Import contacts. Both are off by default and are available on API v2 Apps only.
  • Per onboarding link: POST /v1/apps/token accepts the optional booleans importHistory and importContacts. When present, they override the App switches for that link, in either direction (false turns off an import the App has on). A value that isn’t a boolean returns 400.
  • The number.onboarded webhook now reports the effective importHistory and importContacts values for that number.

What you receive

  • History arrives as history events through the v2 webhook contract, in chunks, with a progress value. If the business declines on the phone, you get one history event with error code 2593109 and no messages. Media in the history arrives as placeholders first, followed by the media itself.
  • Contacts arrive as smb_app_state_sync events (add / remove).
  • The Numbers page in the dashboard shows the import state with badges such as “Importing history”, “History imported” and “History not shared”.

Limits to know

  • It only applies to Coexistence numbers connected after you turn it on.
  • WhatsApp allows the import once per number, within 24 hours of connecting, and the business has to agree on their phone. Temporary errors from Meta are retried inside that window.
  • These events are not queued for offline delivery, so set a webhook URL on the App before you turn imports on.
  • History is past conversation, so your agent should store it and never reply to it.

The details, payload examples and fixtures are in the Coexistence docs.

List your numbers: GET /v1/numbers

Until now, you learned about a customer’s number only from the number.onboarded webhook or the onboarding redirect. If you missed that event, you had no way to rebuild the list.

  • GET /v1/numbers returns the BYON numbers on your App, oldest first, with cursor pagination (limit defaults to 50, max 100; the response is { data, nextCursor }). Numbers still pending registration are included.
  • GET /v1/numbers/{numberId} returns a single number. It returns 404 NUMBER_NOT_FOUND for a number that belongs to another App or is a sandbox number.
  • Each number has numberId, phoneNumber, displayName, status (active, pending, needs_pin, blocked, token_invalid or inactive), mode (cloud_api or coexistence), metadata and connectedAt.
  • It needs an App key (ak_). A sandbox key (pk_) gets 403 BYON_ONLY.

Onboarding metadata on each number

The metadata you pass when you create an onboarding link is now stored with the number and returned by GET /v1/numbers, so you can map each number back to your own customer without depending on the webhook. It is {} when the link had no metadata, and null for numbers connected before this change or added from the dashboard.

status comes from our own records and never calls Meta. For quality rating and messaging tier, keep using GET /v1/pool-numbers/{id}/health. See Listing numbers in the docs.

OpenClaw channel: App mode with trusted senders

The pipes-bot-channel plugin for OpenClaw, version 0.2.0, now accepts App keys (ak_) as well as sandbox keys (pk_):

  • The key picks the mode. pk_ keeps working exactly as before. ak_ connects through API v2 to your BYON numbers.
  • Trusted senders (allowFrom). A sandbox number only talks to the person who activated it, but anyone can message a BYON number. In App mode, the plugin only passes messages from senders on the allowFrom list to your agent: phone numbers in any format, or BSUIDs. Messages from anyone else are dropped, and an empty list drops everything.
  • One number per connection, if you want. The optional poolNumberId limits a connection to a single number.
  • Messages you send from the WhatsApp Business app on a Coexistence number (echoes) are ignored, duplicates are filtered, and failed sends are reported back.

Install or update with openclaw plugins install @pipes.bot/pipes-bot-channel. The README covers the App mode settings.

Announcements in the dashboard

The dashboard at app.pipes.bot can now show product announcements as banners or pop-ups, and there is a What’s new feed in the header with a badge for unread items.

Docs

  • Docs reorganized for integrators. The docs now start from connecting your customers’ numbers (BYON), with new pages on building a platform, billing and a go-live checklist. Shared numbers moved to a Sandbox section. Existing URLs did not change.
  • Coexistence history and contacts import is documented, with payload examples.
  • GET /v1/numbers is documented, and media download with an App key (GET /v1/media/download/{mediaId}) now works for your App’s own numbers.
  • Fix: phoneNumber in number.onboarded is in Meta’s display format (+1 555-123-4567), not E.164. The examples now show it correctly.

Try it

Everything above is live now. Turn on the import switches in your App’s Settings before your next Coexistence customer connects, and call GET /v1/numbers to check which customers are connected. The docs have the full reference.