Receive the Coexistence conversation history

GET /v1/connections/:id/history

When a number is connected through Coexistence, before Meta's window opens, the business answers whether it wants us to deliver its conversation history: up to 6 months, the messages from both sides, no groups. The history stays on the phone: nothing there is deleted or moved. If it answers yes, we request it from Meta (possible only once, at connection; Meta also asks the business in the app whether to share it), keep it encrypted for up to 7 days and deliver it to you in two ways, whichever happens first:

· By webhook: history.batch events with up to 500 messages each (in Meta's shape, like message.received, with contact and direction), signed like every other event, and a history.completed when nothing is left. They go through a separate queue that never delays your live messages: a large history can take hours.
· By API, if you don't have a webhook yet: GET /v1/connections/{id}/history returns the batches in order (limit 1 to 5, after = the previous nextCursor). Reading does not delete: once you stored a batch, confirm it with POST /v1/connections/{id}/history/{batchId}/ack.

Each batch is deleted as soon as it is delivered (your 2xx or your confirmation); what is not delivered is deleted after 7 days anyway. It is not traffic and does not consume your quota. If the business answered no, we request nothing from Meta. If we ever ran out of space, we stop storing new history and tell you with history.dropped.

# 1) read a page (reading does NOT delete)
curl "https://api.waiaconnect.com/v1/connections/conn_…/history?limit=1" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "data": [ { "batchId": "hb_…", "count": 500, "messages": [ … ] } ], "hasMore": true, "nextCursor": 1 }

# 2) once you stored it, confirm it → deleted from WAIA Connect at once
curl -X POST "https://api.waiaconnect.com/v1/connections/conn_…/history/hb_…/ack" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# 3) next page: ?after=1 (the nextCursor) — until hasMore is false

const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY" };
let after = 0, hasMore = true;
while (hasMore) {
  const page = await (await fetch(`https://api.waiaconnect.com/v1/connections/conn_…/history?limit=1&after=${after}`, { headers: H })).json();
  for (const batch of page.data) {
    await saveMessages(batch.messages);            // your storage; dedupe on batch.batchId
    await fetch(`https://api.waiaconnect.com/v1/connections/conn_…/history/${batch.batchId}/ack`, { method: "POST", headers: H });
  }
  hasMore = page.hasMore;
  after = page.nextCursor;
}

<?php
$h = ["Authorization: Bearer wc_live_YOUR_API_KEY"];
$after = 0;
do {
  $ch = curl_init("https://api.waiaconnect.com/v1/connections/conn_…/history?limit=1&after=" . $after);
  curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $h]);
  $page = json_decode(curl_exec($ch), true);
  foreach ($page["data"] as $batch) {
    save_messages($batch["messages"]); // your storage; dedupe on batchId
    $ack = curl_init("https://api.waiaconnect.com/v1/connections/conn_…/history/" . $batch["batchId"] . "/ack");
    curl_setopt_array($ack, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => $h]);
    curl_exec($ack);
  }
  $after = $page["nextCursor"];
} while ($page["hasMore"]);

import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}
after, has_more = 0, True
while has_more:
    page = requests.get("https://api.waiaconnect.com/v1/connections/conn_…/history", headers=H, params={"limit": 1, "after": after}).json()
    for batch in page["data"]:
        save_messages(batch["messages"])  # your storage; dedupe on batchId
        requests.post(f"https://api.waiaconnect.com/v1/connections/conn_…/history/{batch['batchId']}/ack", headers=H)
    has_more, after = page["hasMore"], page["nextCursor"]

Deduplicate on batchId: a batch can reach you twice (for example, if we restart in the middle of a delivery).

If you integrate with onboarding links, send historyDelivery: true|false when you create the link if you already asked your customer; otherwise the page asks them.

history.synced still arrives as a summary of each Meta chunk (progress: 100 = Meta finished).