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

Чтобы создать группу WhatsApp через UnifyPort, отправьте POST /v1/accounts/{account_id}/groups/create с обязательным name и необязательным массивом members. В этом запросе начальные участники WhatsApp указываются номерами телефонов. Успешный ответ возвращает data.id, а не отчёт о составе группы. Сразу сохраните ID, затем получите данные группы и участников — и только после этого запускайте зависящую от них автоматизацию.

Главное

• Создание группы, приглашение людей и управление существующими участниками — разные операции.
• Начальный members содержит номера телефонов; дальнейшее управление участниками использует другой контракт идентификаторов.
• В публичном каталоге нет события group.created. Не делайте его условием завершения процесса.
• Отсутствие ответа означает неопределённость. Автоматический повтор запроса может создать ещё одну группу.

Изучите контракт создания до разработки формы

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

Значение	Назначение	Чем нельзя заменять
account_id в пути	Аккаунт, создающий группу	ID рабочего пространства
name в теле	Обязательное название, до 100 символов	Уникальный идентификатор ресурса
members в теле	Необязательный список начальных участников; для WhatsApp — телефоны	Копия массива LID участников
data.id в ответе	ID новой группы	Код приглашения или ID операции

Объект data в ответе создания содержит только ID новой группы. Результатов добавления каждого человека в нём нет. Храните предполагаемый начальный состав отдельно от состава, который позднее удалось наблюдать.

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

Подготовьте одну подтверждённую попытку

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

Рекомендуемые меры на стороне приложения:

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

Этот пример серверного JavaScript формирует документированный запрос из подтверждённых данных. Здесь он не запускался и намеренно не содержит автоматических повторов:

async function createGroupOnce({ apiKey, accountId, name, phones }) {
  if (!apiKey || !accountId || typeof name !== 'string' || !name.trim()) {
    throw new Error('Missing credential, account, or group name');
  }
  const body = { name };
  if (phones !== undefined) {
    if (!Array.isArray(phones) ||
        phones.some(p => typeof p !== 'string' || !/^[0-9]+$/.test(p))) {
      throw new Error('Use confirmed phone-number strings');
    }
    body.members = phones;
  }
  const response = await fetch(
    `https://api.unifyport.ai/v1/accounts/${encodeURIComponent(accountId)}/groups/create`,
    {
      method: 'POST',
      headers: { 'X-Api-Key': apiKey, 'Content-Type': 'application/json' },
      body: JSON.stringify(body)
    }
  );
  return { httpStatus: response.status, result: await response.json() };
}

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

Отделите ID группы от проверки состава

Получив 200 OK с data.id, сохраните ID вместе с выбранным аккаунтом и локальным намерением создания. Затем вызовите Get group, передав этот ID как group_id.

Для проверки состава используйте List conversation members с ID группы в conversation_id и type=group. Обработайте все страницы по has_more и next_cursor: отсутствие человека на первой странице ещё не завершает проверку. Сохраняйте возвращённые peer_id и role без изменений. Не вычисляйте LID из телефонного номера.

Последующее управление участниками имеет отдельный контракт: один member_id и одно действие на запрос. Для WhatsApp нужен LID, возвращённый списком участников как peer_id. Не используйте там тело запроса создания. Если следующая задача — назначить администраторов, перейдите к руководству по смене роли администратора.

Наблюдение	Рекомендуемое состояние приложения	Следующее действие
Успешный ответ и сохранённый ID	Создана; состав ещё не проверен	Прочитать группу и все страницы участников
Группа доступна, нужный состав не подтверждён	Группа существует; состав требует проверки	Проверить сопоставление идентификаторов или приложение WhatsApp
Тайм-аут, нечитаемый ответ или нет ожидаемого ID	Результат создания не определён	Сверить состояние до новой попытки

Это состояния вашего приложения, а не дополнительные значения ответа API.

Восстановите результат, не создавая дубликат

В каталоге стандартных событий нет group.created; успешное создание не обещает такой callback. Событие group.updated также не является гарантированной квитанцией для каждого запроса создания.

Если ответ потерян, проверьте List groups под тем же аккаунтом, обработав пагинацию. Список включает группы, в которых аккаунт состоит, даже если сообщений ещё не было. Используйте доступные сведения и приложение WhatsApp для проверки. Совпадение названия само по себе не доказывает идентичность группы; неполное или неудачное чтение не доказывает, что создание не состоялось.

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

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

Можно не передавать members?

Да, API описывает members как необязательное поле. Но это свойство схемы запроса, а не гарантия поведения любого аккаунта на стороне платформы. Проверяйте фактический результат.

Успешный HTTP-ответ доказывает, что все вступили?

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

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

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

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

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

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

• WhatsApp: добавление и удаление участников группы
• UnifyPort: Create group
• UnifyPort: List conversation members
• UnifyPort: стандартные события