Types d'événements liés aux interactions avec les applications Google Chat

Cette page décrit les types d'événements d'interaction que votre application Google Chat peut recevoir à partir de Google Chat.

Pour configurer votre application Chat afin de recevoir des événements d'interaction, consultez Recevoir des interactions avec votre application Chat et y répondre.

Formats pour les événements d'interaction

Les utilisateurs peuvent interagir avec les applications Chat de différentes manières. Pour chaque type d'interaction, Google Chat envoie un type d'événement d'interaction différent:

  • Message:un utilisateur envoie un message à votre application Chat ou appelle votre application Chat dans un espace.
  • Ajouté à l'espace:un utilisateur ajoute votre application Chat à un espace.
  • Supprimée de l'espace:un utilisateur supprime votre application Chat d'un espace.
  • Clic sur la fiche:un utilisateur clique sur une fiche ou une boîte de dialogue interactives envoyées par votre application Chat.

Chaque fois qu'un utilisateur interagit avec votre application Chat, Google Chat envoie un événement d'interaction avec un corps de requête, qui correspond à une charge utile JSON représentant l'interaction. Cette charge utile d'événement contient des éléments communs à tous les types d'événements d'interaction, ainsi que des éléments spécifiques au type d'événement.

Pour en savoir plus sur les champs d'un événement d'interaction, consultez la documentation de référence Event de l'API Google Chat.

Champs communs

Les champs suivants sont toujours fournis dans la charge utile d'un événement d'interaction:

Champ Description
type Type d'événement reçu par l'application Chat (par exemple, MESSAGE ou ADDED_TO_SPACE).
eventTime Horodatage indiquant le moment où l'événement a été envoyé.
common Représente les informations sur le client de l'utilisateur, telles que les paramètres régionaux ou la plate-forme.

Champs par type d'événement d'interaction

Selon le type d'événement, la charge utile peut contenir les champs supplémentaires suivants:

Champ Description Type d'événement
message Message lié à l'événement. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space Espace lié à l'événement. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE et CARD_CLICKED.
user Utilisateur lié à l'événement. L'utilisateur est toujours une personne (et non une application Chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE et CARD_CLICKED.
action Fonction déclenchée par un utilisateur lorsqu'il clique sur une fiche ou une boîte de dialogue interactives. CARD_CLICKED.

Exemples de charges utiles d'événement

Cette section décrit ce qui déclenche un événement d'interaction et fournit un exemple de charge utile JSON pour chacun des types d'événements suivants:

Message

Cet événement d'interaction représente une personne qui envoie un message à l'application Chat, par exemple:

  • Tout message d'un espace de message privé avec l'application Chat
  • Message dans un espace accueillant plusieurs personnes où une personne @mentionne l'application Chat ou utilise l'une de ses commandes à barre oblique.
  • Si vous avez configuré des aperçus de lien pour votre application Chat, un utilisateur publie un message contenant un lien correspondant au format d'URL configuré.

L'exemple JSON suivant montre un événement d'interaction MESSAGE dans lequel un utilisateur @mentionne une application Chat dans un espace comptant plusieurs personnes:

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Ajouté à l'espace

Cet événement d'interaction indique que votre application Chat a été ajoutée à un espace. Les applications répondent généralement à cet événement d'interaction en publiant un message de bienvenue dans un nouveau fil de discussion de l'espace.

L'exemple JSON suivant montre le corps de la requête pour un événement d'interaction ADDED_TO_SPACE lorsqu'un utilisateur ajoute une application Chat à un espace:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Installée par les administrateurs Google Workspace

L'événement d'interaction ADDED_TO_SPACE peut également indiquer qu'un administrateur Google Workspace a installé votre application Chat pour un utilisateur de son organisation.

Les administrateurs ne peuvent installer une application Chat que pour les messages privés entre l'application Chat et l'utilisateur. L'application installée apparaît dans le panneau de message privé des utilisateurs. Lorsque les administrateurs installent des applications Chat, les utilisateurs ne peuvent pas les désinstaller. Pour en savoir plus sur les applications Chat installées par les administrateurs, consultez Installer des applications Marketplace dans votre domaine dans la documentation de l'aide Administrateur Google Workspace.

L'exemple JSON suivant montre le corps de la requête pour un événement d'interaction ADDED_TO_SPACE lorsqu'un administrateur Google Workspace installe une application Chat pour un utilisateur. Étant donné qu'un administrateur a installé l'application Chat, adminInstalled est défini sur true:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Exclu de l'espace

Cet événement d'interaction indique que votre application Chat a été supprimée d'un espace. Les applications Chat ne répondent pas par des messages à cet événement, car elles ont déjà été supprimées.

L'exemple JSON suivant montre le corps de la requête pour un événement d'interaction REMOVED_FROM_SPACE lorsqu'un utilisateur supprime une application Chat d'un espace:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Désinstallée par des administrateurs Google Workspace

L'événement d'interaction REMOVED_FROM_SPACE peut également indiquer qu'un administrateur Google Workspace a désinstallé votre application Chat pour un utilisateur de son organisation. Lorsqu'elle est désinstallée, l'application Chat n'apparaît plus dans le panneau de message privé de l'utilisateur.

Si un utilisateur a installé votre application Chat avant l'administrateur, celle-ci reste installée pour l'utilisateur. Dans ce cas, comme l'application Chat est toujours installée, elle ne reçoit pas d'événement d'interaction REMOVED_FROM_SPACE.

L'exemple JSON suivant montre le corps de la requête pour un événement d'interaction REMOVED_FROM_SPACE lorsqu'un administrateur Google Workspace désinstalle une application Chat pour un utilisateur. Étant donné que l'application Chat a été désinstallée par un administrateur, adminInstalled est défini sur true:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Clic sur la fiche

Cet événement d'interaction indique qu'un utilisateur a cliqué sur un bouton dans un message ou une boîte de dialogue de fiche.

Pour recevoir un événement d'interaction, le bouton doit déclencher une autre interaction avec l'application Chat. Par exemple, une application Chat ne reçoit pas d'événement d'interaction CARD_CLICKED si un utilisateur clique sur un bouton qui ouvre un lien vers un site Web, mais reçoit des événements d'interaction dans les exemples suivants:

  • L'utilisateur clique sur le bouton Send feedback d'une fiche, ce qui ouvre une boîte de dialogue lui permettant de saisir des informations.
  • L'utilisateur clique sur un bouton Submit après avoir saisi des informations dans une fiche ou une boîte de dialogue.

L'exemple JSON suivant montre le corps de la requête pour un événement d'interaction CARD_CLICKED lorsqu'un utilisateur clique sur un bouton dans un message de fiche qui lui attribue une demande d'assistance entrante:

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

Clics sur les fiches pour les boîtes de dialogue

Lorsqu'un utilisateur interagit avec une boîte de dialogue, la charge utile de l'événement d'interaction CARD_CLICKED inclut les champs supplémentaires suivants:

  • isDialogEvent: défini sur true pour les événements d'interaction impliquant des boîtes de dialogue.
  • DialogEventType: type d'interaction avec la boîte de dialogue, y compris si un utilisateur ouvre, envoie ou annule une boîte de dialogue.

L'exemple JSON suivant montre une partie du corps d'une requête pour un événement d'interaction CARD_CLICKED. Dans cet exemple, l'utilisateur a cliqué sur un bouton dans une boîte de dialogue qui envoie des informations à l'application Chat:

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

Pour savoir comment traiter les charges utiles des événements d'interaction et renvoyer une réponse, consultez les guides suivants: