Управление группами WhatsApp

Что это такое

YCloud WhatsApp Groups API позволяет вашей компании создавать группы WhatsApp, доступные только по приглашению. Вы отправляете ссылку-приглашение каждому пользователю, и тот сам решает, присоединяться ли. Если для группы требуется одобрение, вы можете проверить запрос пользователя на вступление, прежде чем разрешить ему войти в группу. В этом руководстве рассматриваются настройка групп и управление ими. Отправка сообщений в группы и получение сообщений из групп пока недоступны. Групповые диалоги не отображаются во Входящих (Inbox).

Перед началом работы

Перед интеграцией убедитесь, что ваш рабочий номер телефона WhatsApp соответствует следующим требованиям:

У компании есть официальный бизнес-аккаунт (Official Business Account, OBA).
Номер телефона использует WhatsApp Cloud API, а не приложение WhatsApp Business App.
Номер телефона не использует Multi-solution Conversations.
Ваш аккаунт YCloud имеет доступ к номеру телефона.
У вас есть публичный HTTPS URL, на который YCloud может отправлять события Webhook.
Перед отправкой ссылок-приглашений через шаблонное сообщение у вас должен быть одобренный шаблон приглашения в группу.

YCloud управляет необходимыми подписками на платформе WhatsApp. Вам требуется лишь настроить конечную точку Webhook в YCloud и выбрать события групп YCloud, которые вы хотите получать.

YCloud и WhatsApp проверяют номер телефона на соответствие требованиям. Если он не подходит, проверьте статус OBA, настройку Cloud API и доступ в YCloud.

Поддерживаемые возможности и ограничения

YCloud в настоящее время поддерживает:

Создание, вывод списком, получение и удаление групп.
Получение и сброс ссылок-приглашений.
Отправку одобренного шаблона с ссылкой-приглашением отдельному пользователю WhatsApp.
Просмотр, одобрение и отклонение запросов на вступление.
Удаление участников.
Обновление темы и описания группы.
Обновление аватара группы файлом в формате JPEG.
Получение вебхуков жизненного цикла группы, участников, настроек и блокировок.

Платформа WhatsApp накладывает следующие ограничения:

В группе может быть не более 8 участников.
С одного рабочего номера телефона можно создать не более 10 000 групп.
В группе может находиться только один рабочий номер телефона Cloud API.
Один запрос YCloud может удалить до 8 участников.
Тема группы может содержать до 128 символов.
Описание группы может содержать до 2048 символов.

Эти API не поддерживают закрепление и открепление сообщений.

Как это работает

Выберите события групп, которые YCloud должен отправлять на вашу конечную точку Webhook.
Отправьте запрос на создание группы. YCloud сразу же вернет requestId.
Дождитесь вебхука жизненного цикла, сообщающего, прошло ли создание успешно.
В случае успешного создания сохраните возвращенный groupId и ссылку-приглашение. Сохраняйте и используйте groupId ровно в том виде, в каком его возвращает YCloud.
Отправляйте ссылку-приглашение каждому человеку по отдельности.
Если группа требует одобрения, одобряйте или отклоняйте каждый запрос на вступление.
Используйте события участников и API получения группы, чтобы поддерживать список участников в актуальном состоянии.
Используйте события Webhook для подтверждения удаления группы, удаления участников и изменения настроек.

Ответ 200 с кодом status: "pending" означает только то, что YCloud получил запрос. Сама операция завершится позже. Используйте соответствующее событие Webhook, чтобы узнать, завершилась ли она успешно.

Настройка вебхуков

Перед созданием группы подпишите вашу конечную точку Webhook в YCloud на следующие события:

Событие	Для чего используется
`whatsapp.group.lifecycle_update`	Результаты создания и удаления группы.
`whatsapp.group.participants_update`	Вступления, запросы на вступление, удаления, выходы и сбои на уровне участников.
`whatsapp.group.settings_update`	Результаты обновления темы и описания.
`whatsapp.group.status_update`	События блокировки и снятия блокировки группы.

Когда YCloud отправляет событие, проверьте YCloud-Signature, сохраните событие и незамедлительно верните ответ 2xx. Затем вы можете обработать его в фоновом режиме. YCloud может отправить одно и то же событие несколько раз, а разные события могут поступать не по порядку. Используйте id события, чтобы определить доставку, которую вы уже обработали. Для операции, инициированной через API, сопоставьте Webhook с исходным запросом по requestId. Действия, инициированные участником (например, вступление или выход), могут не содержать requestId. В этом случае используйте тип события, groupId, идентификатор участника и время события.

Создание группы

Выберите режим подтверждения вступления:

Режим	Поведение
`auto_approve`	Пользователь может присоединиться напрямую по ссылке-приглашению. Это значение по умолчанию.
`approval_required`	Пользователь отправляет запрос на вступление, который необходимо одобрить до его присоединения.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "subject": "New purchase inquiry",
    "description": "Discuss purchase requirements with our team.",
    "joinApprovalMode": "approval_required"
  }'

Создание группы завершается асинхронно. Первый ответ лишь подтверждает, что YCloud принял запрос:

