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.

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

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