Управление группами | Документация для разработчиков
Управление группой
Обновлено: 25 марта 2026 г
Обзор
API для работы с группами предоставляет простые функции для управления группами на протяжении всего их жизненного цикла.
При создании новой группы создается ссылка-приглашение для приглашения участников в группу.
Поскольку добавлять участников в группу вручную невозможно, просто отправьте сообщение со ссылкой-приглашением пользователям WhatsApp, которых вы хотели бы пригласить в группу.
Функции управления группами
Чтобы узнать, как отправлять сообщения группам, обратитесь к справочнику по групповым сообщениям .
Подписаться на веб-хуки метаданных групп
Для получения уведомлений через веб-перехватчики о метаданных ваших групп, пожалуйста, подпишитесь на следующие поля веб-перехватчика:
group_lifecycle_updategroup_participants_updategroup_settings_updategroup_status_updateДля получения полной информации о веб-хуках для API групп, пожалуйста, посетите наш справочник по веб-хукам для API групп .
Создать группу
Используйте этот конечный пункт для создания новой группы и генерации ссылки-приглашения в группу.
После создания группы вы получите веб-хук с
invite_link , содержащим ссылку-приглашение в группу. Вы можете отправить эту ссылку-приглашение пользователям WhatsApp, заинтересованным в присоединении к группе.При желании вы можете создать группу, для присоединения к которой требуется подтверждение. Это означает, что если пользователь WhatsApp хочет присоединиться к вашей группе, вы можете одобрить или отклонить его запрос.
Синтаксис запроса
Создайте группу с начальной ссылкой-приглашением:
ПОЧТА /<BUSINESS_PHONE_NUMBER_ID> /группыТекст запроса
{ "messaging_product": "whatsapp", "subject": "<GROUP_SUBJECT> ", "описание": "<GROUP_DESCRIPTION> ", "join_approval_mode": "<JOIN_APPROVAL_MODE> " }Параметры запроса
| Заполнитель | Описание | Пример значения |
|---|---|---|
<BUSINESS_PHONE_NUMBER_ID>Нить | Необходимый Идентификатор номера служебного телефона. | 12784358810 |
<GROUP_SUBJECT>Нить | Необходимый Тематическое исследование. Максимальное количество символов: 128. Пробелы удаляются. | Запрос на новую покупку |
<GROUP_DESCRIPTION>Нить | Необязательный Описание группы. Максимальное количество символов: 2048. | Джим, наш постоянный клиент, хотел бы узнать о новых вариантах покупки автомобилей текущих годов выпуска. |
<JOIN_APPROVAL_MODE>Нить | Необязательный Указывает, могут ли пользователи WhatsApp, перешедшие по ссылке-приглашению, присоединиться к группе с предварительным одобрением или без него. Возможные значения: approval_required — Указывает, что пользователи WhatsApp должны получить одобрение в виде запроса на вступление, прежде чем смогут получить доступ к группе.auto_approve — Указывает, что пользователи WhatsApp могут присоединиться к группе без одобрения.Если параметр join_approval_mode по умолчанию устанавливается значение auto_approve | авто_одобрение |
Вебхуки
Запускается веб-перехватчик group_lifecycle_update
.Группа создает и добивается успеха
Создание группы не удалось
Пользователь присоединяется к группе по ссылке-приглашению
Группы, подающие заявки на вступление
Вы можете создавать группы, для присоединения к которым требуется подтверждение запроса. После включения этой функции пользователи WhatsApp, перешедшие по ссылке-приглашению в группу, смогут отправить запрос на вступление в группу или отменить ранее поданный запрос
Когда пользователь WhatsApp присоединяется к группе, отправляя запрос на вступление, срабатывает [
group_participants_update для пользователя, принявшего запрос на вступление] (/documentation/business-messaging/whatsapp/groups/webhooks#user-accepts-or-cancels-join-request). Вы также можете получить список открытых запросов на вступление через API . Используйте содержимое веб-хука или ответа API для одобрения или отклонения запросов.Получайте запросы на присоединение
Синтаксис запроса
ПОЛУЧАТЬ /<GROUP_ID> /join_requestsПараметры запроса
| Заполнитель | Описание | Пример значения |
|---|---|---|
<GROUP_ID>Нить | Необходимый. Идентификатор группы. | Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD |
Синтаксис ответа
В случае успеха:
{ "data": [ { "join_request_id": "<JOIN_REQUEST_ID> ", "wa_id": "<WHATSAPP_USER_ID> ", "creation_timestamp": "<JOIN_REQUEST_CREATION_TIMESTAMP"> }, // Дополнительные объекты запроса на присоединение будут добавлены, если таковые имеются ], "paging": { "cursors": { "before": "<BEFORE_CURSOR> ", "после": "<AFTER_CURSOR> " } } }Параметры отклика
| Заполнитель | Описание | Пример значения |
|---|---|---|
<JOIN_REQUEST_ID>Нить | Идентификатор запроса на присоединение. | MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw |
<WHATSAPP_USER_ID>Нить | Идентификатор пользователя WhatsApp. | 16505551234 |
<JOIN_REQUEST_CREATION_TIMESTAMP>Целое число | Временная метка Unix, указывающая на момент создания запроса на присоединение. | 1755548877 |
<BEFORE_CURSOR>Нить | Перед курсором. См. Результаты с постраничной разбивкой . | eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3NTU1NTM3MDUxNzUwNTQ1MTAifQZDZD |
<AFTER_CURSOR>Нить | После курсора. См. Результаты с постраничной разбивкой . | eyJvZAmZAzZAXQiOjAsInZAlcnNpb25JZACI6IjE3NTU1NTM3MDUxNzUwNTQ1MTAifQZDZD |
Одобрить запросы на присоединение
Синтаксис запроса
ПОЧТА /<GROUP_ID> /join_requestsТекст запроса
{ "messaging_product": "whatsapp", "join_requests": [ "<JOIN_REQUEST_ID> ", // Здесь будут указаны дополнительные идентификаторы запросов на присоединение, если они утверждаются массово ] }Параметры запроса
| Заполнитель | Описание | Пример значения |
|---|---|---|
<GROUP_ID>Нить | Необходимый. Идентификатор группы. | Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD |
Синтаксис ответа
В случае успеха API отправит следующий JSON-ответ, и пользователи WhatsApp, чьи запросы на вступление были одобрены, смогут получить доступ к группе, перейдя по ссылке-приглашению.
{ "messaging_product": "whatsapp", "approved_join_requests": [ "<JOIN_REQUEST_ID> ", // Здесь будут указаны дополнительные идентификаторы запросов на присоединение, они утверждаются массово ], // Включается только в случае невозможности утвердить один или несколько запросов на присоединение "failed_join_requests": [ { "join_request_id": "<JOIN_REQUEST_ID> ", "ошибки": [ { "код": "<ERROR_CODE> ", "сообщение": "<ERROR_MESSAGE> ", "заголовок": "<ERROR_TITLE> ", "error_data": { "details": "<ERROR_DETAILS> " } } ] } ], "ошибки": [ { "код": "<ERROR_CODE> ", "сообщение": "<ERROR_MESSAGE> ", "заголовок": "<ERROR_TITLE> ", "error_data": { "details": "<ERROR_DETAILS> " } } ] }Параметры отклика
| Заполнитель | Описание | Пример значения |
|---|---|---|
<JOIN_REQUEST_ID>Нить | Идентификатор одобренного запроса на присоединение или идентификатор неудачного запроса на присоединение, если мы не смогли его одобрить. | MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw |
<ERROR_CODE>Целое число | Код ошибки, если подтверждение не удалось. | 131203 |
<ERROR_MESSAGE>Нить | Сообщение об ошибке, если подтверждение не удалось. | (#131203) Получатель не принял наши новые Условия предоставления услуг и Политику конфиденциальности. |
<ERROR_TITLE>Нить | Заголовок сообщения об ошибке, если его не удалось утвердить. | Не удалось добавить участника в группу |
<ERROR_DETAILS>Нить | Подробности ошибки, если подтверждение не удалось. | Получатель не принял наши новые Условия предоставления услуг и Политику конфиденциальности. |
Вебхук
Запускается веб-перехватчик group_participants_update
.Отклонить запросы на присоединение
Синтаксис запроса
УДАЛИТЬ /<GROUP_ID> /join_requestsТекст запроса
{ "messaging_product": "whatsapp", "join_requests": [ "<JOIN_REQUEST_ID> ", //Здесь будут указаны дополнительные идентификаторы запросов на присоединение, они будут отклонены массово] }Параметры запроса
| Заполнитель | Описание | Пример значения |
|---|---|---|
<GROUP_ID>Нить | Необходимый. Идентификатор группы. | Y2FwaV9ncm91cDoxNzA1NTU1MDEzOToxMjAzNjM0MDQ2OTQyMzM4MjAZD |
<JOIN_REQUEST_ID>Нить | Необходимый. Идентификатор запроса на присоединение, который необходимо отклонить. | MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw |
Синтаксис ответа
В случае успеха API отправит следующий JSON-ответ, и пользователь WhatsApp снова увидит «Запрос на вступление» при переходе по ссылке-приглашению в группу.
{ "messaging_product": "whatsapp", "rejected_join_requests": [ "<JOIN_REQUEST_ID> ", //Здесь будут указаны дополнительные идентификаторы запросов на присоединение, так как они отклоняются одновременно ], //Включается только в том случае, если не удается отклонить один или несколько запросов на присоединение "failed_join_requests": [ { "join_request_id": "<JOIN_REQUEST_ID> ", "ошибки": [ { "код": "<ERROR_CODE> ", "сообщение": "<ERROR_MESSAGE> ", "заголовок": "<ERROR_TITLE> ", "error_data": { "details": "<ERROR_DETAILS> " } } ] } ], "ошибки": [ { "код": "<ERROR_CODE> ", "сообщение": "<ERROR_MESSAGE> ", "заголовок": "<ERROR_TITLE> ", "error_data": { "details": "<ERROR_DETAILS> " } } ] }Параметры отклика
| Заполнитель | Описание | Пример значения |
|---|---|---|
<JOIN_REQUEST_ID>Нить | Идентификатор отклоненного запроса на присоединение или идентификатор неудачного запроса на присоединение, если мы не смогли отклонить его. | MTY0NjcwNDM1OTU6MTIwMzYzNDA0Njk0MjMzODIw |
<ERROR_CODE>Целое число | Код ошибки, если отклонение невозможно. | 131203 |
<ERROR_MESSAGE>Нить | Сообщение об ошибке, если отклонить запрос не удалось. | (#131203) Получатель не принял наши новые Условия предоставления услуг и Политику конфиденциальности. |
<ERROR_TITLE>Нить | Заголовок сообщения об ошибке, если отклонить запрос не удалось. | Не удалось добавить участника в группу |
<ERROR_DETAILS>Нить | Подробности ошибки, если отклонить запрос не удалось. | Получатель не принял наши новые Условия предоставления услуг и Политику конфиденциальности. |
Вебхук
Никто.
Получить и сбросить ссылку-приглашение в группу
После сброса пригласительной ссылки все предыдущие пригласительные ссылки станут недействительными.
При создании группы генерируется ссылка-приглашение. Используйте эти конечные точки для получения и сброса ссылок-приглашений для группы.
Для каждой конечной точки вам потребуется идентификатор вашей группы, чтобы получить или сбросить ссылку для соответствующей группы следующим образом:
| Заполнитель | Описание | Пример значения |
|---|---|---|
<GROUP_ID>Нить | Необходимый Идентификатор группы, для которой вы хотите получить или сбросить ссылку-приглашение. | Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD |
Получить ссылку-приглашение в группу
Синтаксис запроса
ПОЛУЧАТЬ /<GROUP_ID> /invite_linkОтветный текст
{ "messaging_product": "whatsapp", "invite_link": "https://chat.whatsapp.com/<LINK_ID> " }Обратите внимание, что
invite_link всегда начинается с префикса https://chat.whatsapp.com/ . Единственная изменяемая часть — это .Сбросить ссылку-приглашение в группу
Синтаксис запроса
ПОЧТА /<GROUP_ID> /invite_linkТекст запроса
{ "messaging_product": "whatsapp", }Ответный текст
{ "messaging_product": "whatsapp", "invite_link": "https://chat.whatsapp.com/<LINK_ID> " }Отправить шаблон сообщения со ссылкой-приглашением в группу
Библиотека шаблонов содержит вспомогательные шаблоны сообщений для отправки ссылок-приглашений в группы пользователям WhatsApp. Используйте эти предварительно созданные шаблоны для отправки приглашений в группы в качестве вспомогательных сообщений.
Чтобы шаблон оставался платным
, его нельзя изменять при копировании из библиотеки шаблонов в ваш WABA-архив.Чтобы отправить шаблонное сообщение:
Шаг 1. Добавьте шаблон ссылки-приглашения в группу в библиотеку шаблонов вашей учетной записи:
В менеджере WhatsApp
Через API
Вы можете запросить библиотеки шаблонов, применимые к ссылкам-приглашениям в группы, используя приведенный ниже запрос:
GET /message_template_library?category=utility&topic=group_invite_link&language=enУтверждение шаблона может занять до 24 часов. После утверждения вы сможете отправлять сообщения, используя этот шаблон.
Шаг 2. Отправьте сообщение по шаблону
Если вы укажете идентификатор группы в API-запросе, он будет автоматически преобразован в соответствующую ссылку-приглашение в группу при отправке сообщения.
Синтаксис запроса
ПОЧТА /<BUSINESS_PHONE_NUMBER_ID> /сообщенияПараметры конечной точки
| Заполнитель | Описание | Пример значения |
|---|---|---|
<BUSINESS_PHONE_NUMBER_ID>Целое число | Необходимый Идентификатор номера служебного телефона. | 13057863445 |
Текст запроса
curl --location 'https://graph.facebook.com/<API_VERSION> /<BUSINESS_PHONE_NUMBER_ID> /messages?access_token=' \ --header 'Content-Type: application/json' \ --data '{ "messaging_product": "whatsapp", "to": "<WHATSAPP_USER_PHONE_NUMBER> ", "type": "template", "template": { "name": "<TEMPLATE_NAME> ", "язык": { "код": "<TEMPLATE_LANGUAGE> " }, "components": [ { "type": "body", "parameters": [ { "type": "group_id", "group_id": "<GROUP_ID> " }, { ...дополнительные параметры } ] } ] } }'Вебхуки
Пользователь присоединяется к группе по ссылке-приглашению
Удалить группу
Этот конечный пункт удаляет группу и всех участников, включая компанию. Тело запроса не требуется.
Синтаксис запроса
УДАЛИТЬ /<GROUP_ID>Запрос свойств
| Заполнитель | Описание | Пример значения |
|---|---|---|
<GROUP_ID>Нить | Необходимый Идентификатор группы, которую вы хотите удалить. | Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD |
Вебхуки
Запускается веб-перехватчик group_lifecycle_update
.Удаление группы прошло успешно
Удаление группы не удаётся
Удалить участников группы
Используйте этот конечный пункт для удаления участников из группы.
Примечание: Если участник удален из группы, он больше не сможет присоединиться к группе по ссылке-приглашению.
Синтаксис запроса
УДАЛИТЬ /<GROUP_ID> /участникиТекст запроса
{ "messaging_product": "whatsapp", "participants": [ { "user": "<WHATSAPP_USER_PHONE_NUMBER> или<WHATSAPP_USER_ID> " }, { "пользователь": "<WHATSAPP_USER_PHONE_NUMBER> или<WHATSAPP_USER_ID> "" }, ... ] }Запрос свойств
| Заполнитель | Описание | Пример значения |
|---|---|---|
"участники": []Множество | Необязательный Указывает массив телефонных номеров или идентификаторов WhatsApp учетных записей. Рабочий телефонный номер, использованный для создания группы, всегда добавляется в группу в качестве создателя и администратора. | |
Вебхуки
Запускается веб-перехватчик group_participants_update
.Участник группы уходит
Получить информацию о группе
Используйте этот конечный пункт для получения метаданных об отдельной группе.
Примечание: если в параметрах запроса не указаны поля, будут возвращены только идентификатор группы и продукт для обмена сообщениями.
Синтаксис запроса
ПОЛУЧАТЬ /<GROUP_ID> ?fields=<FIELDS>Параметры конечной точки
| Заполнитель | Описание | Пример значения |
|---|---|---|
<GROUP_ID>Нить | Необходимый Идентификатор группы, из которой вы запрашиваете информацию. | Y2FwaV9ncm91cDoxOTUwNTU1MDA3OToxMjAzNjMzOTQzMjAdOTY0MTUZD |
<FIELDS>Нить | Необязательный Список полей, разделенных запятыми, для возврата. Если поля не переданы, возвращается только идентификатор группы. | "subject,description,participants,join_approval_mode" |
Доступные поля
| Поле | Описание | Пример возвращаемого значения |
|---|---|---|
режим_присоединения_одобренияНить | Указывает, могут ли пользователи WhatsApp, перешедшие по ссылке-приглашению, присоединиться к группе с предварительным одобрением или без него. Возможные значения: approval_required — Указывает, что пользователи WhatsApp должны получить одобрение в виде запроса на вступление, прежде чем смогут получить доступ к группе.auto_approve — Указывает, что пользователи WhatsApp могут присоединиться к группе без одобрения. | авто_одобрение |
предметНить | Тема для обсуждения в группе. | «Аналитические данные об искусственном интеллекте» |
описаниеНить | Описание группы, если оно было задано во время создания. | |
приостановленныйЛогический | Возвращает true , если группа была заблокирована WhatsApp. | ЛОЖЬ |
creation_timestampЦелое число | Временная метка UNIX в секундах, в которую была создана группа. | 683731200 |
участникиСписок | Список объектов {"wa_id": " , где является участником группы, о которой идет речь. | [{"wa_id": "2228675309"}, {"wa_id": "7693349922"}] |
общее_количество_участниковЦелое число | Общее количество участников группы, за исключением вашей компании. | 6 |
Пример ответа
{ "messaging_product": "whatsapp", "id": "<GROUP_ID> ", "предмет": "<SUBJECT> ", "creation_timestamp": "<TIMESTAMP> ", "приостановленный": "<SUSPENDED> ", "описание": "<DESCRIPTION> ", "total_participant_count": "<TOTAL_PARTICIPANT_COUNT> ", "участники": [ { "wa_id": "<WA_ID> " }, { "wa_id": "<WA_ID> " } ], "join_approval_mode": "<JOIN_APPROVAL_MODE> " }Привлекайте активные группы
Используйте этот конечный пункт для получения списка активных групп для заданного номера корпоративного телефона.
Синтаксис запроса
ПОЛУЧАТЬ /<BUSINESS_PHONE_NUMBER_ID> /группыПараметры запроса
?limit=<LIMIT> , // Необязательно &after=<AFTER_CURSOR> , // Необязательно &before=<BEFORE_CURSOR> // Необязательный
| Параметр | Описание |
|---|---|
<LIMIT>Необязательный | Количество групп, которые необходимо получить в запросе. Мин.: 1 | По умолчанию: 25 | Макс.: 1024 |
<BEFORE_CURSOR>Необязательный | Курсор, указывающий на начало страницы данных. Подробнее о постраничных результатах в Graph API можно узнать здесь. |
<AFTER_CURSOR>Необязательный | Курсор, указывающий на конец страницы данных. Подробнее о постраничных результатах в Graph API можно узнать здесь. |
Объект ответа
{ "data": { "groups": [ {"id": "GROUP_ID", "subject": SUBJECT, "created_at": "TIMESTAMP"}, {"id": "GROUP_ID", "subject": SUBJECT, "created_at": "TIMESTAMP"} … ] }, "paging": { "cursors": { "after": "MTAxNTExOTQ1MjAwNzI5NDE=", "before": "NDMyNzQyODI3OTQw" }, "previous": "https://graph.facebook.com/VERSION/PHONE_NUMBER_ID/groups?limit=10&before=NDMyNzQyODI3OTQw", "next": "https://graph.facebook.com/VERSION/PHONE_NUMBER_ID/groups?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE=" } }Параметры отклика
| Параметр | Описание |
|---|---|
данные[группы]Список | Список групп, каждая из которых содержит идентификатор группы, тему группы и метку времени UNIX для создания группы. |
пейджингОбъект | Объект пагинации. |
Обновить настройки группы
Используйте этот веб-хук для обновления темы, описания и фотографии вашей группы.
Синтаксис запроса
ПОЧТА /<GROUP_ID>Текст запроса
{ "messaging_product": "whatsapp", "subject": "<GROUP_SUBJECT> ", "profile_picture_file": "<FILE_PATH> ", "описание": "<GROUP_DESCRIPTION> ", }Запрос свойств
Примечание
| Заполнитель | Описание | Пример значения |
|---|---|---|
<FILE_PATH>Нить | Необязательный Путь к файлу изображения, хранящемуся в вашей локальной директории. Для загрузки файла : следуйте той же структуре запроса, что и загрузки медиафайлов . Пример использования cURL для загрузки файла: Требование к групповой фотографии профиля: | /local/path/file.jpg |
<GROUP_SUBJECT>Нить | Необязательный Новая тема для группы. | «Любители часов» |
<GROUP_DESCRIPTION>Нить | Необязательный Новое описание группы. | |
Вебхуки
Запускается веб-перехватчик group_settings_update
.Обновление настроек группы прошло успешно
Обновление настроек группы частично завершилось с ошибкой
Обновление настроек группы завершилось неудачей
Веб-хуки статуса групповых сообщений
При отправке сообщения группе вы получаете веб-перехватчик статуса, когда сообщение доставлено или прочитано участниками группы.
Веб-хуки статусов для отдельных участников группы могут быть объединены в один веб-хук, содержащий несколько объектов
статуса statuses . Однако агрегирование не гарантируется. Если статусы нескольких участников генерируются приблизительно в одно и то же время, они могут быть объединены в один веб-хук. Если статусы генерируются в разное время, вы можете получать отдельные веб-хуки для каждого участника.Каждый веб-хук всегда ссылается только на одно сообщение, отправленное одной группе и имеющее один тип статуса (например,
доставлено ). Статусы для разных сообщений, групп или типов статусов никогда не объединяются в один веб-хук.Полный справочник по полезной нагрузке веб-перехватчика см. в справочнике по веб-перехватчикам сообщений о состоянии .
Информация о ценах
Сообщения о состоянии , содержащие веб-хуки с информацией о ценах, будут иметь
установить один из следующих вариантов:group_marketing — Обозначает групповое маркетинговое обсуждение.group_utility — Указывает на групповой разговор.group_service — Указывает на групповой диалог службы.