{
  "requestId": "REQ_1",
  "status": "pending"
}

Дождитесь whatsapp.group.lifecycle_update. Успешное событие group_create содержит окончательные groupId и inviteLink.

{
  "id": "evt_group_lifecycle_123",
  "type": "whatsapp.group.lifecycle_update",
  "whatsappGroup": {
    "type": "group_create",
    "requestId": "REQ_1",
    "status": "created",
    "groupId": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE",
    "inviteLink": "https://chat.whatsapp.com/AbCdEfGhIjK"
  }
}

Сохраняйте и используйте groupId точно в таком виде, в каком он появляется в событии об успехе. Он чувствителен к регистру. Не декодируйте, не изменяйте и не генерируйте его самостоятельно.

Приглашение участников

Вы можете использовать ссылку-приглашение из Webhook о создании или получить её позже с помощью эндпоинта invite-link. Сбрасывайте ссылку только тогда, когда необходимо прекратить действие всех ранее опубликованных ссылок. После сброса пользователи не смогут присоединиться по старой ссылке. Чтобы отправить ссылку через WhatsApp, сначала подготовьте одобренный шаблон приглашения. Затем отправьте этот шаблон отдельному пользователю:

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups/inviteLink/messages \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "to": "+16315552222",
    "templateName": "group_invite_link",
    "languageCode": "en_US",
    "parameters": [
      {
        "type": "group_id",
        "group_id": "Y2FwaV9ncm91cDpFWEFNUExFX0dST1VQX0lE"
      }
    ]
  }'

Этот эндпоинт отправляет шаблонное сообщение человеку, указанному в to или recipient. Он не отправляет сообщение в группу. Если указаны оба поля, YCloud использует to.

Обработка запросов на вступление

Для группы с типом auto_approve дождитесь Webhook о добавлении участника, прежде чем сохранять пользователя в качестве участника. Для группы с типом approval_required:

Получите group_join_request_created или запросите ожидающие запросы.
Сохраните joinRequestId, пока запрос находится в состоянии ожидания.
Отправьте каждый ID на эндпоинт одобрения или отклонения.
Проверьте как успешные, так и неуспешные элементы в ответе, включая failedJoinRequests и errors.
Подтвердите вступление пользователя с помощью Webhook о добавлении участника или запросив данные группы.

curl --request POST \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups/GROUP_ID/joinRequests/approve \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "joinRequests": ["join-request-id"]
  }'

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

Получение списка групп и запросов на вступление

Список групп и список запросов на вступление возвращают результаты постранично. Курсор — это временное значение, отмечающее вашу позицию в списке. Параметр limit управляет размером страницы, принимает значения от 1 до 1024 и по умолчанию равен 25. Передавайте after для перехода к следующей странице или before для перехода к предыдущей странице.

curl --get \
  https://api.ycloud.com/v2/whatsapp/+16315551111/groups \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --data-urlencode "limit=25" \
  --data-urlencode "after=NEXT_CURSOR"

Не сохраняйте курсор как постоянный идентификатор. Если он недействителен или истек, начните снова с первой страницы.

Управление группой

Удаление участников

В одном запросе можно удалить до восьми участников. Перед отправкой удалите повторяющиеся идентификаторы участников. Некоторые участники могут быть удалены успешно, тогда как для других произойдет ошибка, поэтому проверяйте removedParticipants, failedParticipants[].errors и поле верхнего уровня errors в Webhook об участниках.

Обновление настроек

Вы можете обновить subject, description, изображение JPEG profile_picture_file или любую комбинацию этих параметров. Отправляйте JSON только при изменении текста. Отправляйте multipart/form-data при загрузке фото профиля. Первоначальный ответ лишь подтверждает, что YCloud принял запрос. Дождитесь Webhook о настройках и проверьте каждую запись settings[], чтобы узнать, что именно было обновлено.

Удаление группы

Первоначальный ответ на удаление не подтверждает, что группа была удалена. Дождитесь Webhook жизненного цикла с type: "group_delete" и окончательным status. После удаления группу нельзя использовать снова. События, которые уже были в процессе обработки, все еще могут поступить.

Безопасная обработка асинхронных результатов

Сохраняйте requestId, запрошенную операцию и свой собственный идентификатор (ID) вместе.
Если вы повторно получаете то же событие id, не применяйте одно и то же изменение дважды.
Убедитесь, что повторная обработка того же события не приводит к дублированию данных или побочным эффектам.
Учитывайте, что события могут повторяться или приходить не по порядку.
Запрашивайте данные группы повторно, если событие конфликтует с вашими текущими данными.
Проверяйте ошибки верхнего уровня и ошибки на уровне отдельных элементов при частичном выполнении операций.
Скрывайте ключи API, ссылки-приглашения, идентификаторы участников и персональные данные в общих журналах приложения.

Ошибки и устранение неполадок

API-запрос может завершиться сбоем сразу или после того, как YCloud его принял:

