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

​
Проверка доступности для номера

Текущее руководство по группам YCloud требует наличия официального бизнес-аккаунта (Official Business Account) и поддерживаемого номера Cloud API. Номера из приложения WhatsApp Business и Multi-solution Conversations не поддерживаются. Ваш аккаунт YCloud должен иметь доступ к номеру. Доступность функций работы с группами зависит от проверок со стороны платформы и YCloud; само по себе наличие ключа API не делает номер подходящим. В руководстве описаны небольшие группы до восьми участников. Ознакомьтесь с актуальным руководством перед проектированием логики, основанной на количестве групп, лимитах участников или других предположениях о вместимости.

​
Что поддерживает YCloud

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

Meta's invitation model: create the group, receive the invite link through the lifecycle webhook, then invite WhatsApp users. This diagram does not imply YCloud outbound group-message support.

Источник: официальный пример Meta.

​
Участие осуществляется по приглашению

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

​
Ожидание окончательного результата

Некоторые операции управления выполняются асинхронно. Немедленный ответ подтверждает прием запроса, а результаты передаются через Webhook. Перед отправкой приглашения убедитесь, что создание группы завершилось успешно. После изменения состава участников проверяйте статус конкретных участников, а не предполагайте успешное выполнение всего запроса. Интеграция может получить входящее событие сообщения группы, даже если чат не отображается во Входящих (Inbox). Это событие не означает поддержку исходящих групповых сообщений.

​
Безопасный процесс создания первой группы

  1. Убедитесь в наличии статуса OBA у номера отправителя и проверьте доступность функций Groups.
  2. Создайте группу с понятной темой и выберите тип вступления: автоматическое или требующее одобрения.
  3. Сохраните идентификатор запроса на создание (request ID). Ответ с status: "pending" еще не является готовой группой.
  4. Дождитесь успешного события жизненного цикла создания группы и сохраните ее идентификатор (group ID) и ссылку-приглашение.
  5. Отправьте утвержденный шаблон со ссылкой-приглашением подходящим получателям.
  6. Если требуется одобрение, проверяйте каждый запрос на вступление и одобряйте либо отклоняйте его.
  7. Подтверждайте факт участия по фактическому результату для пользователя, прежде чем считать его участником группы.
Факт доставки приглашения не означает, что получатель открыл ссылку, запросил доступ или вступил в группу. Если операция одобрения возвращает смешанные результаты, обрабатывайте каждый результат отдельно.

​
Идентификаторы и задокументированные лимиты

Относитесь к идентификатору группы (group ID) как к непрозрачному идентификатору с учетом регистра. Не нормализуйте и не декодируйте его. Идентификатор запроса на создание, идентификатор группы, идентификатор сообщения-приглашения и идентификатор запроса на вступление — это разные идентификаторы, они не взаимозаменяемы.

​
Безопасность при изменении состава участников

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

​
Принятие решения о начале работы

Используйте Руководство по интеграции групп, если поддерживаемые операции управления соответствуют вашим потребностям. Если вашим ключевым требованием является двусторонний обмен сообщениями в группах через YCloud Inbox или Messages API, уточните доступность этой функции в YCloud перед началом внедрения. Не давайте клиентам обещаний на базе неподдерживаемых возможностей.

​
Часто задаваемые вопросы

Дождитесь окончательного результата создания. ID запроса не является ID группы или ссылкой-приглашением. Сохраните данные группы из успешного события жизненного цикла, а затем отправьте подтвержденное приглашение подходящим отдельным получателям.
Доставка лишь подтверждает, что приглашение дошло до получателя. Клиент все еще должен открыть ссылку и согласиться вступить; для групп с обязательным одобрением также требуется подтверждение заявки. Проверяйте запрос на вступление и событие добавления участника, а не считайте статус доставки приглашения фактом членства.
Сначала проверьте, не была ли ссылка сброшена. Сброс аннулирует предыдущую ссылку, поэтому используйте актуальную ссылку и обновите контролируемые точки распространения. Если ссылка актуальна, проверьте, не заполнена ли группа или не был ли участник удален ранее. Проверьте состояние группы и участника перед созданием дублирующей группы. См. раздел Часто задаваемые вопросы по группам Meta.
В рамках текущей документированной функциональности YCloud — нет. Групповые диалоги не отображаются в Inbox, а отправка исходящих групповых сообщений не поддерживается в Messages API. Эндпоинты управления группами и входящие групповые события не обеспечивают полноценный двусторонний групповой чат.
Meta по-прежнему может доставлять сообщения или события статусов, полученные до удаления. Эти отложенные события не означают, что группа была создана заново. Сохраняйте ID группы и результат удаления, корректно обрабатывайте исторические события и не возобновляйте отправку приглашений только на основании запоздалого Webhook. См. раздел Часто задаваемые вопросы по группам Meta.