Дайте ИИ-агенту память: шесть месяцев чатов и контактов WhatsApp
На номере, подключённом через Coexistence, Meta может один раз отправить на ваш сервер контакты из приложения и до 180 дней личных переписок, если прямой адрес вебхука сохранён в течение 24 часов после подключения и компания разрешила это в приложении. Фрагменты могут прийти не по порядку, а прогресс 100 означает конец. Сохраняйте сообщения по id, храните людей по BSUID и передавайте агенту последние реплики.
easyCoexistence подключает номер через процесс Coexistence от Meta и, если вы сохраните свой эндпоинт как прямой адрес вебхука в течение 24 часов, один раз запрашивает у Meta контакты и до 180 дней переписок, которые идут сразу на ваш сервер.
Как далеко назад синхронизация истории захватывает данные от подключения; в таблице функций Meta это последние 6 месяцев.
Время после подключения, когда можно запросить контакты и историю; каждый запрос можно сделать только один раз.
Значение metadata.progress, при котором синхронизация истории считается завершённой; Meta говорит, что одной фазы для этого недостаточно.
Код ошибки в вебхуке истории, когда компания отключила передачу истории в приложении WhatsApp Business.
Фаза 0 охватывает 0–1 день до подключения, фаза 1 дни 1–90, фаза 2 дни 90–180.
Наибольший размер полезной нагрузки, которую отправляет Meta вебхуку; от него зависит лимит размера тела запроса на вашем эндпоинте.
Что приносит импорт, а что не переходит?
Два потока, оба из приложения WhatsApp Business на телефоне. Контакты приходят как вебхуки smb_app_state_sync, по одной записи на контакт с действием add или remove; то же поле сообщает о контактах, которые компания позже добавляет, меняет или удаляет в приложении. Чаты приходят как вебхуки history: личные переписки за до 180 дней до подключения, в обоих направлениях, со статусом доставки. Что не переносится, перечислено ниже, поэтому память, построенная на импорте, не должна этого ожидать.
Как убедиться, что импорт доходит до вашего сервера?
Сделайте эндпоинт доступным до подключения номера, затем сохраните его как прямой адрес вебхука номера в течение 24 часов после подключения: на странице номера в разделе «Пересылать входящие сообщения на свой вебхук», через set_webhook_destination из вашего ИИ или как webhook_url в сессии подключения Partner API. Именно сохранение заставляет easyCoexistence запросить у Meta синхронизацию, сначала контактов, затем истории, один раз за каждое подключение; запрос и идентификаторы запросов Meta появляются в журнале событий номера как history_sync_requested.
Компания должна согласиться на передачу истории, когда приложение спросит об этом при подключении. Номер, сообщения которого идут через easyCoexistence («Через easyCoexistence» в карточке «Куда идут входящие сообщения»), даже с Forward URL, импорта не получает, потому что запрос делается только для прямого адреса. Если позже понадобятся автоматизации, переключитесь после завершения импорта.
Как приходят фрагменты истории?
Не по порядку, в фазах, которые идут от самых новых сообщений назад: фаза 0 охватывает последний день до подключения, фаза 1 до 90 дня, фаза 2 до 180 дня. Сортируйте по metadata.chunk_order, если порядок важен, и считайте концом metadata.progress = 100, поскольку Meta отмечает, что фаза не показывает, завершена ли она. Идентификатор переписки это номер телефона клиента, который не указывается, если им нельзя поделиться, а поле 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 может прийти без номера; справка Meta прямо советует использовать user_id для идентификации контакта. Сообщения храните по их wamid, чтобы импорт, живые вебхуки и повторные доставки одного и того же сообщения сводились к одной строке, а флаг 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, и сохраняет заглушку [type], если текста нет. ingestContacts делает вставку с обновлением по user_id или номеру телефона и помечает удалённые контакты, не удаляя их сообщения. Вызывайте их с change.value при прямом адресе или с value из тела запроса, когда событие пересылки имеет тип 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 реплик, от старых к новым, начиная с реплики клиента, как ожидают большинство API чатов; добавьте сохранённое резюме старых переписок, если агенту нужно больше. Шесть месяцев переписки в каждом промпте стоят токенов при каждом ответе и заглушают вопрос, на который нужно ответить.
Для сравнения: встроенный шаг «Ответить с помощью ИИ» читает не более 20 предыдущих сообщений (по умолчанию 10), а шаг «Вызвать мой вебхук» отправляет последние 10. Оба опираются на текст, который хранится столько, сколько выберет владелец: 30, 90 или 365 дней (по умолчанию 90), с момента включения автоматизаций, поэтому шесть месяцев импортированных переписок должны жить в вашей собственной базе данных.
Как память остаётся актуальной после импорта?
Тот же адрес продолжает получать живой трафик: сообщения от клиентов, smb_message_echoes для ответов, набранных в приложении, и smb_app_state_sync, когда компания меняет свои контакты. Вставляйте их теми же таблицами с source live или echo. Когда клиент меняет номер телефона, Meta отправляет системное сообщение типа user_changed_number или user_changed_user_id с previous_user_id; это сигнал перенести его строки на новый BSUID.
Если позже включить автоматизации, прямой адрес удаляется. Добавьте тот же URL как Forward URL, читайте event и value из каждого подписанного POST-запроса и дождитесь progress 100 перед переключением, иначе оставшиеся фрагменты придут только через пересылку.
Как настроить
- 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 часов после подключения, поэтому эндпоинт, сохранённый позже, получает только живые сообщения.
- Включение автоматизаций до того, как прогресс достигнет 100. Прямой адрес удаляется сразу, и последующие фрагменты дойдут до вас, только если Forward URL уже задан.
- Принятие фазы 2 за конец импорта. Только metadata.progress = 100 говорит, что синхронизация завершена, а фрагменты не доставляются по порядку.
- Привязка памяти только к номеру телефона. Идентификаторы переписок и контакты теряют номер телефона, когда пользователь с username не может им поделиться, но user_id остаётся.
Запрос записывается в журнал событий номера, а после этого номер находится под мониторингом 24/7. От US$ 9 за подключённый номер в месяц, до US$ 0,75 по мере добавления номеров, с бесплатным пробным периодом 3 дня.
Часто задаваемые вопросы
Можно ли запустить импорт повторно?
Только через новое подключение. Meta разрешает один запрос на подключение, поэтому номер нужно отключить и подключить снова, после чего чаты придут снова; вставка по id сообщения не даст добавить что-либо дважды.
Хранит ли easyCoexistence копию импортированных чатов?
Нет. История и контакты идут от Meta прямо на ваш эндпоинт и по умолчанию не сохраняются. Для номера с включёнными автоматизациями easyCoexistence хранит текст сообщений в течение выбранного вами срока, 30, 90 или 365 дней (по умолчанию 90), и экран «Разговоры» его показывает; пересланные доставки хранятся до 7 дней, а журналы запусков 30 дней.
Насколько большими могут быть полезные нагрузки?
Один вебхук Meta может содержать до 3 МБ, а у активного номера приходит много фрагментов истории. Увеличьте лимит тела запроса в вашем фреймворке (Express по умолчанию принимает 100 kb) и отправьте подтверждение до записи в базу данных.
Нужен ли агенту импорт для работы?
Нет. Без него память начинается с первого сообщения после подключения и растёт за счёт живого трафика. Импорт важен, когда прошлые переписки должны влиять на ответы с первого дня, например на последний заказ вернувшегося клиента.
Читайте дальше
Готовы начать?
Настройте WhatsApp Coexistence за несколько минут, а не месяцев. Приложение продолжит работать на телефоне.
Начать бесплатный пробный периодПроверено по состоянию на