# Ricevere la cronologia di Coexistence

`GET /v1/connections/:id/history`

Quando colleghi un numero in Coexistence, prima di aprire la finestra di Meta, l'attività risponde se vuole che le consegniamo la cronologia delle sue conversazioni: **fino a 6 mesi, i messaggi di entrambe le parti, senza gruppi**. La cronologia resta sul suo telefono: lì non si cancella né si sposta nulla. **La scelta è adesso**: Meta condivide la cronologia una sola volta, quando si collega il numero, e se la risposta è no, dopo non si può più richiedere. Se la risposta è sì, la chiediamo a Meta (nell'app WhatsApp Business bisogna accettare di condividerla), la conserviamo **cifrata fino a 7 giorni** e te la consegniamo in due modi, quello che arriva prima:

· **Via webhook:** eventi `history.batch` con fino a 500 messaggi ciascuno (nel formato di Meta, come `message.received`, con `contact` e `direction`), firmati come gli altri, e un `history.completed` quando non resta nulla. Passano da una coda separata che non rallenta i tuoi messaggi in tempo reale: una cronologia grande può richiedere ore.
· **Tramite l'API**, se non hai ancora un webhook: GET /v1/connections/{id}/history ti dà i blocchi in ordine (`limit` da 1 a 5, `after` = il `nextCursor` precedente). Leggere non cancella: quando hai salvato un blocco, confermalo con POST /v1/connections/{id}/history/{batchId}/ack.

Ogni blocco **si cancella appena viene consegnato** (il tuo 2xx o la tua conferma); ciò che non viene consegnato si cancella comunque dopo 7 giorni. Se il quinto giorno restano blocchi non consegnati, avvisiamo UNA volta per numero (pannello ed email) con la data in cui verranno cancellati. Non conta come traffico né consuma quota. Se l'attività ha risposto di no, non chiediamo nulla a Meta. Se un giorno restassimo senza spazio, smetteremmo di conservare nuova cronologia e te lo diremmo con `history.dropped`.

## Esempi

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

## Note

- **Foto, audio e documenti arrivano senza il file** (`type: "media_placeholder"`, senza `id`). Meta invia il file solo degli ultimi 14 giorni, in un messaggio a parte con lo stesso `id` di messaggio e il suo `image.id` (o `.audio.id`, …), e non sempre lo invia: se arriva, scaricalo con GET /v1/media/{id} entro i 7 giorni. Ognuno porta il nostro `connect.media`: `{ status: "available", available_until }` se è arrivato con il suo `id`, oppure `{ status: "unavailable", reason }` con `older_than_14_days` (Meta non lo invia mai), `meta_failed` (Meta non è riuscita a recuperarlo dal telefono; quel 131052 non ti arriva più come `message.status`) o `pending` (può arrivare in un altro blocco).
- **Deduplica per `batchId`**: un blocco può arrivarti due volte (per esempio, se riavviamo nel mezzo di una consegna).
- Se integri con i link di onboarding, manda `historyDelivery: true|false` quando crei il link se l'hai già chiesto al tuo cliente; altrimenti glielo chiede la pagina.
- `history.synced` continua ad arrivare come riepilogo di ogni blocco di Meta (`progress: 100` = Meta ha finito).