Смена администраторов группы WhatsApp через API: promote и demote

Чтобы изменить роль администратора группы WhatsApp через UnifyPort, отправьте POST /v1/accounts/{account_id}/groups/members с group_id, LID участника в member_id и action: "promote" либо "demote". Один вызов выполняет одно действие над одним участником. Снятие прав администратора — не действие remove, удаляющее участника. Сначала прочитайте текущий состав группы и исключите её создателя из обычного сценария снятия прав.

Главное

• Выбирайте аккаунт для обмена сообщениями, группу и участника вместе: отображаемое имя не является идентификатором.
• Используйте LID, полученный в peer_id списка участников, а не значение, составленное из номера телефона.
• Различайте member, admin и superadmin до включения кнопки изменения роли.
• После запроса перечитайте состояние. При тайм-ауте не отправляйте противоположное действие автоматически.

Определите нужный переход роли

Официальная справка WhatsApp об администраторах описывает снятие прав и указывает, что создателя группы нельзя удалить: он остаётся администратором, пока сам не выйдет. Интеграция через API не меняет это правило.

Таблица ниже — рекомендуемая политика приложения, а не гарантия принятия каждого запроса платформой.

Наблюдаемая роль	Намерение оператора	Решение приложения
member	Назначить администратором	Предложить promote после проверки прав
admin	Оставить участником, снять права	Предложить demote с подтверждением
superadmin	Снять права создателя	Остановить сценарий и объяснить ограничение
Уже имеет нужную роль	Повторить изменение	Обновить интерфейс без нового запроса
Данные отсутствуют, неизвестны или неполны	Всё равно изменить роль	Перечитать список или проверить вручную

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

Выберите участника по актуальному списку

Вызовите получение участников беседы для выбранного аккаунта. Передайте conversation_id группы, обработайте страницы через cursor и сохраните peer_id и role выбранной записи. Документированные роли — member, admin, superadmin; последняя обозначает владельца или создателя.

Пример запроса на чтение ниже использует переменные окружения, заполненные на сервере по реальному выбору:

curl --get \
  "https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/conversations/members" \
  -H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
  --data-urlencode "conversation_id=${WHATSAPP_GROUP_ID}" \
  --data-urlencode "type=group" \
  --data-urlencode "limit=50"

Если data.has_more равно true, продолжите с возвращённым data.next_cursor. Отсутствие человека на первой странице не доказывает, что он вышел. Сохраняйте LID без изменений: не выводите его из телефона, имени или идентификатора участника другого формата из события.

Перед отправкой проверьте право оператора управлять этим аккаунтом и группой, а также необходимые полномочия подключённого WhatsApp-аккаунта внутри группы. Доступ к API рабочего пространства сам по себе не даёт прав администратора группы. API-ключ должен оставаться на сервере.

Отправляйте одно явное изменение

Справочник управления участниками определяет четыре действия: add, remove, promote, demote. Для смены роли используйте только два последних и единственное поле member_id, а не массив member_ids из процедуры одобрения заявок.

Этот пример JavaScript лишь собирает тело запроса из ранее выбранной записи. Он не проверяет полномочия и не выполняет сетевой вызов:

function roleChangeBody(groupId, selectedMember, action) {
  const expectedRole = { promote: 'member', demote: 'admin' };
  if (!Object.hasOwn(expectedRole, action) ||
      selectedMember?.role !== expectedRole[action]) {
    throw new Error('Refresh membership before changing this role');
  }
  if (!groupId || !selectedMember?.peer_id?.endsWith('@lid')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  return {
    group_id: groupId,
    member_id: selectedMember.peer_id,
    action
  };
}

Отправьте JSON с сервера на документированный эндпоинт с заголовком X-Api-Key. Проверка окончания строки — только локальная защита от ошибки, не подтверждение личности или полномочий. В окне подтверждения явно показывайте группу, участника и действие. Не определяйте цель по текущей первой строке обновляющегося списка.

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

Проверяйте результат, не предполагая транзакцию

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

Рекомендуемые меры:

1. Выполняйте изменения приложения последовательно для одного аккаунта, группы и участника.
2. Проверяйте роль непосредственно перед отправкой: другой администратор мог изменить её после открытия диалога.
3. При тайм-ауте оставьте результат неопределённым и проверьте текущий список. Не повторяйте запрос и не отправляйте обратное действие автоматически.
4. Не считайте передачу обязанностей между несколькими людьми атомарной. Сначала подтвердите наблюдаемую роль нового администратора, затем отдельно решайте вопрос о снятии прав с прежнего.

Стандартное событие group.updated может содержать в data.changes[] записи с kind: "promoted" или "demoted" и members[]. Используйте его как повод сверить состояние, а не как гарантированную квитанцию для каждого запроса. Идентификаторы участников из события не обязательно подходят в качестве LID для следующей записи. При обработке webhook следуйте справочнику подписи и доставки: проверяйте подпись до доверия к телу и учитывайте дубликаты и нарушение порядка доставки.

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

demote удаляет участника из группы?

Нет. Снятие роли и удаление участника — разные действия. Кнопка «Снять права администратора» не должна вызывать remove.

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

Не предлагайте это в данном сценарии. По правилам WhatsApp создатель остаётся администратором до собственного выхода. В списке UnifyPort эта роль представлена как superadmin.

Можно изменить нескольких администраторов одним запросом?

Не через этот эндпоинт: он принимает один member_id и одно действие. Если приложение запускает пакет операций, результат каждой нужно учитывать отдельно.

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

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

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

• WhatsApp: управление администраторами группы
• UnifyPort: управление участниками группы
• UnifyPort: стандартные события webhook