History synchronization

When you activate Coexistence, you can import the message history from your WhatsApp Business number to Positus. The import is asynchronous and messages arrive at your webhook in the same format as normally received messages.

How to trigger synchronization

Make a POST request to the endpoint below. No request body is required.

POST https://api.positus.global/v2/whatsapp/numbers/{NUMBER_ID}/onboarding-smb-app/sync-message-history
Authorization: Bearer <your-token>

Parameters:

{NUMBER_ID} — ID of the WhatsApp number already activated with Coexistence.

The import can be triggered only once per onboarding, within the 24-hour window after Coexistence activation. The server only confirms receipt of the request; messages are delivered later, across multiple webhooks.

What you receive

Each message from history is delivered to your webhook in the same format as a normally received message in Positus — the envelope { "contacts": [...], "messages": [...] }. You receive one webhook per message from history; your existing webhook handler already processes these messages without modification.

{
  "contacts": [
    {
      "profile": { "name": "Contact name" },
      "wa_id": "5511999999999"
    }
  ],
  "messages": [
    {
      "from": "5511999999999",
      "id": "wamid.xyz",
      "timestamp": "1739230955",
      "type": "text",
      "text": { "body": "message from history" },
      "history_context": { "status": "READ" }
    }
  ]
}

This is the same format described in Webhook. The difference is that history messages include the additional field history_context, indicating the state that the message had in the app. Internal progress metadata of the import (phase, batch order) are not passed to your webhook.

Message fields

Field	Description
`from`	Number of the message sender
`id`	Unique message ID (wamid)
`timestamp`	Date/time of original send (Unix timestamp)
`type`	Message type: `text`, `media_placeholder`, `image`, `video`, `audio`, `document` etc.
`text.body`	Message body (for `type: "text"`)
`history_context.status`	State that the message had in the app (see table below)

Values of `history_context.status`

Status	Meaning
`READ`	Message read
`PLAYED`	Media (audio/video) played
`DELIVERED`	Message delivered to device
`SENT`	Message sent to WhatsApp server
`PENDING`	Still awaiting send confirmation
`ERROR`	Send error

History coverage window

Meta makes history available in three phases, defining how far back messages are imported:

Phase	Period covered
Phase 0	Day 0 → Day 1 (last 24 hours)
Phase 1	Day 1 → Day 90
Phase 2	Day 90 → Day 180

Messages older than 180 days are not imported. You don’t need to handle these phases: they only determine the scope of the import — messages arrive at your webhook one by one, as described above.

Two-stage media

Older media messages (more than ~14 days old) arrive in two stages:

First, a message with type: "media_placeholder" — without media content.
Then, a new webhook delivers the same message with the actual media content.

Wait for the second stage before considering the media complete. The media_placeholder signals that media exists, but has not yet been delivered.

History rejected by business

If history sharing is disabled in the WhatsApp Business app, Meta rejects the import (error 2593109 — “History sync is turned off by the business”).

When history is rejected, the import does not proceed and no messages are delivered. The user must enable history sharing in the WhatsApp Business app and redo the onboarding.

Next steps

Introduction to CoEx — concept and eligibility.
Contact Synchronization — import the contact list.
Webhook — complete message envelope format.

​History synchronization

​How to trigger synchronization

​What you receive

​Message fields

​Values of history_context.status

​History coverage window

​Two-stage media

​History rejected by business

​Next steps

History synchronization

How to trigger synchronization

What you receive

Message fields

Values of `history_context.status`

History coverage window

Two-stage media

History rejected by business

Next steps