Руководство October 23, 2026

Как изменить название, описание и аватар группы WhatsApp через API

Чтобы изменить название, описание или аватар группы WhatsApp через UnifyPort, отправьте POST /v1/accounts/{account_id}/groups/update-info с group_id и хотя бы одним полем: name, description или avatar_url. Для этого endpoint нужны права администратора группы. Передавайте только намеренные изменения, затем снова прочитайте сведения о группе. Снимок, полученный при открытии редактора, не обязательно отражает текущее состояние.

Главное

Сведения о группе — не приватная метка в CRM. Покажите область действия перед сохранением.
Зафиксируйте выбранный аккаунт обмена сообщениями и ID группы на время редактирования.
Отправляйте небольшое явное изменение, а не весь ответ операции чтения.
Сверяйте поля отдельно: тайм-аут или отсутствие webhook не доказывает, что изменения не произошло.

Выберите поле, а не общее действие «Настройки»

Инструкция WhatsApp по изменению групп описывает редактирование в приложении. В инструкции по настройкам администратора также объясняется разрешение участникам редактировать настройки группы. Но настройка приложения не расширяет контракт UnifyPort: справочник Update group info явно требует прав администратора.

Задача	Поле запроса	Отдельная задача
Изменить название группы	`name`	Локальный псевдоним в рабочем интерфейсе
Изменить описание	`description`	Текст обращения или сообщения
Заменить изображение группы	`avatar_url`	Фото профиля участника

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

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

Открывайте редактор на основе свежих данных

Выберите группу через List groups под нужным аккаунтом, учитывая пагинацию. Сохраните возвращённый id: для группы conversation_id равен id. Название служит для отображения, а не для уникальной идентификации.

Затем вызовите Get group и храните в приложении отдельно:

Последние прочитанные значения.
Поля, которые оператор действительно изменил.
Значения, прочитанные после отправки запроса.

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

На экране подтверждения покажите аккаунт, группу и изменённые поля. API key должен оставаться на сервере; проверку прав оператора также выполняйте на сервере.

Отправляйте только намеренные изменения

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

async function updateGroupInfo({ apiKey, accountId, groupId, edits }) {
  if (!apiKey || !accountId || !groupId) {
    throw new Error('Missing credential or selected target');
  }
  const body = { group_id: groupId };
  for (const field of ['name', 'description', 'avatar_url']) {
    if (!Object.hasOwn(edits, field)) continue;
    const value = edits[field];
    if (typeof value !== 'string' || !value.trim()) {
      throw new Error('This editor accepts non-empty replacements only');
    }
    body[field] = value;
  }
  if (Object.keys(body).length === 1) return null;

  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/update-info`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

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

Документированный успешный ответ — 200 OK с data.ok: true. Проверяйте оба признака перед показом успеха. В рабочем клиенте также нужны обработка сетевых ошибок и ответов не в JSON, сохранение доступного request_id и исключение секретов из журналов. Пример приведён для пояснения и здесь не выполнялся.

Сверяйте поля вместо повторной отправки формы

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

В справочнике стандартных событий у group.updated предусмотрено несколько возможных элементов data.changes[]:

renamed содержит name.
description_changed содержит description.
WhatsApp avatar_changed содержит removed и необязательный picture_id, но не URL изображения.

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

При тайм-ауте отметьте результат как неопределённый и проверьте текущее состояние, прежде чем решать, что ещё нужно изменить. Не отправляйте автоматически старую многополевую форму и не восстанавливайте старый снимок. Публичная документация не предоставляет атомарного отката нескольких полей или предусловия версии. Отказы в правах со стороны провайдера возвращаются как update_group_info_failed; изучайте детали, поскольку этот код не означает единственную возможную причину.

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

Можно ли очистить описание или удалить аватар пустым значением?

Этот процесс на такое поведение не рассчитывает. Цитируемый endpoint не описывает соглашение об очистке. Не включайте соответствующие элементы управления до подтверждения контракта нужной операции.

Успешное чтение группы означает право редактирования?

Нет. Доступ к чтению, поддержка действия провайдером и права администратора — три отдельные проверки.

Нужно ли передавать все три поля?

Нет. Нужны group_id и хотя бы одно поддерживаемое поле изменения. Неизменённая форма не должна выполнять запись.

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

Реализуйте форму по Update group info. До включения проверьте изменение только названия, нетронутую форму, параллельную правку в WhatsApp, недоступное изображение, отказ в правах и тайм-аут. Это рекомендуемые проверки, а не отчёт о проведённых испытаниях.

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

UnifyPort API

Превратите интеграцию сообщений в стабильный продуктовый pipeline.

Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.

Получить API Key Открыть справочник API