Удаление участника группы WhatsApp через API: ID и проверка результата

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

Главное

• Удаление участника, снятие прав администратора, отклонение заявки и выход подключённого аккаунта из группы — разные действия.
• Выбирайте аккаунт обмена сообщениями, группу и участника вместе. Не составляйте LID из номера телефона.
• Требуйте подтверждения цели и решения; незнакомое имя не повод для автоматического удаления.
• Тайм-аут означает неопределённый результат, а не разрешение повторять запросы удаления.

Выберите действие по намерению

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

Намерение	Подходящее действие
Удалить уже состоящего в группе человека	Действие управления участниками remove
Оставить человека в группе, но снять права администратора	Отдельное действие demote
Отказать тому, кто ещё не вступил	Отклонить ожидающую заявку
Вывести из группы сам подключённый аккаунт	Выход из группы
Только скрыть строку в своём приложении	Локальное изменение интерфейса, не состава группы

Для снятия прав используйте руководство по смене роли администратора. Для кандидата на вступление — очередь рассмотрения заявок. Этим сценариям не нужна общая неоднозначная кнопка «Удалить».

Что показать перед подтверждением

Прежде чем включать удаление, вызовите список участников беседы для выбранного аккаунта. Передайте ID группы как conversation_id и укажите type=group. Продолжайте пагинацию по data.has_more и data.next_cursor, пока нужная проверка не завершена. Отсутствие человека на первой странице ещё ничего не доказывает.

Сохраните возвращённые peer_id, display_name и role. Документированы роли member, admin и superadmin; последняя обозначает владельца или создателя. Отображаемое имя помогает оператору узнать человека, но не является идентификатором для запроса.

Ниже — рекомендуемые меры приложения, а не дополнительные требования API:

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

Если цель нельзя сопоставить с возвращённым WhatsApp LID, остановитесь. Не подставляйте номер телефона, имя или идентификатор из события в другом формате.

Один подтверждённый участник — один запрос

Справочник управления участниками группы принимает одиночный member_id, а не массив member_ids, используемый для решений по заявкам. UnifyPort предоставляет неофициальный интерфейс. Текущая матрица действий провайдеров относит эту операцию только к whatsapp, не к LINE, Telegram или whatsapp-protocol.

Этот пример JavaScript только формирует тело запроса. Передайте подтверждённый ID группы и выбранную запись из списка участников. Проверку полномочий и сетевой вызов пример не реализует.

function removalBody(groupId, selectedMember) {
  if (!groupId || !/^\d+@lid$/.test(selectedMember?.peer_id ?? '')) {
    throw new Error('Select a group and a returned WhatsApp member LID');
  }
  if (!['member', 'admin'].includes(selectedMember.role)) {
    throw new Error('This target requires separate review');
  }
  return {
    group_id: groupId,
    action: 'remove',
    member_id: selectedMember.peer_id
  };
}

Ограничение по роли — локальная мера безопасности. Проверка формата LID не доказывает ни личность, ни полномочия. Отправляйте JSON с сервера на указанный выше эндпоинт с X-Api-Key и Content-Type: application/json. Не передавайте ключ в браузер и не записывайте его в логи. Транзакция удаления нескольких участников не документирована: даже при массовом выборе в интерфейсе учитывайте результат для каждого одобренного участника отдельно.

Оценивайте доказательства, а не анимацию интерфейса

Разделяйте намерение оператора, HTTP-результат и наблюдаемый состав группы:

Наблюдение	Что может сообщить приложение
200 OK и data.ok: true	API вернул успех; нужно обновить состав группы
Успешное завершённое чтение списка без выбранного LID	Участник не обнаружен при этом чтении; сохраните время проверки
Чтение списка не завершено или завершилось ошибкой	Проверка остаётся нерешённой
Тайм-аут изменения или нечитаемый ответ	Исход запроса не установлен; перед новой записью нужна проверка

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

Сохраняйте request_id, если он доступен, для диагностики, но не используйте его как ключ идемпотентности. При неопределённом результате прочитайте текущий состав и потребуйте повторного рассмотрения перед новым изменением. Автоматическая отправка add в качестве компенсации — новое решение о членстве, а не гарантированный откат.

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

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

Нет. Для этой операции документированы WhatsApp LID из peer_id списка участников. Начальные участники при создании группы задаются по другому контракту идентификаторов.

Удаление также стирает сохранённые сообщения или навсегда запрещает повторное вступление?

Не обещайте этого на основании данного API. Его область — управление участниками, не удаление истории и не постоянная политика допуска. Хранение данных и будущие решения о вступлении настраивайте отдельно.

Что проверить до запуска?

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

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

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

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

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