Zalo Official Account API или вебхук личного аккаунта: как принимать сообщения?

Если компании нужна официальная бизнес-страница и функции Zalo Official Account (OA), сначала стоит рассмотреть Zalo Official Account API. Если клиенты уже пишут в обычный аккаунт Zalo, а задача — передавать входящие сообщения в поддержку, CRM или AI-процесс, подписанный вебхук личного аккаунта может оказаться прямее. Главный критерий — какой именно аккаунт уже видит и использует клиент, а не длина списка функций.

Кратко

• Zalo определяет Official Account как официальный аккаунт бизнеса и включает создание, верификацию, настройку и эксплуатацию в путь OA.
• Официальная поверхность для разработчиков прямо называется Official Account API.
• UnifyPort подключает обычный аккаунт Zalo по QR-коду и доставляет входящие сообщения единообразными событиями вебхука.
• Официальный API подходит для функций OA, официальной поддержки и корпоративного контроля; неофициальный интерфейс — для сохранения существующего личного входящего канала.
• До подключения Slack, CRM или AI необходимо проверять подпись и сохранять события.

Чем отличаются Zalo OA API и вебхук личного аккаунта

На официальном сайте Zalo OA Official Account описывается как официальный аккаунт компании. Создание и верификация OA входят в предложенный платформой путь подключения. Соответствующая документация для разработчиков называется Official Account API.

Вебхук личного аккаунта начинается с другой модели. Команда авторизует уже существующий обычный аккаунт Zalo, а наблюдаемые в нём сообщения преобразуются в стандартные события для приложения. Авторизация Zalo в UnifyPort выполняется только по QR-коду: заранее предоставлять учётные данные разработчика Zalo не нужно, а идентичность определяется после сканирования.

Критерий	Zalo Official Account API	Вебхук личного аккаунта через UnifyPort
Идентичность для клиента	Zalo Official Account	Существующий обычный аккаунт Zalo
Начальная настройка	Создание и настройка OA для разработки	Создание messaging account Zalo и сканирование QR-кода
Входящая доставка	Модель API и вебхуков OA	Нормализованные события message.received
Несколько каналов	Отдельная реализация модели Zalo	Общая структура для Zalo, WhatsApp, LINE, Telegram, TikTok и X
Оптимальный сценарий	Нативные процессы OA и официальная поддержка	Входящая очередь на базе обычного аккаунта
Основной компромисс	Требования к идентичности и настройке OA	Контроль сессии и рисков неофициального интерфейса

Эти варианты решают близкие, но разные задачи. Универсального победителя нет.

Когда выбирать официальный OA

Официальный путь логичнее, если Zalo Official Account сам является частью требования. Например, клиент должен находить бренд через OA, операционная работа зависит от OA Manager либо закупкам и юридическому отделу нужны официальные отношения с платформой и канал эскалации.

Полезно сформулировать требование одной фразой: «Клиенты будут писать в наш Zalo Official Account, а процесс зависит от функций OA». Если это верно, сначала оценивайте официальный API. Неофициальный интерфейс не заменяет верификацию Zalo и весь набор продуктов, предназначенных для OA.

Когда подходит вебхук личного аккаунта

Другой типичный запрос звучит так: «Клиенты уже пишут в этот обычный аккаунт Zalo, а нам нужно направить сообщения в Slack, CRM или общую очередь поддержки». Менять знакомую клиентам идентичность только ради серверной интеграции может быть избыточно.

Последовательность из руководства по авторизации Zalo выглядит так:

1. Сначала зарегистрировать endpoint вебхука, чтобы у событий авторизации и входящих сообщений был получатель.
2. Создать messaging account Zalo с provider: zalo и auth_mode: qrcode.
3. Запустить QR-авторизацию и отсканировать код нужным аккаунтом Zalo.
4. После успеха обрабатывать события message.received, где data.message.direction равно inbound.
5. До разбора и маршрутизации проверять доставку с помощью signing_secret по контракту HMAC-SHA256.

Мультиканальная архитектура показана в материале об одном вебхуке для LINE, Zalo и X. Практический процесс разработки описан в руководстве по созданию приёмника Zalo с Claude Code.

Сначала спроектируйте входящий слой

Долгоживущим решением должен быть не выбор между Slack и CRM, а контракт событий между Zalo и этими инструментами. Получатель быстро подтверждает корректную доставку, сохраняет событие и только затем асинхронно запускает маршрутизацию.

Конверт события UnifyPort содержит id, type, provider, account_id, occurred_at и зависящий от типа объект data. Для входящего сообщения в data находятся conversation, sender и message. Для повторных доставок обычных событий используйте ID события и идемпотентную обработку. При этом сообщения нужно хранить самостоятельно: REST API для чтения истории сообщений и гарантированного воспроизведения пропущенных событий нет.

X-Device-Signature — шестнадцатеричная HMAC-SHA256 от строки, составленной из временной метки, точки и исходного тела запроса. Подпись проверяют по исходным байтам до разбора JSON. Полные правила подтверждения, повторной доставки и порядка событий находятся в документации доставки вебхуков.

Ограничения и компромиссы

Подключение обычного аккаунта зависит от действительности авторизованной сессии. Эксплуатационная инструкция должна отслеживать состояния авторизации и runtime, обрабатывать account.auth.required и при необходимости запрашивать у владельца повторное сканирование QR-кода. Доступность со стороны платформы также может различаться по аккаунтам и регионам.

Официальный OA использует отдельную бизнес-идентичность и модель разработчика. Для бренда это может быть обязательным условием, но для команды, уже обслуживающей клиентов через обычный аккаунт, такой путь не всегда короче.

Сначала определите видимую клиенту идентичность, затем перечислите действительно необходимые функции платформы и только после этого выбирайте интеграцию.

Частые вопросы

Можно ли использовать Zalo Official Account API с личным аккаунтом?

Официальная поверхность называется Official Account API и построена вокруг Zalo Official Account. Для обычного аккаунта нужна другая модель интеграции.

Можно ли получать сообщения обычного аккаунта Zalo через вебхук?

Да, через неофициальный интерфейс UnifyPort. После QR-авторизации входящие сообщения доставляются событиями message.received.

Нужны ли учётные данные разработчика Zalo для QR-процесса UnifyPort?

Согласно документации, заранее они не нужны. Идентичность определяется, когда целевой аккаунт сканирует QR-код.

Что лучше для мультиканальной поддержки?

Если один получатель должен обрабатывать Zalo вместе с WhatsApp, LINE, Telegram, TikTok или X, единый вебхук обычно проще сопровождать. Если обязательны идентичность OA и функции OA, выбирайте официальный API.

Подходит ли неофициальный интерфейс всем командам?

Нет. Приоритет официальной верификации, поддержки, корпоративного контроля или функций OA означает, что лучше выбрать официальный путь.

Следующий шаг

Начните с руководства по авторизации Zalo, затем реализуйте проверку подписи по документации вебхуков и только после этого подключайте Slack, CRM или AI-процесс.

Официальные источники

Проверено 2026-08-23:

• Zalo Official Account
• Zalo for Developers: Official Account API