> ## Documentation Index > Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt > Use this file to discover all available pages before exploring further. # Управление группами WhatsApp > Узнайте, как создавать группы WhatsApp только по приглашению, приглашать пользователей, рассматривать запросы на вступление и управлять настройками группы. ## Что это такое API групп WhatsApp от YCloud позволяет вашей компании создавать группы WhatsApp только по приглашению. Вы отправляете ссылку-приглашение каждому пользователю, и он сам решает, вступать ли в группу. Если для группы требуется подтверждение, вы можете рассмотреть запрос пользователя на вступление, прежде чем разрешить ему доступ. В этом руководстве рассматриваются настройка групп, управление ими и исходящие групповые сообщения. Групповые диалоги не отображаются во Входящих (Inbox). ## Перед началом работы Перед началом интеграции убедитесь, что ваш рабочий номер телефона WhatsApp соответствует следующим требованиям: * У компании есть официальный бизнес-аккаунт (Official Business Account, OBA). * Номер телефона использует WhatsApp Cloud API, а не приложение WhatsApp Business. * Номер телефона не использует Multi-solution Conversations. * У вашего аккаунта YCloud есть доступ к этому номеру телефона. * У вас есть публичный URL-адрес HTTPS, на который YCloud может отправлять события Webhook. * Перед отправкой ссылок-приглашений через шаблонное сообщение у вас должен быть одобренный шаблон приглашения в группу. YCloud управляет необходимыми подписками платформы WhatsApp. Вам требуется только [настроить эндпоинт Webhook в YCloud](/ru/api-reference/guides/api-fundamentals/configure-webhooks) и выбрать события групп YCloud, которые вы хотите получать. YCloud и WhatsApp проверяют соответствие номера телефона требованиям. Если он им не соответствует, проверьте его статус OBA, настройку Cloud API и доступ в YCloud. ## Поддерживаемые возможности и ограничения В настоящее время YCloud поддерживает: * Создание, получение списка, получение информации и удаление групп. * Получение и сброс ссылок-приглашений. * Отправку утвержденного шаблона со ссылкой-приглашением отдельному пользователю WhatsApp. * Просмотр списка, одобрение и отклонение запросов на вступление. * Удаление участников. * Обновление темы и описания группы. * Обновление изображения профиля группы с помощью файла JPEG. * Отправку в группу текстовых сообщений, медиафайлов, стикеров и поддерживаемых шаблонных сообщений. * Получение событий Webhook о жизненном цикле группы, участниках, настройках и блокировке. Платформа WhatsApp устанавливает следующие ограничения: * В группе может быть до 8 участников. * Один бизнес-номер телефона может создать до 10 000 групп. * Группа может содержать только один рабочий номер телефона Cloud API. * Один запрос YCloud может удалить до 8 участников. * Тема группы может содержать до 128 символов. * Описание группы может содержать до 2048 символов. Эти API не поддерживают закрепление или открепление сообщений. ## Как это работает 1. Выберите, какие события групп YCloud должен отправлять на ваш эндпоинт Webhook. 2. Отправьте запрос на создание группы. YCloud немедленно возвращает `requestId`. 3. Дождитесь события Webhook о жизненном цикле, сообщающего об успешности создания. 4. В случае успешного создания сохраните возвращенный `groupId` и ссылку-приглашение. Сохраняйте и используйте `groupId` в точности так, как его возвращает YCloud. 5. Отправляйте ссылку-приглашение пользователям по одному. 6. Если для группы требуется подтверждение, одобряйте или отклоняйте каждый запрос на вступление. 7. Используйте события участников и API получения группы, чтобы поддерживать список участников в актуальном состоянии. 8. Используйте события Webhook для подтверждения удаления группы, исключения участников и изменения настроек. Ответ `200` с `status: "pending"` означает только то, что YCloud принял запрос. Операция завершается позже. Используйте соответствующее событие Webhook, чтобы узнать, завершилась ли она успешно. ## Настройка 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` | Пользователь отправляет запрос на вступление, который необходимо одобрить до того, как он сможет присоединиться. | ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 принял запрос: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "requestId": "REQ_1", "status": "pending" } ``` Дождитесь события `whatsapp.group.lifecycle_update`. Успешное событие `group_create` содержит окончательные `groupId` и `inviteLink`. ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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 о создании или получить её позже с помощью эндпоинта для ссылки-приглашения. Сбрасывайте ссылку только тогда, когда необходимо прекратить действие всех ранее предоставленных ссылок. После сброса пользователи не смогут присоединиться по старой ссылке. Чтобы отправить ссылку через WhatsApp, сначала подготовьте одобренный шаблон сообщения с приглашением. Затем отправьте этот шаблон конкретному пользователю: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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`: 1. Получите `group_join_request_created` или запросите ожидающие запросы. 2. Сохраните `joinRequestId`, пока запрос все еще ожидает обработки. 3. Отправьте каждый ID на эндпоинт одобрения или отклонения. 4. Проверьте как успешные, так и неуспешные элементы в ответе, включая `failedJoinRequests` и `errors`. 5. Убедитесь, что человек присоединился, используя Webhook о добавлении участника или запросив данные группы. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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` для предыдущей. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} 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" ``` Не сохраняйте курсор в качестве постоянного идентификатора. Если он недействителен или истек, начните снова с первой страницы. ## Отправка сообщения в группу Используйте `POST /whatsapp/groupMessages/sendDirectly` для отправки одного сообщения текущим участникам группы. YCloud сначала получает данные группы и фиксирует снимок получателей для этого сообщения. Если в группе восемь участников, включая бизнес-отправителя, YCloud создает семь результатов для участников. Люди, присоединившиеся позже, не получат ранее отправленное сообщение и не будут добавлены в его историю. Ответ на отправку подтверждает принятие сообщения. Используйте `GET /whatsapp/groupMessages/{id}` для получения результата на уровне группы, статуса доставки для каждого участника и окончательной стоимости. Статус `status` на уровне группы описывает общий результат отправки: принято YCloud, отправлено Meta или ошибка. Каждый элемент в `recipients` описывает одного участника и может иметь отдельный статус. YCloud поддерживает сообщения типов `text`, `image`, `video`, `audio`, `document`, `sticker` и поддерживаемые `template`. Шаблоны аутентификации, а также шаблоны с интерактивными или коммерческими компонентами отклоняются. Для маркетинговых шаблонов YCloud может использовать канал MM Lite, если WABA соответствует требованиям и как минимум для одного получателя задана цена MM Lite. В этом случае записи участников используют `group_marketing_lite`. Сервисные и утилитарные сообщения сохраняют `group_utility` и `group_service` и не используют MM Lite. Если для участника нет цены для выбранного канала, YCloud все равно отправляет сообщение в группу, если его можно отправить хотя бы одному участнику. При этом сумма для участника без цены не резервируется, а откат к цене другого канала не выполняется. Окончательный расчет основывается на цене, указанной в отчете о доставке. ## Управление группой ### Удаление участников Вы можете удалить до восьми участников в одном запросе. Удалите дублирующиеся идентификаторы участников перед отправкой запроса. Некоторые участники могут быть удалены, в то время как удаление других завершится ошибкой, поэтому проверяйте `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`, не применяйте одно и то же изменение дважды. * Убедитесь, что повторная обработка того же события не приводит к созданию дубликатов данных или побочных эффектов. * Учитывайте, что события могут повторяться или приходить в нарушенном порядке. * Запрашивайте данные группы повторно, если событие конфликтует с вашими текущими данными. * Проверяйте ошибки верхнего уровня и ошибки на уровне отдельных элементов при частичном выполнении операций. * Скрывайте ключи API, ссылки-приглашения, идентификаторы участников и персональные данные из общих логов приложения. ## Ошибки и устранение неполадок Запрос к API может завершиться ошибкой сразу или после того, как YCloud его принял: * При немедленном сбое проверьте стандартный ответ об ошибке YCloud. Параметр верхнего уровня `error.code` представляет собой общий код YCloud, такой как `BAD_REQUEST` или `FORBIDDEN`. Поле `error.whatsappApiError` может содержать дополнительные сведения от WhatsApp. Не определяйте логику работы приложения на основе сопоставления текста `message`, предназначенного для чтения человеком. * При сбое, о котором сообщается позже, проверьте Webhook группы. В зависимости от операции просмотрите `whatsappGroup.errors`, `failedParticipants[].errors` или `settings[].errors`. | Сценарий | Рекомендуемое действие | | - | - | | Группа не найдена или недоступна | Убедитесь, что значение `groupId` в точности совпадает со значением, возвращенным YCloud, затем запросите актуальное состояние группы. | | Курсор недействителен или срок его действия истек | Перезапустите разбиение на страницы с первой страницы. | | Операция выполнена частично | Обрабатывайте успешные и завершившиеся ошибкой элементы раздельно. | | Повторяющиеся участники | Удалите дублирующиеся идентификаторы участников перед повторной попыткой. | | Достигнут лимит участников группы | Прекратите добавление участников и сообщите, что группа заполнена. | | Группа заблокирована | Дождитесь обновления статуса или обратитесь в службу поддержки. | | Превышен лимит запросов на операции с группами | Повторите попытку с использованием экспоненциальной задержки, джиттера и ограничения числа попыток. | | Достигнут лимит групп для номера телефона | Удалите неиспользуемые группы или обратитесь в службу поддержки. | | Участник отсутствует в группе | Обновите список участников вместо повторной попытки удаления. | | Запрос на вступление не найден | Обновите список ожидающих запросов; возможно, он был отозван или обработан. | | Создание групп временно ограничено | Прекратите создание групп и пересмотрите недавнюю стратегию отправки сообщений. | | Номер телефона не подходит | Проверьте статус OBA, подключение к Cloud API и доступ к YCloud. | К частым сбоям ссылок-приглашений также относятся сброшенная или просроченная ссылка, переполненная группа или пользователь, который ранее был удален компанией. Не повторяйте неизмененные запросы бесконечно. ## Сквозной контрольный список Перед запуском в рабочей среде выполните этот полный сценарий, используя подходящий тестовый номер телефона: 1. Подпишите тестовую конечную точку Webhook на все четыре типа событий группы. 2. Создайте группу `approval_required` и сохраните возвращенный `requestId`. 3. Дождитесь соответствующего события `group_create` и сохраните его `groupId` и `inviteLink`. 4. Отправьте одобренный шаблон сообщения с приглашением тестовому пользователю. 5. Попросите пользователя отправить запрос на вступление. 6. Получите запрос или список запросов, затем подтвердите его `joinRequestId`. 7. Дождитесь события добавления участника. 8. Запросите данные группы и убедитесь, что участник присутствует. 9. Удалите тестового участника и подтвердите асинхронный результат. 10. Удалите тестовую группу и подтвердите событие жизненного цикла. Примеры в этом руководстве соответствуют текущему контракту YCloud API. Успешно выполните шаги из этого контрольного списка перед использованием интеграции в рабочей среде. ## Справочник по API | Операция | Ссылка на справочник | | - | - | | Создать группу | [Справочник по API](/api-reference/whatsapp-groups/create-a-group) | | Получить список групп | [Справочник по API](/api-reference/whatsapp-groups/list-groups) | | Получить информацию о группе | [Справочник по API](/api-reference/whatsapp-groups/retrieve-a-group) | | Удалить группу | [Справочник по API](/api-reference/whatsapp-groups/delete-a-group) | | Получить ссылку-приглашение | [Справочник по API](/api-reference/whatsapp-groups/retrieve-a-group-invite-link) | | Сбросить ссылку-приглашение | [Справочник по API](/api-reference/whatsapp-groups/reset-a-group-invite-link) | | Отправить сообщение со ссылкой-приглашением | [Справочник по API](/api-reference/whatsapp-groups/send-a-group-invite-link-message) | | Получить список запросов на вступление | [Справочник по API](/api-reference/whatsapp-groups/list-group-join-requests) | | Одобрить запросы на вступление | [Справочник по API](/api-reference/whatsapp-groups/approve-group-join-requests) | | Отклонить запросы на вступление | [Справочник по API](/api-reference/whatsapp-groups/reject-group-join-requests) | | Удалить участников | [Справочник по API](/api-reference/whatsapp-groups/remove-group-participants) | | Обновить настройки группы | [Справочник по API](/api-reference/whatsapp-groups/update-group-settings) | | Отправить сообщение в группу напрямую | [Справочник по API](/api-reference/whatsapp-group-messages/send-a-group-message-directly) | | Получить сообщение группы | [Справочник по API](/api-reference/whatsapp-group-messages/retrieve-a-group-message) | ## Примеры Webhook Обработка результатов создания и удаления групп. Обработка вступлений, запросов на вступление, удалений и сбоев на уровне участников. Обработка результатов обновления темы и описания. Обработка событий блокировки группы и снятия блокировки. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.