ВойтиНачать бесплатный пробный период
easyCoexistence Официальные API

Как импортировать историю чатов и контакты приложения 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 их контакты и историю чатов сразу, как только ваш вебхук настроен.

180 days

Как далеко назад доходят вебхуки history, отсчитывая от момента подключения бизнеса к Cloud API.

24 hours

Срок после подключения, в течение которого контакты и история сообщений бизнеса должны быть синхронизированы.

2593109

Код ошибки в вебхуке history, когда бизнес отключил передачу истории в приложении WhatsApp Business.

Once

Как часто может выполняться каждая синхронизация; для повтора клиенту нужно отключить номер и заново пройти Embedded Signup.

100

Значение 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 с причиной.

1Connect sessionwebhook_url and webhook_verify_token set before the link goes out
2Customer connectsScans the QR code and chooses whether to share chats
3Contactssmb_app_state_sync, a change per contact
4Chatshistory chunks, the newest phase first
5Completemetadata.progress reaches 100

Что передают вебхуки контактов?

Поле 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. Групповые чаты не входят.

A history webhook, as Meta sends it
{
  "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, отбрасывается.

Как настроить

  1. 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.
  2. Create the connect sessionPOST /connect-sessions with webhook_url and webhook_verify_token, then send the customer the url it returns.
  3. Store contacts and chatsUpsert contacts from smb_app_state_sync, and insert history messages keyed on their id, sorted by chunk_order.
  4. 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 часов, история номера не будет импортирована никогда.
Настройка с EasyCoexistence

История идёт прямо на ваш эндпоинт без промежуточного хранения, и каждый номер мониторится круглосуточно. От US$ 9 до US$ 0,75 за подключение в месяц, цена снижается по мере добавления подключений, первые 3 дня бесплатно.

Часто задаваемые вопросы

Как далеко назад уходит импорт истории чатов WhatsApp?

До 180 дней до подключения номера к Cloud API, включая переписки один на один в обоих направлениях.

Импортируются ли групповые чаты?

Нет. Meta не передаёт сообщения, которые являются частью группового чата.

Попадут ли старые чаты клиента в мой вебхук?

Да, до 180 дней переписок один на один, отправляются один раз в течение 24 часов после подключения, если бизнес в приложении выбрал передачу.

Сохраняет ли easyCoexistence копию импортированных чатов?

Нет. Meta отправляет историю прямо на ваш webhook_url, как и новые сообщения, и ничего не сохраняется по пути.

Читайте дальше

Как получать сообщения клиентов WhatsApp и комментарии соцсетей по вебхукуВебхук на каждое подключение: сообщения WhatsApp напрямую от Meta, защита секретом в URL, а комментарии и DM соцсетей подписаны X-EC-Signature.Как узнать, что подключение клиента к WhatsApp или соцсети отключилосьСобытия connection.* и channel.*: тело запроса, причины вроде PRIMARY_INACTIVITY, X-EC-Signature, повторы около 33 часов и дедупликация по id.Как получить API-токены клиентов для WhatsApp, Instagram и TikTokПоля учётных данных для номера WhatsApp и аккаунтов в соцсетях, а также как работают обновление токенов и token_ready.Вебхук historyОдноразовая передача истории чатов на номере Coexistence приходит в этом поле. Что приходит, когда и почему только один раз.Вебхук smb_app_state_syncСинхронизация контактов из приложения WhatsApp Business приходит в этом поле. Что она передаёт и почему не входит в историю сообщений.Как подключить WhatsApp к API без потери чатовПодключите номер WhatsApp Business к Cloud API без потери переписки. Узнайте, что остаётся в телефоне и что синхронизируется.

Подключите первый канал за две минуты.

Не нужно ждать проверок платформ. Подключите WhatsApp, Instagram, TikTok или другой канал, затем попросите ИИ опубликовать пост, ответить или подготовить отчёт и посмотрите, как он работает.

  • 3 дня бесплатно
  • Отмена в любой момент
  • Только официальные API
  • Мониторинг 24/7

Проверено по состоянию на