Как импортировать историю чатов и контакты приложения WhatsApp Business через API
Номер приложения WhatsApp Business, подключённый через Coexistence, может один раз передать в API существующие контакты и до 180 дней переписок один на один в течение 24 часов после подключения. Контакты приходят в вебхуках smb_app_state_sync, чаты в вебхуках history, порциями, упорядоченными по metadata.chunk_order. Значение metadata.progress, равное 100, означает, что импорт завершён. Передавать ли чаты, бизнес решает в приложении.
easyCoexistence подключает номера приложения WhatsApp Business ваших клиентов через Coexistence и запрашивает у Meta их контакты и историю чатов сразу, как только ваш вебхук настроен.
Как далеко назад доходят вебхуки history, отсчитывая от момента подключения бизнеса к Cloud API.
Срок после подключения, в течение которого контакты и история сообщений бизнеса должны быть синхронизированы.
Код ошибки в вебхуке history, когда бизнес отключил передачу истории в приложении WhatsApp Business.
Как часто может выполняться каждая синхронизация; для повтора клиенту нужно отключить номер и заново пройти Embedded Signup.
Значение progress, при котором синхронизация истории считается завершённой.
Как начинается импорт?
С адреса вебхуков, заданного для номера. Если номер подключается с уже указанным webhook_url в сессии подключения или если вы задали его через PUT /connections/{id}/webhook в течение 24 часов после подключения, easyCoexistence один раз запрашивает данные у Meta: POST /{phone_number_id}/smb_app_data с sync_type smb_app_state_sync для контактов, затем history для чатов, в порядке, описанном в документации Meta. В журнале событий номера фиксируются history_sync_requested со значениями request_id от Meta для поддержки или history_sync_failed с причиной.
Что передают вебхуки контактов?
Поле smb_app_state_sync с массивом state_sync в value. Каждый элемент имеет type contact, объект contact с full_name, first_name и phone_number, действие add или remove и metadata.timestamp. При remove имена не передаются. Meta продолжает присылать эти вебхуки и после импорта, каждый раз, когда бизнес добавляет, редактирует или удаляет контакт в приложении WhatsApp Business, поэтому ваша адресная книга остаётся в соответствии с телефоном.
Что передают вебхуки history?
Поле history с массивом history в value. Каждый элемент содержит metadata с phase, chunk_order и progress, а также threads: по одному на клиента. Идентификатор потока это номер клиента, а messages перечисляет переписку один на один, входящие и исходящие, при этом from показывает, кто отправил каждое сообщение. Сообщение содержит id, timestamp, type, содержимое под именем поля type и history_context.status, например READ или DELIVERED. Групповые чаты не входят.
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WABA_ID>",
"changes": [
{
"field": "history",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "<BUSINESS_NUMBER>", "phone_number_id": "<PHONE_NUMBER_ID>" },
"history": [
{
"metadata": { "phase": 1, "chunk_order": 3, "progress": 42 },
"threads": [
{
"id": "<CUSTOMER_NUMBER>",
"messages": [
{
"from": "<CUSTOMER_NUMBER>",
"id": "wamid.<ID>",
"timestamp": "1790726400",
"type": "text",
"text": { "body": "<MESSAGE_TEXT>" },
"history_context": { "status": "READ" }
}
]
}
]
}
]
}
}
]
}
]
}Как импортируются медиасообщения?
Сначала как заглушки. Медиасообщение приходит с type media_placeholder, без содержимого и без идентификатора медиа. Затем Meta присылает отдельные вебхуки history с идентификаторами медиа, но только для медиа, отправленных в течение 14 дней до подключения. Такие файлы нужно забрать у Meta с токеном клиента. Более старые медиа остаются заглушкой, поэтому показывайте их как недоступное вложение, а не оставляйте пустое место в переписке.
В каком порядке приходят порции и когда импорт завершён?
Не обязательно по порядку. Meta делит чаты на три фазы, от новых к старым: фаза 0 это день до подключения, фаза 1 уходит назад до 90 дня, фаза 2 до 180 дня. Порции могут прийти не по порядку, поэтому сортируйте их по metadata.chunk_order. metadata.progress это процент всей синхронизации, а 100 означает, что она завершена. Сам номер фазы не говорит о том, что фаза завершилась.
Что, если бизнес отказывается передавать чаты?
Во время подключения приложение WhatsApp Business спрашивает бизнес, передавать ли историю чатов. При отказе приходит вебхук history без сообщений и с массивом errors, где code равен 2593109, а заголовок: History sync is turned off by the business from the WhatsApp Business App. Контакты всё равно приходят, а новые сообщения идут как обычно с момента подключения номера.
Можно ли запустить импорт снова?
Не в том же подключении. Meta разрешает каждую синхронизацию один раз, в течение 24 часов после подключения, и повторно её воспроизвести нельзя. Чтобы запустить её снова, клиент должен отключить номер и подключить его заново; это считается новым подключением. Если адрес вебхуков у вас сохранён, easyCoexistence снова запросит импорт, поэтому дедуплицируйте по id каждого сообщения. Сюда относится и номер, вернувшийся после правила 14 дней.
Что должно быть готово до отправки ссылки на подключение?
Ваш эндпоинт, запущенный и отвечающий. Meta проверяет URL своим GET-рукопожатием при задании адреса вебхуков, и импорт запрашивается один раз сразу после этого. Если рукопожатие не проходит, номер всё равно подключится, но без адреса вебхуков. Причину объяснит last_error в сессии, а импорт не начнётся, пока вы не исправите эндпоинт и не зададите адрес через PUT /connections/{id}/webhook в пределах 24 часов. Номер без webhook_url вообще не получит импорт, потому что содержимое, отправленное в easyCoexistence, отбрасывается.
Как настроить
- Prepare the endpointDeploy an HTTPS URL with a random secret in its path that answers Meta's GET handshake and accepts bodies up to 3 MB.
- Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
- Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
- Wait for progress 100Treat the import as finished when metadata.progress reaches 100, or as declined when a history webhook carries error 2593109.
Распространённые ошибки
- Отклонение больших порций истории. Полезная нагрузка Meta может достигать 3 МБ, тогда как Express по умолчанию разбирает JSON только до 100 КБ, поэтому поднимите лимит, иначе порции не пройдут, и Meta будет повторять попытки их отправки.
- Обработка порций в порядке поступления. Они могут прийти не по порядку, поэтому сортируйте по metadata.chunk_order и дождитесь progress 100, прежде чем считать импорт завершённым.
- Вставка истории без дедупликации. Новые сообщения могут пересекаться с импортом, а повторное подключение запускает его снова, поэтому ключом для каждого сообщения сделайте его id.
- Отправка ссылки на подключение до того, как эндпоинт ответит на рукопожатие Meta. Адрес тогда не задаётся, и если вы не зададите его в течение 24 часов, история номера не будет импортирована никогда.
История идёт прямо на ваш эндпоинт без промежуточного хранения, и каждый номер мониторится круглосуточно. От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, первые 3 дня бесплатно.
Часто задаваемые вопросы
Как далеко назад уходит импорт истории чатов WhatsApp?
До 180 дней до подключения номера к Cloud API, включая переписки один на один в обоих направлениях.
Импортируются ли групповые чаты?
Нет. Meta не передаёт сообщения, которые являются частью группового чата.
Попадут ли старые чаты клиента в мой вебхук?
Да, до 180 дней переписок один на один, отправляются один раз в течение 24 часов после подключения, если бизнес в приложении выбрал передачу.
Сохраняет ли easyCoexistence копию импортированных чатов?
Нет. Meta отправляет историю прямо на ваш webhook_url, как и новые сообщения, и ничего не сохраняется по пути.
Читайте дальше
Подключите первый канал за две минуты.
Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.
- 3 дня бесплатно
- Отмена в любой момент
- Только официальные API
- Мониторинг 24/7
Проверено по состоянию на