Управление группами 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 и выбрать события групп YCloud, которые вы хотите получать.

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

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

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

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

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

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

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

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

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

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 о создании или получить её позже с помощью эндпоинта для ссылки-приглашения. Сбрасывайте ссылку только тогда, когда необходимо прекратить действие всех ранее предоставленных ссылок. После сброса пользователи не смогут присоединиться по старой ссылке. Чтобы отправить ссылку через 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"

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

Отправка сообщения в группу

Используйте 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.

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

Сквозной контрольный список

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

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

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

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

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

Примеры Webhook

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

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

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

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

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

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

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

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

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

Руководства

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

Webhooks

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

Что это такое

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

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

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

Настройка Webhook

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

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

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

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

Отправка сообщения в группу

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

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

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

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

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

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

Сквозной контрольный список

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

Примеры Webhook

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

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

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

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

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

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

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

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

​Настройка Webhook

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

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

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

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

​Отправка сообщения в группу

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

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

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

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

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

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

​Сквозной контрольный список

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

​Примеры Webhook

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

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

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

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

Что это такое

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

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

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

Настройка Webhook

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

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

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

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

Отправка сообщения в группу

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

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

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

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

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

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

Сквозной контрольный список

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

Примеры Webhook