В случае мгновенного сбоя проверьте стандартный ответ об ошибке YCloud. Поле верхнего уровня error.code представляет собой общий код YCloud, такой как BAD_REQUEST или FORBIDDEN. Поле error.whatsappApiError может содержать дополнительные сведения от WhatsApp. Не определяйте логику поведения вашего приложения путем сопоставления человекочитаемого текста message.
Если сбой зафиксирован позже, проверьте Webhook группы. В зависимости от операции изучите whatsappGroup.errors, failedParticipants[].errors или settings[].errors.

Сценарий	Рекомендуемое действие
Группа не найдена или недоступна	Убедитесь, что `groupId` в точности совпадает со значением, возвращенным YCloud, затем запросите актуальное состояние группы.
Курсор недействителен или истек	Начните пагинацию заново с первой страницы.
Операция выполнена частично	Обработайте успешные и неуспешные элементы раздельно.
Повторяющиеся участники	Удалите повторяющиеся ID участников перед повторной попыткой.
Достигнут лимит участников группы	Прекратите добавление участников и передайте сообщение о том, что группа заполнена.
Группа заблокирована	Дождитесь обновления статуса или обратитесь в службу поддержки.
Превышен лимит частоты операций с группой	Повторите попытку с экспоненциальной задержкой, добавлением случайного отклонения (jitter) и ограничением числа попыток.
Достигнут лимит групп для номера телефона	Удалите неиспользуемые группы или обратитесь в службу поддержки.
Participant not in the group	Обновите список участников вместо повторной попытки удаления.
Join request not found	Обновите список ожидающих запросов; возможно, запрос был отозван или уже обработан.
Group creation temporarily restricted	Прекратите создание групп и пересмотрите недавнюю стратегию рассылки сообщений.
Phone number not eligible	Проверьте статус OBA, подключение к Cloud API и доступ к YCloud.

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

Комплексный чек-лист

Перед запуском в продакшене используйте подходящий тестовый номер телефона, чтобы выполнить этот полный сценарий:

Подпишите тестовый эндпоинт Webhook на все четыре типа событий группы.
Создайте группу approval_required и сохраните возвращенный requestId.
Дождитесь соответствующего события group_create и сохраните его groupId и inviteLink.
Отправьте одобренный шаблон приглашения тестовому пользователю.
Попросите пользователя отправить запрос на вступление.
Получите или запросите список запросов, затем одобрите его joinRequestId.
Дождитесь события добавления участника.
Запросите данные группы и убедитесь, что участник присутствует.
Удалите тестового участника и подтвердите асинхронный результат.
Удалите тестовую группу и подтвердите событие жизненного цикла.

Примеры в этом руководстве соответствуют текущему контракту YCloud API. Успешно пройдите этот чек-лист перед использованием интеграции в рабочей среде.

Справочник по API

Операция	Справочник
Создать группу	Справочник по API
Получить список групп	Справочник по API
Получить данные группы	Справочник по API
Удалить группу	Справочник по API
Получить ссылку-приглашение	Справочник по API
Сбросить ссылку-приглашение	Справочник по API
Отправить сообщение со ссылкой-приглашением	Справочник по API
Получить список запросов на вступление	Справочник по API
Одобрить запросы на вступление	Справочник по API
Отклонить запросы на вступление	Справочник по API
Удалить участников	Справочник по API
Обновить настройки группы	Справочник по API

Примеры Webhook

События жизненного цикла

Обработка результатов создания и удаления групп.

События участников

Обработка вступлений, запросов на вступление, удалений и ошибок на уровне участников.

События настроек

Обработка результатов обновления темы и описания.

События статуса

Обработка событий блокировки группы и снятия блокировки.

Начало работы

Руководства

Конечные точки

Webhooks

Управление группами WhatsApp

Что это такое

Перед началом работы

Поддерживаемые возможности и ограничения

Как это работает

Настройка вебхуков

Создание группы

Приглашение участников

Обработка запросов на вступление

Получение списка групп и запросов на вступление

Управление группой

Удаление участников

Обновление настроек

Удаление группы

Безопасная обработка асинхронных результатов

Ошибки и устранение неполадок

Комплексный чек-лист

Справочник по API

Примеры Webhook

События жизненного цикла

События участников

События настроек

События статуса

​Что это такое

​Перед началом работы

​Поддерживаемые возможности и ограничения

​Как это работает

​Настройка вебхуков

​Создание группы

​Приглашение участников

​Обработка запросов на вступление

​Получение списка групп и запросов на вступление

​Управление группой

​Удаление участников

​Обновление настроек

​Удаление группы

​Безопасная обработка асинхронных результатов

​Ошибки и устранение неполадок

​Комплексный чек-лист

​Справочник по API

​Примеры Webhook

События жизненного цикла

События участников

События настроек

События статуса

Что это такое

Перед началом работы

Поддерживаемые возможности и ограничения

Как это работает

Настройка вебхуков

Создание группы

Приглашение участников

Обработка запросов на вступление

Получение списка групп и запросов на вступление

Управление группой

Удаление участников

Обновление настроек

Удаление группы

Безопасная обработка асинхронных результатов

Ошибки и устранение неполадок

Комплексный чек-лист

Справочник по API

Примеры Webhook