groupEvent

В группе или канале что-то изменилось: состав, админы, название, фото, группу удалили, появились заявки на вступление. Gratio присылает groupEvent и тогда, когда изменение сделал сам номер канала — с телефона или через API.

Пример

Олег исключил номер канала из группы MAX. Так приложение узнаёт об этом сразу, а не по ошибке следующего запроса:

{
  "typeWebhook": "groupEvent",
  "instanceData": {"idInstance": 7100000001, "wid": "79990000001@c.us", "typeInstance": "v3", "channel": "max"},
  "timestamp": 1792206959,
  "idMessage": "117454075298537298",
  "chatId": "-80040066617372",
  "chatName": "3А · Робототехника",
  "event": "participantRemoved",
  "platformEvent": "remove",
  "actor": {"chatId": "1111111", "name": "Олег", "self": false},
  "participants": [{"chatId": "457747484", "name": "Школа робототехники", "self": true}],
  "self": true,
  "title": "",
  "eventId": "msg:-80040066617372:117454075298537298"
}

Поля

У события группы нет senderData и messageData.

Виды событий

Номер канала исключили, он вышел или группу удалили — Gratio больше не берёт данные этой группы из кэша и не отслеживает в ней реакции.

Ещё примеры

Назначили админа

MAX не присылает служебного сообщения о смене админов, поэтому idMessage — ключ события Gratio:

{
  "typeWebhook": "groupEvent",
  "instanceData": {"idInstance": 7100000001, "wid": "79990000001@c.us", "typeInstance": "v3", "channel": "max"},
  "timestamp": 1792206960,
  "idMessage": "adminAdded:8695836:1792206960123",
  "chatId": "-80040066617372",
  "chatName": "3А · Робототехника",
  "event": "adminAdded",
  "platformEvent": "admins",
  "actor": null,
  "participants": [{"chatId": "8695836", "name": "Мария", "self": false}],
  "self": false,
  "title": "",
  "eventId": "grp:-80040066617372:adminAdded:8695836:1792206960123"
}

Переименовали

Новое название — в title, остальные поля — как в примере выше:

"event": "groupRenamed", "platformEvent": "title", "participants": [], "self": false,
"title": "3А · Робототехника и программирование"

Telegram

События приходят из служебных сообщений групп и каналов. platformEvent — действие Telegram:

• Вошёл сам — по ссылке, по одобренной заявке или по публичному адресу — participantJoinedByLink.
• События о действиях самого аккаунта через API (joinChat, answerJoinRequest, addGroupParticipant) тоже приходят.
• Смена админов в Telegram пока без событий. Удаления группы как события нет.

Мария вошла в супергруппу по ссылке:

{
  "typeWebhook": "groupEvent",
  "instanceData": {"idInstance": 7100000001, "wid": "79990000001@c.us", "typeInstance": "telegram", "channel": "telegram"},
  "timestamp": 1792207100,
  "idMessage": "5120",
  "chatId": "-1001234567890",
  "chatName": "3А · Робототехника",
  "event": "participantJoinedByLink",
  "platformEvent": "ChatJoinedByLink",
  "actor": {"chatId": "8617393401", "name": "Мария", "self": false},
  "participants": [{"chatId": "8617393401", "name": "Мария", "self": false}],
  "self": false,
  "title": "",
  "eventId": "msg:-1001234567890:5120"
}

joinRequested — новые заявки

Только Telegram: в вашу группу или канал просятся вступить. Служебного сообщения Telegram не шлёт, только число ждущих заявок и последних просившихся:

{
  "typeWebhook": "groupEvent",
  "instanceData": {"idInstance": 7100000001, "wid": "79990000001@c.us", "typeInstance": "telegram", "channel": "telegram"},
  "timestamp": 1792243200,
  "idMessage": "joinRequests:2:1792243200",
  "chatId": "-1001234567890",
  "chatName": "3А · Робототехника",
  "event": "joinRequested",
  "platformEvent": "PendingJoinRequests:2",
  "actor": null,
  "participants": [{"chatId": "8600000002", "name": "Олег", "self": false}],
  "self": false,
  "title": "",
  "eventId": "grp:-1001234567890:joinRequests:2:1792243200"
}

Число в platformEvent — сколько заявок ждёт ответа. Полный список — getJoinRequests, ответ на заявку — answerJoinRequest.

Как обработать

Перестать писать в группу, из которой исключили номер канала, и обновить состав:

def on_group_event(body: dict) -> None:
    if body["typeWebhook"] != "groupEvent":
        return
    group = body["chatId"]
    event = body["event"]
    if body["self"] and event in ("participantRemoved", "participantLeft", "groupDeleted"):
        disable_group(group)                       # отправка в группу больше не пройдёт
        return
    if event == "participantAdded":
        for p in body["participants"]:
            add_member(group, p["chatId"], p["name"])
    elif event in ("participantRemoved", "participantLeft"):
        for p in body["participants"]:
            remove_member(group, p["chatId"])
    elif event == "groupRenamed":
        rename_group(group, body["title"])
    elif event == "joinRequested":
        notify_admin(f"Новые заявки в {body['chatName']}: {body['platformEvent'].split(':')[1]}")

Что дальше

• getGroupData — состав и настройки группы.
• Группа для клиентов — группа с участниками по шагам.
• getJoinRequests — заявки на вступление.