# 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`.

## Examples

### cURL

```bash
# 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
```

### Node.js

```javascript
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

```php
<?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"]);
```

### Python

```python
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"]
```

## Notes

- **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).