Закрепить чат или сообщение WhatsApp: какой API выбрать

Закрепите чат WhatsApp, чтобы его было проще найти в списке разговоров. Закрепите сообщение, чтобы выделить конкретный материал внутри разговора. Это разные операции. В интерфейсе, работающем через API, сначала определите объект: чату нужен идентификатор разговора, а сообщению — ещё и собственный ID. Для чужого сообщения следует явно указать отправителя.

Главное

• Закрепление чата меняет список разговоров подключённого аккаунта; закрепление сообщения выделяет содержимое внутри чата.
• В UnifyPort используются разные маршруты и разные способы отмены.
• У закрепления разговора нет параметра длительности. У закрепления сообщения есть необязательный duration_seconds.
• Поле pinned в conversation.updated относится к списку чатов, а не к отдельному сообщению.

Чем закрепление чата отличается от закрепления сообщения

В инструкции WhatsApp по отправке сообщений себе описано закрепление чата вверху списка. В инструкции по закреплению сообщения нужно выбрать конкретное сообщение и срок закрепления. Одинаковое название действия не означает одинаковый объект.

Задача	Объект	Чего это не означает
Быстро находить разговор с клиентом	Строка в списке чатов	Конкретное сообщение клиента тоже выделено
Выделить инструкцию в группе	Отдельное сообщение	Группа переместится наверх входящих
Назначить срочную задачу сотруднику	Заявка или очередь вашего приложения	Закрепление на платформе создаст ответственного и срок

Согласно справке WhatsApp, при закреплении сообщения в группе публикуется системное сообщение с указанием того, кто выполнил действие. Администраторы могут разрешать или запрещать участникам закреплять сообщения. Поэтому такую функцию нельзя представлять как личную закладку сотрудника. Справка также предупреждает: отсутствие истории может мешать участнику увидеть закреплённое сообщение. Закрепление не восстанавливает недоступный контент.

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

Выберите контракт UnifyPort по объекту

Ниже описан неофициальный интерфейс UnifyPort, а не Meta Cloud API.

Деталь	Закрепить разговор	Закрепить сообщение
Метод и маршрут	POST /v1/accounts/{account_id}/conversations/pin	POST /v1/messages/pin
Выбор аккаунта	account_id в URL	account_id в JSON
Объект в JSON	conversation_id	conversation_id, message_id; для чужого сообщения укажите sender_id
Выбор состояния	Маршрут означает закрепление	pinned: true закрепляет, pinned: false открепляет
Длительность	Параметра нет	При закреплении можно передать duration_seconds
Отмена	Отдельный маршрут открепления разговора	Тот же маршрут сообщения с pinned: false

Перед формированием запроса проверьте документацию по закреплению разговора, его откреплению и закреплению или откреплению сообщения.

Не переносите настройку срока из экрана приложения в API разговора. Аналогично, отправка pinned: false в маршрут закрепления разговора не является документированным способом отмены. Следуйте контракту конкретной операции.

В текущей матрице действий провайдеров закрепление и открепление разговоров поддерживается для WhatsApp и LINE, а закрепление сообщений — только для WhatsApp. Неподдерживаемая комбинация возвращает 501 unsupported_by_provider. Общий интерфейс не делает возможности каналов одинаковыми: наличие кнопки закрепления чата LINE не означает, что можно включить закрепление сообщения LINE.

Сохраняйте выбранное сообщение, а не последнее

Для сообщения, выбранного из сохранённого события message.received, документация задаёт такое соответствие:

• account_id из оболочки события → account_id;
• data.conversation.id → conversation_id;
• data.message.id → message_id;
• data.sender.id → sender_id.

При отсутствии sender_id операция закрепления сообщения использует сам подключённый аккаунт. Для сообщения другого участника укажите отправителя явно. В группе идентификатор разговора указывает на группу, а идентификатор отправителя — на автора. Их нельзя подменять друг другом.

Пока сотрудник подтверждает действие, сохраняйте выбранный объект. Новое входящее сообщение не должно заменять целевой ID. Перед запросом проверьте право сотрудника управлять выбранным аккаунтом обмена сообщениями и разговором.

У сообщения с цитатой есть ещё одна ловушка: ID родительского сообщения не равен собственному ID. Это разобрано в руководстве по ответам с цитированием WhatsApp. Для закрепления нужен ID выбранного сообщения, а не reply_token и не автоматически выбранный родитель.

Подтверждайте результат на правильном уровне

В обоих справочниках успешный ответ содержит data.ok: true. Храните объект запроса и фактический ответ отдельно от записи о нажатии кнопки. При тайм-ауте результат неизвестен: не показывайте подтверждённый успех и не отправляйте противоположную операцию как автоматическое исправление.

Справочник событий описывает conversation.updated с data.conversation.id и, при изменении закрепления, с data.pinned. Это локальное состояние списка чатов подключённого аккаунта. Оно не сообщает, какое сообщение закрепили внутри разговора.

Применяйте только присутствующие настройки. Например, событие отключения уведомлений без pinned не должно очищать сохранённое состояние закрепления. Считайте события наблюдениями, а не гарантией подтверждения каждого вызова API. В текущем публичном каталоге нет отдельного события закрепления сообщения, а матрица событий не указывает поддержку conversation.updated для LINE.

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

Закрепление не заменяет приоритет заявки

Допустим, команда закрепляет чат, пока клиент ждёт ответа. Это условный пример, не история клиента. Ответственный, срок и статус решения должны храниться в приложении. Открепление чата не должно автоматически закрывать заявку.

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

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

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

Закрепление чата закрепляет и последнее сообщение?

Нет. Операции используют разные объекты и разные API.

Можно передать duration_seconds при закреплении разговора?

В документированном контракте UnifyPort такого параметра нет. Он относится к закреплению сообщения.

Подтверждает ли pinned в conversation.updated закрепление сообщения?

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

Доступны ли обе операции для LINE через UnifyPort?

Текущая матрица поддерживает закрепление и открепление разговоров LINE, но не закрепление сообщений. Проверяйте каждое действие отдельно.

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

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

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

• WhatsApp: отправка сообщений себе
• WhatsApp: закрепление сообщения
• UnifyPort: закрепление и открепление сообщения
• UnifyPort: поддержка действий провайдерами