Синхронизация имени аккаунта WhatsApp через account.profile.updated

Чтобы синхронизировать собственное имя подключённого аккаунта WhatsApp, обрабатывайте событие UnifyPort account.profile.updated. Поле data.profile.display_name отдаёт предпочтение названию компании, а затем использует push-имя. Обновляйте представление профиля аккаунта, а не контакт клиента, внутреннюю метку или состояние соединения. Документированный источник — события имени WhatsApp; это не универсальный поток изменений профиля для всех каналов.

Главное

• Определяйте аккаунт по рабочему пространству, provider и account_id, а не по имени.
• Храните конфигурационное поле name отдельно от публичного имени платформы.
• full_sync обозначает источник профиля, а не завершение восстановления истории сообщений.
• Уведомление о профиле не подтверждает авторизацию или работающее соединение.

Определите, какое имя показывает интерфейс

В списке аккаунтов поддержки можно показывать и внутреннюю рабочую метку, и публичное имя канала. Переименование не должно незаметно менять ответственного, маршрутизацию или права доступа.

Значение или событие	Смысл	Рекомендуемое место
name в конфигурации аккаунта	Метка, управляемая через настройки аккаунта	Внутренний список аккаунтов
data.profile.display_name	Публичное имя из профиля платформы	Отдельная строка имени канала
data.profile.business_name / push_name	Компоненты имени из документации события	Дополнительные сведения профиля
contact.updated	Имена контакта в адресной книге	Представление контакта клиента
account.status.updated	Авторизация или состояние runtime	Индикатор соединения

Руководство по синхронизации имён контактов относится к клиенту, а не к собственному аккаунту. Не используйте один обработчик для обеих сущностей. Имя отправителя клиентского сообщения тоже не доказывает переименование вашего аккаунта.

Get account возвращает конфигурацию и provider_profile отдельно. Этот запрос подходит для начального заполнения экрана. Если публичного имени нет, покажите отсутствие данных, а не выдавайте внутреннюю метку за имя, полученное от платформы.

Что означает account.profile.updated

Ниже приведена структура из справочника события. Значения — документальный пример, не запись реального клиента:

{
  "id": "evt_profile_7e91d2c4",
  "type": "account.profile.updated",
  "provider": "whatsapp",
  "account_id": "acc_8c21d0",
  "occurred_at": "2026-08-28T09:51:51Z",
  "data": {
    "account": { "provider_account_ref": "provider_account_example" },
    "profile": {
      "display_name": "Example Business",
      "business_name": "Example Business",
      "push_name": "Example Account"
    },
    "event": {
      "kind": "account_profile_updated",
      "source": "self_rename"
    }
  }
}

Используйте готовое display_name, не вводя конкурирующее правило приоритетов. Если название компании имеет приоритет, изменение push_name может не изменить отображаемое имя.

Документация различает два значения data.event.source:

• self_rename — подключённый аккаунт изменил собственное имя.
• full_sync — профиль получен из снимка полной синхронизации.

Ни одно значение не указывает человека, выполнившего действие. Не создавайте на его основе вымышленную запись об операторе в журнале аудита. full_sync также не подтверждает синхронизацию всех сообщений, контактов, изображений и других данных аккаунта.

Создайте отдельную проекцию карточки аккаунта

Рекомендуемый порядок реализации:

1. Настройте подписку. Добавьте account.profile.updated в нужный набор событий, сохранив остальные подписки и настройки подписи. В руководстве по фильтрам разобраны явный список и wildcard.
2. Проверьте и сохраните событие. По контракту доставки проверяйте шестнадцатеричную HMAC-SHA256 от X-Device-Timestamp, точки и исходного тела с ключом signing_secret, а также свежесть времени. Возвращайте 2xx после надёжного сохранения аутентифицированного события.
3. Найдите существующий аккаунт. Используйте рабочее пространство получателя, provider и account_id из конверта. Новое имя не должно создавать второй аккаунт или переносить диалоги.
4. Меняйте только представление профиля. Не затрагивайте внутренние метки, имена клиентов, авторизацию и runtime. Отображайте имя как текст, не как HTML.
5. Сохраняйте происхождение локально. Свяжите проекцию с ID события, временем возникновения и source. Это данные приложения, не новые поля API.

Этот JavaScript извлекает имя из уже аутентифицированного события. Он не реализует хранилище, упорядочивание или полный HTTP-приёмник:

function profileNameCandidate(event) {
  if (event.type !== 'account.profile.updated' ||
      event.provider !== 'whatsapp') return null;
  if (typeof event.account_id !== 'string' || !event.account_id) {
    throw new Error('Missing account identity');
  }
  const name = event.data?.profile?.display_name;
  if (typeof name !== 'string') {
    throw new Error('Profile display name needs review');
  }
  return { accountId: event.account_id, displayName: name };
}

Ключи результата — переменные приложения. Если имя отсутствует или имеет неверный тип, сохраните событие для разбора вместо замены всего профиля значениями по умолчанию. Для пустой строки задайте локальную политику отображения «имя недоступно». Не переносите сюда правила очистки полей события контакта.

Согласуйте старые события и начальное чтение

Устраняйте повторы обычных событий по ID. Порядок доставки не гарантирован: применяйте события профиля по occurred_at, используя ID как детерминированный критерий при равном времени. Запись о обработке и изменение проекции фиксируйте вместе.

Общая версия профиля для REST-чтения и Webhook здесь не документирована. Медленный начальный запрос не должен перезаписывать событие, применённое во время его выполнения. Сериализуйте инициализацию и обработку событий либо используйте чтение как базу, после которой применяются накопленные события. При противоречии помечайте данные для сверки, не обещая точного восстановления причинного порядка на платформе.

UnifyPort предоставляет неофициальный интерфейс. Это событие не является командой изменения нативного профиля, полным архивом или гарантией повторного получения пропущенных данных. Общий конверт не означает поддержку этого события в LINE, Zalo, Telegram или whatsapp-protocol.

Вопросы и ответы

Почему push_name изменилось, а display_name — нет?

По документации сначала используется BusinessName, затем PushName. Проверьте компоненты имени, прежде чем считать неизменный экран ошибкой синхронизации.

Означает ли full_sync полную историю сообщений?

Нет. Это источник конкретного события профиля, а не подтверждение полноты или восстановления истории.

Нужно ли после события менять name через PATCH?

Не как автоматический шаг синхронизации. Это меняет конфигурацию аккаунта, а не только показывает полученное публичное имя. Редактирование внутренней метки должно оставаться отдельным явным действием.

Следующий шаг и источники

Реализуйте карточку по справочнику события профиля. Проверьте оба source, разные business- и push-имена, повторные и старые события, отсутствующее и пустое имя, задержку начального чтения. Контакты клиентов, внутренние метки и состояние соединения должны остаться прежними. Это предлагаемые проверки, а не результаты выполненных тестов.

Источники проверены 2026-11-05:

• UnifyPort: account.profile.updated
• UnifyPort: Get account
• UnifyPort: доставка Webhook