Δώστε μνήμη στον πράκτορα AI σας: έξι μήνες συνομιλιών WhatsApp και επαφών
Σε αριθμό που έχει συνδεθεί μέσω Coexistence, η Meta μπορεί να στείλει στον server σας, μία φορά, τις επαφές της εφαρμογής και έως 180 ημέρες ατομικών συνομιλιών, αν έχει αποθηκευτεί άμεσος προορισμός webhook μέσα σε 24 ώρες από τη σύνδεση και η επιχείρηση το επιτρέψει στην εφαρμογή. Τα τμήματα μπορεί να φτάσουν εκτός σειράς, και η πρόοδος 100 σημαίνει το τέλος. Αποθηκεύστε τα μηνύματα ανά id, καταχωρίστε τα άτομα με βάση το BSUID και τροφοδοτήστε τον πράκτορα με τις πρόσφατες απαντήσεις.
Το easyCoexistence συνδέει τον αριθμό μέσω της ροής Coexistence της Meta και, όταν αποθηκεύσετε το endpoint σας ως άμεσο προορισμό webhook μέσα σε 24 ώρες, ζητά από τη Meta μία φορά τις επαφές και έως 180 ημέρες συνομιλιών, που πηγαίνουν κατευθείαν στον server σας.
Πόσο πίσω φτάνει ο συγχρονισμός ιστορικού από την ενσωμάτωση· ο πίνακας χαρακτηριστικών της Meta τον ονομάζει τους τελευταίους 6 μήνες.
Ο χρόνος μετά την ενσωμάτωση για να ζητηθούν επαφές και ιστορικό· κάθε αίτημα μπορεί να γίνει μία μόνο φορά.
Η τιμή metadata.progress που σημαίνει ότι ο συγχρονισμός ιστορικού ολοκληρώθηκε· η Meta λέει ότι η φάση από μόνη της δεν αρκεί.
Κωδικός σφάλματος σε webhook ιστορικού όταν η επιχείρηση απενεργοποίησε την κοινή χρήση ιστορικού στην εφαρμογή WhatsApp Business.
Η φάση 0 καλύπτει την ημέρα 0 έως 1 πριν από την ενσωμάτωση, η φάση 1 τις ημέρες 1 έως 90, η φάση 2 τις ημέρες 90 έως 180.
Το μεγαλύτερο payload webhook που στέλνει η Meta, το οποίο ορίζει το όριο μεγέθους σώματος που χρειάζεται το endpoint σας.
Τι φέρνει η εισαγωγή και τι μένει πίσω;
Δύο ροές, και οι δύο από την εφαρμογή WhatsApp Business στο τηλέφωνο. Οι επαφές φτάνουν ως τα webhooks smb_app_state_sync, με μία εγγραφή ανά επαφή και ενέργεια add ή remove, ενώ το ίδιο πεδίο αναφέρει και τις επαφές που η επιχείρηση προσθέτει, επεξεργάζεται ή αφαιρεί αργότερα στην εφαρμογή. Οι συνομιλίες φτάνουν ως τα webhooks ιστορικού: ατομικές συνομιλίες έως 180 ημέρες πριν από την ενσωμάτωση, και προς τις δύο κατευθύνσεις, με την κατάσταση παράδοσής τους. Όσα δεν έρχονται περιγράφονται παρακάτω, οπότε η μνήμη που βασίζεται στην εισαγωγή δεν πρέπει να τα περιμένει.
Πώς εξασφαλίζετε ότι η εισαγωγή φτάνει στον server σας;
Ορίστε το endpoint ώστε να είναι ενεργό πριν συνδεθεί ο αριθμός, και μετά αποθηκεύστε το ως άμεσο προορισμό webhook του αριθμού μέσα σε 24 ώρες από τη σύνδεση: στη σελίδα του αριθμού, στο «Δρομολόγηση εισερχόμενων μηνυμάτων προς το δικό σας webhook», με το set_webhook_destination από τον AI σας ή ως webhook_url σε συνεδρία Partner API connect. Η αποθήκευση είναι αυτό που κάνει το easyCoexistence να ζητήσει από τη Meta τον συγχρονισμό, πρώτα τις επαφές και μετά το ιστορικό, μία φορά ανά ενσωμάτωση. Το αίτημα και οι κωδικοί αιτήματος της Meta εμφανίζονται στο ημερολόγιο συμβάντων του αριθμού ως history_sync_requested.
Η επιχείρηση πρέπει να συμφωνήσει στην κοινή χρήση ιστορικού όταν η εφαρμογή το ζητήσει κατά τη σύνδεση. Ένας αριθμός του οποίου τα μηνύματα περνούν μέσω του easyCoexistence («Μέσω του easyCoexistence» στην κάρτα «Πού πηγαίνουν τα εισερχόμενα μηνύματα»), ακόμη και με Forward URL, δεν παίρνει εισαγωγή, επειδή το αίτημα γίνεται μόνο για άμεσο προορισμό. Αν χρειαστείτε αργότερα automations, κάντε την αλλαγή αφού τελειώσει η εισαγωγή.
Πώς φτάνουν τα τμήματα του ιστορικού;
Εκτός σειράς, σε φάσεις που ξεκινούν από τα πιο πρόσφατα μηνύματα και πηγαίνουν πίσω: η φάση 0 καλύπτει την τελευταία ημέρα πριν από την ενσωμάτωση, η φάση 1 έως την ημέρα 90 και η φάση 2 έως την ημέρα 180. Ταξινομήστε με το metadata.chunk_order αν η σειρά έχει σημασία, και θεωρήστε το metadata.progress = 100 ως το τέλος, αφού η Meta σημειώνει ότι η φάση δεν δείχνει ότι μια φάση ολοκληρώθηκε. Το id μιας συνομιλίας είναι ο αριθμός τηλεφώνου του πελάτη, που λείπει όταν δεν μπορεί να κοινοποιηθεί, και το context της περιλαμβάνει wa_id, user_id και username. Ένα μήνυμα που έστειλε η επιχείρηση έχει στο from τον αριθμό της επιχείρησης και ένα πεδίο to.
{
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "16315550142", "phone_number_id": "106540352242922" },
"history": [{
"metadata": { "phase": 1, "chunk_order": 2, "progress": 55 },
"threads": [{
"id": "5511987654321",
"context": { "wa_id": "5511987654321", "user_id": "BR.13491208655302741918" },
"messages": [
{
"from": "5511987654321",
"from_user_id": "BR.13491208655302741918",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYFDNBMDhFN0QxRjM2QTk4RTU2RTY0AA==",
"timestamp": "1789912800",
"type": "text",
"text": { "body": "Can I pick up the cake on Saturday?" },
"history_context": { "status": "read" }
},
{
"from": "16315550142",
"to": "5511987654321",
"id": "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABEYEjQ2RDhGMkE3QjEwQzNFOTFBMgA=",
"timestamp": "1789913100",
"type": "text",
"text": { "body": "Yes, from 9 am. See you then!" },
"history_context": { "status": "read" }
}
]
}]
}]
}Πώς πρέπει να αποθηκεύεται η μνήμη ενός πράκτορα;
Αρκούν δύο πίνακες. Τα άτομα καταχωρίζονται με βάση το BSUID, το user_id που η Meta προσθέτει στις επαφές, στις συνομιλίες και στα μηνύματα, με τον αριθμό τηλεφώνου δίπλα, επειδή ένας χρήστης με username μπορεί να φτάσει χωρίς αυτόν· η δική της αναφορά λέει να χρησιμοποιείτε το user_id για να αναγνωρίζετε μια επαφή. Τα μηνύματα ταυτοποιούνται με το wamid τους, ώστε η εισαγωγή, τα ζωντανά webhooks και οι επαναδοκιμές της ίδιας παράδοσης να γίνονται μία γραμμή, και μια σημαία from_business καταγράφει ποιος μίλησε. Ευρετηριάστε ανά άτομο και χρόνο, αφού ο πράκτορας ζητά τις τελευταίες απαντήσεις ενός ατόμου.
-- One row per person. Key on the BSUID (user_id); keep the phone number beside it.
create table wa_contacts (
user_key text primary key, -- user_id (BSUID) when present, else the phone number
wa_id text, -- phone number in digits, when Meta shares it
username text,
name text, -- full_name from the app's address book
removed boolean not null default false,
updated_at timestamptz not null default now()
);
-- One row per message. The wamid makes history, live events and retries collapse.
create table wa_messages (
id text primary key, -- messages[].id
user_key text not null,
from_business boolean not null,
type text not null, -- text, image, media_placeholder...
body text not null, -- the text, a caption, or a [type] placeholder
sent_at timestamptz not null,
source text not null -- history | live | echo
);
create index wa_messages_by_user on wa_messages (user_key, sent_at desc);Πώς φορτώνετε τα τμήματα και τις επαφές σε αυτήν;
Με εισαγωγές ασφαλείς για επανάληψη, ώστε η σειρά και η επαναποστολή να παύουν να έχουν σημασία. Η ingestHistory διαβάζει μία αλλαγή ιστορικού: καταγράφει μια απόρριψη 2593109 και προχωρά, καταχωρίζει μια συνομιλία με context.user_id ή το id της, σημειώνει ένα μήνυμα ως της επιχείρησης όταν το from ισούται με metadata.display_phone_number, και αποθηκεύει ένα placeholder [type] όταν δεν υπάρχει κείμενο. Η ingestContacts κάνει upsert με βάση το user_id ή τον αριθμό τηλεφώνου και σημαίνει τις αφαιρεμένες επαφές αντί να διαγράφει τα μηνύματά τους. Καλέστε τις με change.value σε άμεσο προορισμό, ή με το value του σώματος όταν το event του forward είναι history ή smb_app_state_sync.
// memory.mjs: npm i pg. Feed it the value of a "history" or "smb_app_state_sync"
// change: change.value on a direct destination, delivery.value on a forward.
import pg from "pg";
const db = new pg.Pool(); // reads the PG* environment variables
export async function ingestHistory(value) {
const business = value.metadata?.display_phone_number; // digits, like messages[].from
for (const chunk of value.history ?? []) {
if (chunk.errors?.some((e) => e.code === 2593109)) {
console.log("The business turned off history sharing in the app"); // contacts still come
continue;
}
for (const thread of chunk.threads ?? []) {
const userKey = thread.context?.user_id ?? thread.id; // thread.id is the phone, when shared
for (const m of thread.messages ?? []) {
await db.query(
`insert into wa_messages (id, user_key, from_business, type, body, sent_at, source)
values ($1, $2, $3, $4, $5, to_timestamp($6), 'history')
on conflict (id) do nothing`,
[m.id, userKey, m.from === business, m.type,
m.text?.body ?? m[m.type]?.caption ?? `[${m.type}]`, Number(m.timestamp)]
);
}
}
const { phase, chunk_order, progress } = chunk.metadata ?? {};
console.log(`history: phase ${phase}, chunk ${chunk_order}, ${progress}%`);
if (Number(progress) === 100) console.log("Import complete; late chunks still insert safely");
}
}
export async function ingestContacts(value) {
for (const s of value.state_sync ?? []) {
const c = s.type === "contact" ? s.contact ?? {} : null;
const userKey = c && (c.user_id ?? c.phone_number);
if (!userKey) continue;
await db.query(
`insert into wa_contacts (user_key, wa_id, username, name, removed)
values ($1, $2, $3, $4, $5)
on conflict (user_key) do update set
wa_id = coalesce(excluded.wa_id, wa_contacts.wa_id),
username = coalesce(excluded.username, wa_contacts.username),
name = coalesce(excluded.name, wa_contacts.name),
removed = excluded.removed, updated_at = now()`,
[userKey, c.phone_number ?? null, c.username ?? null, c.full_name ?? c.first_name ?? null,
s.action === "remove"]
);
}
}
// A bounded memory for one person: who they are and their last turns, oldest first.
export async function memoryFor(userKey, turns = 20) {
const [{ rows: [contact] }, { rows }] = await Promise.all([
db.query("select name from wa_contacts where user_key = $1 and not removed", [userKey]),
db.query(
`select from_business, body from wa_messages
where user_key = $1 order by sent_at desc limit $2`, [userKey, turns]),
]);
const history = rows.reverse().map((r) => ({ role: r.from_business ? "assistant" : "user", content: r.body }));
while (history[0]?.role === "assistant") history.shift(); // open on the customer's turn
const who = contact?.name ? `The customer is ${contact.name}.` : "The customer is not in the address book.";
return { system: `${process.env.AI_INSTRUCTIONS ?? ""}\n${who}`.trim(), history };
}Πώς τροφοδοτείτε αυτή τη μνήμη στον πράκτορα;
Με περιορισμένο τρόπο, ποτέ όλα μαζί. Η memoryFor επιστρέφει το όνομα του ατόμου από το βιβλίο επαφών και τις τελευταίες 20 απαντήσεις του, από την παλαιότερη στη νεότερη, ξεκινώντας από μια απάντηση πελάτη όπως περιμένουν τα περισσότερα chat APIs· προσθέστε μια αποθηκευμένη σύνοψη των παλαιότερων συνομιλιών αν ο πράκτορας χρειάζεται περισσότερα. Έξι μήνες συνομιλιών σε κάθε prompt κοστίζουν τα tokens σε κάθε απάντηση και θάβουν την ερώτηση που γίνεται.
Για σύγκριση, το ενσωματωμένο βήμα Reply with AI διαβάζει το πολύ 20 προηγούμενα μηνύματα (10 εξ ορισμού), και το βήμα Call my webhook στέλνει τα τελευταία 10. Και τα δύο βασίζονται σε κείμενο που κρατιέται για τη διατήρηση που επιλέγει ο ιδιοκτήτης, 30, 90 ή 365 ημέρες (90 εξ ορισμού), από τη στιγμή που ενεργοποιήθηκαν τα automations, γι' αυτό οι έξι μήνες εισαγμένων συνομιλιών πρέπει να ζουν στη δική σας βάση δεδομένων.
Πώς μένει η μνήμη ενημερωμένη μετά την εισαγωγή;
Ο ίδιος προορισμός συνεχίζει να λαμβάνει ζωντανή κίνηση: μηνύματα από πελάτες, smb_message_echoes για απαντήσεις που γράφονται στην εφαρμογή και smb_app_state_sync όταν η επιχείρηση επεξεργάζεται τις επαφές της. Καταχωρίστε τα μέσα από τους ίδιους πίνακες με source live ή echo. Όταν ένας πελάτης αλλάζει αριθμό τηλεφώνου, η Meta στέλνει ένα μήνυμα συστήματος τύπου user_changed_number ή user_changed_user_id με previous_user_id, που σας λέει να μεταφέρετε τις γραμμές του στο νέο BSUID.
Αν ενεργοποιήσετε αργότερα automations, ο άμεσος προορισμός αφαιρείται. Προσθέστε το ίδιο URL ως Forward URL, διαβάστε τα event και value από κάθε υπογεγραμμένο POST και περιμένετε το progress 100 πριν από την αλλαγή· αλλιώς τα υπόλοιπα τμήματα φτάνουν μόνο μέσω εκείνου του forward.
Πώς να το ρυθμίσετε
- Put the endpoint onlineIt must return hub.challenge as plain text on Meta's GET handshake when hub.verify_token matches, accept POST bodies of a few megabytes and answer 200 fast.
- Connect the numberRun the connection from the dashboard, and accept sharing chat history when the WhatsApp Business app asks.
- Save the destination within 24 hoursOn the number's page, under Route incoming messages to your own webhook, fill Webhook URL (with a long random path) and Verify token, then Save; or ask your AI to call set_webhook_destination.
- Store chunks until progress 100Insert contacts and messages as they come; the event log shows history_sync_requested once the request went to Meta.
- Switch modes only afterwardsIf you want automations, choose Through easyCoexistence in the card Where incoming messages go and add the same URL as the Forward URL.
Συνηθισμένα λάθη
- Αποθήκευση του προορισμού τη δεύτερη ημέρα. Ο συγχρονισμός ζητείται μόνο μέσα σε 24 ώρες από τη σύνδεση, οπότε ένα endpoint που αποθηκεύεται αργότερα ξεκινά μόνο με τα ζωντανά μηνύματα.
- Ενεργοποίηση automations πριν η πρόοδος φτάσει 100. Ο άμεσος προορισμός αφαιρείται αμέσως, και τα επόμενα τμήματα φτάνουν σε εσάς μόνο αν έχει ήδη οριστεί Forward URL.
- Η φάση 2 θεωρείται τέλος της εισαγωγής. Μόνο το metadata.progress = 100 δηλώνει ότι ο συγχρονισμός ολοκληρώθηκε, και τα τμήματα δεν παραδίδονται με σειρά.
- Μνήμη με κλειδί μόνο τον αριθμό τηλεφώνου. Τα id συνομιλιών και οι επαφές χάνουν τον αριθμό όταν ένας χρήστης με username δεν μπορεί να τον κοινοποιήσει, ενώ το user_id υπάρχει ακόμη.
Το αίτημα καταγράφεται στο ημερολόγιο συμβάντων του αριθμού, και ο αριθμός παρακολουθείται 24/7 στη συνέχεια. Από US$ 9 έως US$ 0.75 ανά αριθμό τον μήνα, με μείωση όσο προσθέτετε αριθμούς, και δωρεάν δοκιμή των πρώτων 3 ημερών.
Συχνές ερωτήσεις
Μπορεί η εισαγωγή να τρέξει δεύτερη φορά;
Μόνο με νέα ενσωμάτωση. Η Meta επιτρέπει ένα αίτημα ανά ενσωμάτωση, οπότε ο αριθμός πρέπει να αποσυνδεθεί και να ξανασυνδεθεί, και τότε οι συνομιλίες φτάνουν ξανά· η εισαγωγή με βάση το id μηνύματος εμποδίζει τη δεύτερη φορά να προσθέσει οτιδήποτε διπλό.
Κρατά το easyCoexistence αντίγραφο των εισαχθέντων συνομιλιών;
Όχι. Το ιστορικό και οι επαφές πηγαίνουν από τη Meta κατευθείαν στο endpoint σας και δεν αποθηκεύονται εξ ορισμού. Για έναν αριθμό με automations ενεργά, το easyCoexistence κρατά το κείμενο των μηνυμάτων για το διάστημα που επιλέγετε, 30, 90 ή 365 ημέρες (90 εξ ορισμού), και η οθόνη Συνομιλίες το εμφανίζει· οι προωθημένες παραδόσεις κρατιούνται έως 7 ημέρες, και τα αρχεία εκτέλεσης 30 ημέρες.
Πόσο μεγάλα μπορούν να γίνουν τα payloads;
Ένα μόνο webhook της Meta μπορεί να φέρει έως 3 MB, και ένας πολυσύχναστος αριθμός στέλνει πολλά τμήματα ιστορικού. Αυξήστε το όριο σώματος του framework σας (το Express έχει προεπιλογή 100 kb) και επιβεβαιώστε τη λήψη πριν γράψετε στη βάση δεδομένων.
Χρειάζεται ο πράκτορας την εισαγωγή για να λειτουργήσει;
Όχι. Χωρίς αυτήν, η μνήμη ξεκινά από το πρώτο μήνυμα μετά τη σύνδεση και μεγαλώνει από τη ζωντανή κίνηση. Η εισαγωγή έχει σημασία όταν οι παλιές συνομιλίες πρέπει να επηρεάζουν τις απαντήσεις από την πρώτη μέρα, όπως η τελευταία παραγγελία ενός επιστρέφοντα πελάτη.
Συνεχίστε την ανάγνωση
Έτοιμοι να ξεκινήσετε;
Ρυθμίστε το WhatsApp Coexistence σε λίγα λεπτά, όχι σε μήνες. Η εφαρμογή συνεχίζει να λειτουργεί στο τηλέφωνο.
Ξεκινήστε δωρεάν δοκιμήΕπαληθεύτηκε στις