Ссылка-приглашение в группу WhatsApp через API: получение и сброс
Чтобы получить ссылку-приглашение в группу WhatsApp через UnifyPort, вызовите GET /v1/accounts/{account_id}/groups/invite-code, передав group_id в параметрах запроса. Ответ содержит data.invite_url и data.invite_code. Получение ссылки не означает её сброс. В WhatsApp администратор может деактивировать ссылку и создать новую, но публичная документация UnifyPort описывает чтение, а не операцию сброса.
Главное
- Выбирайте аккаунт обмена сообщениями и группу вместе: код приглашения не является ID группы.
- Выполняйте запрос на сервере и показывайте ссылку только уполномоченным сотрудникам.
- Разделяйте получение, распространение, одобрение вступления и сброс ссылки.
- После сброса в WhatsApp получите актуальную ссылку и замените копии, которыми управляет ваше приложение.
Что делает endpoint получения ссылки
Официальная справка WhatsApp о приглашении в группу описывает приглашение по ссылке и предупреждает, что получатели могут пересылать её другим людям. Там же описана возможность администратора деактивировать ссылку и создать новую. Это действие в приложении нельзя приравнивать к чтению через API.
Документация UnifyPort определяет более узкий контракт:
| Входные или выходные данные | Значение |
|---|---|
account_id в пути | Подключённый аккаунт, выполняющий операцию |
group_id в query | Идентификатор группы у провайдера |
data.invite_url | Полученный URL приглашения |
data.invite_code | Полученный код приглашения, не ID диалога |
В текущей матрице поддержки действий эта операция доступна для whatsapp, но не для LINE, Telegram, Zalo или отдельного провайдера whatsapp-protocol. Справка endpoint предупреждает, что у большинства провайдеров необходимы права администратора группы. Для этого сценария используйте разрешённый к работе аккаунт администратора WhatsApp и проверьте его текущие права. Доступ к API рабочего пространства сам по себе не даёт полномочий в группе.
Это неофициальный интерфейс для подключённого аккаунта, а не endpoint WhatsApp Cloud API.
Получение без раскрытия API-ключа
Сначала выберите группу нужного аккаунта через список групп. Он включает группы, в которые аккаунт вступил, даже если в них ещё не было переписки. Обработайте пагинацию и сохраните id выбранного элемента; для группы conversation_id равен id. Не определяйте цель только по отображаемому имени: оно может совпадать у разных групп.
Ниже приведён пример запроса, а не результат выполненного теста. В переменных окружения должны находиться серверный API-ключ, ID выбранного аккаунта и ID группы из списка:
curl --get \
"https://api.unifyport.ai/v1/accounts/${UNIFYPORT_ACCOUNT_ID}/groups/invite-code" \
-H "X-Api-Key: ${UNIFYPORT_API_KEY}" \
--data-urlencode "group_id=${WHATSAPP_GROUP_ID}"Идентификаторы провайдера могут содержать символы вроде @, поэтому параметры запроса нужно кодировать. Храните ключ на сервере: не переносите этот авторизованный запрос в браузерный JavaScript.
При успешном ответе прочитайте data.invite_url и data.invite_code. Не пытайтесь построить URL приглашения из ID группы. Если запрос завершился ошибкой или ожидаемая ссылка отсутствует, покажите ошибку либо недоступность, а не выдуманное значение.
Для диагностики сохраняйте HTTP-статус, код ошибки и серверный request_id. Руководство по трассировке запросов объясняет, как сохранять доказательства без записи всего тела ответа. Здесь оно содержит ссылку-приглашение, которой не место в аналитике и общих журналах приложения.
Разные намерения — разные элементы управления
| Элемент интерфейса | Назначение | Чего он не означает |
|---|---|---|
| Показать текущую ссылку | Прочитать и показать ответ API | Создана новая ссылка |
| Скопировать ссылку | Скопировать URL для разрешённого распространения | Человек уже вступил в группу |
| Проверить заявки | Открыть процесс модерации | Ссылка сброшена |
| Сбросить ссылку | Направить администратора к действию в WhatsApp | Существует документированный вызов сброса UnifyPort |
Перед показом или копированием проверяйте права сотрудника в вашем приложении. Не размещайте ссылку на публичных панелях, скриншотах для поддержки или в свойствах аналитических событий. Если результат кэшируется, помечайте его как ранее полученный, не обещая, что он всё ещё действителен.
Одобрение вступления — отдельный процесс. Если нужна модерация, используйте очередь заявок в группу WhatsApp, где список ожидающих заявок проверяется перед решением. Получение ссылки не включает режим одобрения и не одобряет заявителя.
Обновление копий после сброса в WhatsApp
Рассмотрим гипотетический сценарий: администратор считает, что приглашение распространилось слишком широко, и сбрасывает ссылку в WhatsApp. В вашем приложении при этом остаётся старый URL.
Рекомендуемый порядок действий:
- Приостановите распространение кэшированной ссылки на время действий администратора.
- Повторно получите ссылку для того же аккаунта и группы.
- Покажите свежий результат уполномоченному сотруднику для проверки.
- Замените ссылки, которыми управляет приложение, и QR-изображения, созданные из старого URL.
- Попросите владельцев других каналов распространения проверить свои копии.
Это рекомендации по эксплуатации, а не функция атомарной ротации. Публичная документация не определяет параметр сброса, endpoint сброса, время истечения ссылки или специальный webhook подтверждения сброса. Не добавляйте предполагаемые поля и не считайте отсутствие события доказательством неизменности ссылки. Если повторное чтение не удалось, оставьте распространение приостановленным или явно обозначьте неопределённость вместо незаметного возврата к старому кэшу.
Частые вопросы
Создаёт ли каждый вызов invite-code новую ссылку?
Документированная операция получает ссылку и код. Создание новой ссылки или ротация при каждом чтении не обещаны.
Можно ли передать invite_code как group_id?
Нет. Используйте ID группы провайдера, выбранной под подключённым аккаунтом. Код приглашения — отдельное возвращаемое значение.
Можно ли сбросить ссылку через этот API?
В текущей публичной документации такой операции нет. Используйте действие администратора в WhatsApp, затем снова получите актуальную ссылку.
Ошибка чтения означает, что группа удалена?
Нет. Проверьте HTTP-статус и подробности ошибки. get_group_invite_code_failed обозначает сбой получения на сервере или у вышестоящего сервиса, а не подтверждает удаление группы.
Следующий шаг и источники
Начните с реализации чтения по документации Get group invite link. Перед запуском проверьте выбор группы, недостаточные права, кодирование query, отсутствие секретных данных в логах и обновление копии после разрешённого сброса в WhatsApp. Это предлагаемые проверки, а не отчёт об уже проведённых тестах.
Источники проверены 2026-10-15:
Превратите интеграцию сообщений в стабильный продуктовый pipeline.
Начните с отправки через единый API, затем возвращайте входящие сообщения в бизнес-систему стандартными событиями.