ΣύνδεσηΞεκινήστε δωρεάν δοκιμή
Meta Tech Provider

Δώστε μνήμη στον πράκτορα AI σας: έξι μήνες συνομιλιών WhatsApp και επαφών

Σε αριθμό που έχει συνδεθεί μέσω Coexistence, η Meta μπορεί να στείλει στον server σας, μία φορά, τις επαφές της εφαρμογής και έως 180 ημέρες ατομικών συνομιλιών, αν έχει αποθηκευτεί άμεσος προορισμός webhook μέσα σε 24 ώρες από τη σύνδεση και η επιχείρηση το επιτρέψει στην εφαρμογή. Τα τμήματα μπορεί να φτάσουν εκτός σειράς, και η πρόοδος 100 σημαίνει το τέλος. Αποθηκεύστε τα μηνύματα ανά id, καταχωρίστε τα άτομα με βάση το BSUID και τροφοδοτήστε τον πράκτορα με τις πρόσφατες απαντήσεις.

Το easyCoexistence συνδέει τον αριθμό μέσω της ροής Coexistence της Meta και, όταν αποθηκεύσετε το endpoint σας ως άμεσο προορισμό webhook μέσα σε 24 ώρες, ζητά από τη Meta μία φορά τις επαφές και έως 180 ημέρες συνομιλιών, που πηγαίνουν κατευθείαν στον server σας.

180 days

Πόσο πίσω φτάνει ο συγχρονισμός ιστορικού από την ενσωμάτωση· ο πίνακας χαρακτηριστικών της Meta τον ονομάζει τους τελευταίους 6 μήνες.

24 hours

Ο χρόνος μετά την ενσωμάτωση για να ζητηθούν επαφές και ιστορικό· κάθε αίτημα μπορεί να γίνει μία μόνο φορά.

100

Η τιμή metadata.progress που σημαίνει ότι ο συγχρονισμός ιστορικού ολοκληρώθηκε· η Meta λέει ότι η φάση από μόνη της δεν αρκεί.

2593109

Κωδικός σφάλματος σε webhook ιστορικού όταν η επιχείρηση απενεργοποίησε την κοινή χρήση ιστορικού στην εφαρμογή WhatsApp Business.

3 phases

Η φάση 0 καλύπτει την ημέρα 0 έως 1 πριν από την ενσωμάτωση, η φάση 1 τις ημέρες 1 έως 90, η φάση 2 τις ημέρες 90 έως 180.

3 MB

Το μεγαλύτερο payload webhook που στέλνει η Meta, το οποίο ορίζει το όριο μεγέθους σώματος που χρειάζεται το endpoint σας.

Τι φέρνει η εισαγωγή και τι μένει πίσω;

Δύο ροές, και οι δύο από την εφαρμογή WhatsApp Business στο τηλέφωνο. Οι επαφές φτάνουν ως τα webhooks smb_app_state_sync, με μία εγγραφή ανά επαφή και ενέργεια add ή remove, ενώ το ίδιο πεδίο αναφέρει και τις επαφές που η επιχείρηση προσθέτει, επεξεργάζεται ή αφαιρεί αργότερα στην εφαρμογή. Οι συνομιλίες φτάνουν ως τα webhooks ιστορικού: ατομικές συνομιλίες έως 180 ημέρες πριν από την ενσωμάτωση, και προς τις δύο κατευθύνσεις, με την κατάσταση παράδοσής τους. Όσα δεν έρχονται περιγράφονται παρακάτω, οπότε η μνήμη που βασίζεται στην εισαγωγή δεν πρέπει να τα περιμένει.

Contactsfull_name, first_name, phone_number, user_id (BSUID), username
One-to-one chatsUp to 180 days, sent and received, grouped by conversation
Message statushistory_context.status: sent, delivered, read, played, pending or error
Mediamedia_placeholder without the file; separate webhooks carry ids for media from about the last 14 days
Group chatsNot included
App toolsLabels, quick replies, greeting and away messages stay on the phone

Πώς εξασφαλίζετε ότι η εισαγωγή φτάνει στον 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.

history webhook value, trimmed
{
  "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 καταγράφει ποιος μίλησε. Ευρετηριάστε ανά άτομο και χρόνο, αφού ο πράκτορας ζητά τις τελευταίες απαντήσεις ενός ατόμου.

memory.sql (PostgreSQL)
-- 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: ingest and recall (Node.js, pg)
// 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.

Πώς να το ρυθμίσετε

  1. 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.
  2. Connect the numberRun the connection from the dashboard, and accept sharing chat history when the WhatsApp Business app asks.
  3. 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.
  4. Store chunks until progress 100Insert contacts and messages as they come; the event log shows history_sync_requested once the request went to Meta.
  5. 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 υπάρχει ακόμη.
Κάντε το με EasyCoexistence

Το αίτημα καταγράφεται στο ημερολόγιο συμβάντων του αριθμού, και ο αριθμός παρακολουθείται 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 και BSUID: τι αλλάζει στα webhooks του Cloud APIΠώς τα ονόματα χρήστη αλλάζουν τα webhooks του Cloud API: το BSUID στο user_id, πότε λείπει ο αριθμός, η απάντηση με recipient και το Coexistence.Δημιουργία AI agent για WhatsApp σε Node.js και Python, με αριθμό CoexistenceΚώδικας Node.js και Python για WhatsApp AI agent σε αριθμό Coexistence: έλεγχος υπογραφής, παύση όταν απαντά άνθρωπος, αφαίρεση διπλοτύπων, έλεγχος παραθύρου.Πώς φτάνουν τα μηνύματα WhatsApp στον διακομιστή σας: άμεσα ή διαχειριζόμενα, και επαλήθευση της υπογραφήςΆμεσα: η Meta στέλνει στον διακομιστή σας. Διαχειριζόμενα: αυτοματισμοί και υπογεγραμμένη προώθηση στο Forward URL. Payload, X-EC-Signature και επαναδοκιμές.Το webhook historyΗ εφάπαξ μεταφορά συνομιλιών σε αριθμό Coexistence παραδίδεται στο πεδίο history. Τι φτάνει, πότε και γιατί γίνεται μόνο μία φορά.Το webhook smb_app_state_syncΟ συγχρονισμός επαφών από την εφαρμογή WhatsApp Business φτάνει σε αυτό το πεδίο. Τι περιέχει και γιατί είναι ξεχωριστός από το history.Τι μπορεί να δει και να κάνει ένα AI στο WhatsApp σας; Δεδομένα, αποθήκευση και αποσύνδεσηΤι μπορεί να διαβάσει και να κάνει ένα AI στο WhatsApp Business σας, τι φτάνει στον πάροχό του, τι αποθηκεύεται και πώς διακόπτεται η πρόσβαση.

Έτοιμοι να ξεκινήσετε;

Ρυθμίστε το WhatsApp Coexistence σε λίγα λεπτά, όχι σε μήνες. Η εφαρμογή συνεχίζει να λειτουργεί στο τηλέφωνο.

Ξεκινήστε δωρεάν δοκιμή

Επαληθεύτηκε στις