← Все статьи
Руководство

Как выйти из группы WhatsApp через API: безопасный порядок действий

Чтобы подключённый аккаунт WhatsApp вышел из группы через UnifyPort, отправьте POST /v1/accounts/{account_id}/groups/leave с полем group_id в JSON-теле. Операция меняет участие выбранного аккаунта в группе. Она не удаляет группу для всех и не очищает вашу базу обращений. Перед запросом подтвердите цель и остановите ожидающие отправки автоматические ответы в эту группу.

Главное

  • Выбирайте аккаунт мессенджера и группу вместе: название группы не является уникальным идентификатором.
  • Выход, удаление другого участника, отключение уведомлений и очистка сохранённых сообщений — разные операции.
  • Сейчас действие выхода в UnifyPort поддерживается только для whatsapp, а не для всех каналов с доступным списком групп.
  • После тайм-аута результат неизвестен. Сначала проверьте текущее состояние и лишь затем решайте, нужен ли новый запрос.

Убедитесь, что нужен именно выход

Официальная инструкция WhatsApp различает Exit group, сохраняющий историю чата, и Exit and delete for me, удаляющий её локально. Не объединяйте эти намерения в неоднозначную кнопку «Удалить». Если группа входит в сообщество, сначала изучите инструкцию для участника: последствия для сообщества требуют отдельной проверки.

Цель оператораПодходящий процесс
Прекратить участие подключённого аккаунтаЯвный выход из группы
Уменьшить количество уведомленийОтключение уведомлений
Остановить автоответы, сохранив участиеПауза на стороне вашего приложения
Изменить права администратора другого участникаОтдельная смена роли
Удалить данные в системе поддержкиСобственная процедура хранения и удаления данных

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

Зафиксируйте аккаунт и группу до подтверждения

Используйте List groups для выбранного аккаунта. Метод возвращает группы, в которых он состоит, включая группы без отправленных сообщений. В элементах есть id, conversation_id и name; для группы conversation_id совпадает с id. Обрабатывайте страницы по has_more и next_cursor, а не ограничивайтесь первой.

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

Рекомендуемые меры в приложении:

  1. Запрашивать подтверждение именно этого выхода у уполномоченного оператора.
  2. Остановить новые автоматические отправки для пары аккаунт/группа и проверить уже ожидающие и выполняющиеся задания.
  3. Оставить приём подписанных webhook включённым. Остановка исходящих сообщений не требует прекращать сохранение входящих событий.
  4. Записать оператора, цель и причину в собственный журнал аудита, а не отправлять их как несуществующие поля API.

Это рекомендации для приложения, а не дополнительные гарантии эндпоинта.

Отправьте один запрос выхода

UnifyPort предоставляет неофициальный интерфейс. В справочнике Leave group описаны запрос ниже и успешный ответ 200 OK с data.ok: true. Согласно матрице действий провайдеров, выход поддерживается только для whatsapp, но не для LINE, Telegram или отдельного провайдера whatsapp-protocol.

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

const accountId = process.env.UNIFYPORT_ACCOUNT_ID;
const groupId = process.env.WHATSAPP_GROUP_ID;
const apiKey = process.env.UNIFYPORT_API_KEY;
if (!accountId || !groupId || !apiKey) {
  throw new Error('Missing confirmed target or credential');
}

const response = await fetch(
  `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/leave`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ group_id: groupId })
  }
);
const outcome = await response.json();
if (!response.ok || outcome.data?.ok !== true) {
  throw new Error('Exit not confirmed; review the response');
}

В рабочей системе также необходимо безопасно сохранять HTTP-статус и request_id, обрабатывать сетевые ошибки и ошибки разбора, а до выполнения кода проверять полномочия оператора. Отсутствие ответа не доказывает, что WhatsApp отклонил действие.

Проверяйте результат отдельно от удаления данных

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

Держите задания ответов на паузе, пока оператор не разрешит ситуацию. Запоздавшие входящие события не должны незаметно возобновлять отправку. Выход также не стирает сообщения, ранее сохранённые вашим приложением: применяйте политику хранения отдельно.

Если события группы служат сигналом для сверки, соблюдайте контракт доставки webhook при проверке подписи и обработке дублей. Не рассчитывайте на неописанное событие group.left и не обещайте callback для каждого запроса выхода.

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

Группа удаляется для всех?

Нет. Описанное действие выводит подключённый аккаунт из группы. Это не API роспуска группы или удаления базы данных.

Можно выйти через удаление участника?

Для подключённого аккаунта используйте специальное действие выхода. Управление другим участником — отдельный запрос с другими параметрами.

Если API показывает группы LINE, можно ли через него выйти из них?

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

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

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

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

UnifyPort API

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

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

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