Cette page a été traduite par l'API Cloud Translation.

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 qu'elle reçoive des événements d'interaction, consultez la page 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 une carte:un utilisateur clique sur une fiche ou une boîte de dialogue interactive envoyée 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 est 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 sur 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 de l'événement reçu par l'application Chat, par exemple `MESSAGE` ou `ADDED_TO_SPACE`.
`eventTime`	Horodatage indiquant l'heure d'envoi de l'événement.
`common`	Représente des 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 associé à l'événement.	`MESSAGE`, `ADDED_TO_SPACE`, `REMOVED_FROM_SPACE` et `CARD_CLICKED`.
`user`	Utilisateur associé à 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 interactive.	`CARD_CLICKED`.

Exemples de charges utiles d'événements

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 (MESSAGE)
Ajouté à l'espace (ADDED_TO_SPACE)
Supprimé de l'espace (REMOVED_FROM_SPACE)
Clic sur une fiche (CARD_CLICKED)

Message

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

Tous les messages d'un espace de message privé (MP) avec l'application Chat
Message envoyé dans un espace avec plusieurs personnes dans lequel 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 illustre un événement d'interaction MESSAGE dans lequel un utilisateur @mentionne une application Chat dans un espace avec 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 la section Installer des applications Marketplace dans votre domaine de la documentation d'aide pour les administrateurs 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 de chat ne renvoient pas de 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 les 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. Une fois 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, cette application reste installée pour l'utilisateur. Dans ce cas, étant donné que 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. Comme 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 une carte

Cet événement d'interaction indique qu'un utilisateur a cliqué sur un bouton dans un message ou une boîte de dialogue de la 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 dans laquelle il peut saisir des informations.
L'utilisateur clique sur un bouton Submit après avoir saisi des informations dans une carte 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",
}

Articles associés

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