Jenis peristiwa interaksi aplikasi Google Chat

Halaman ini menjelaskan jenis peristiwa interaksi yang dapat diterima aplikasi Google Chat Anda dari Google Chat.

Untuk mengonfigurasi aplikasi Chat Anda agar menerima peristiwa interaksi, baca artikel Menerima dan merespons interaksi dengan aplikasi Chat Anda.

Format untuk peristiwa interaksi

Pengguna dapat berinteraksi dengan aplikasi Chat dalam berbagai cara. Untuk setiap jenis interaksi, Google Chat mengirimkan jenis peristiwa interaksi yang berbeda:

  • Pesan: Pengguna mengirim pesan ke aplikasi Chat Anda, atau memanggil aplikasi Chat Anda di sebuah ruang.
  • Ditambahkan ke ruang: Pengguna menambahkan aplikasi Chat Anda ke ruang.
  • Dihapus dari ruang: Pengguna menghapus aplikasi Chat Anda dari ruang.
  • Kartu diklik: Pengguna mengklik kartu atau dialog interaktif yang dikirim oleh aplikasi Chat Anda.

Setiap kali pengguna berinteraksi dengan aplikasi Chat Anda, Google Chat mengirim peristiwa interaksi dengan isi permintaan, yang merupakan payload JSON yang mewakili interaksi tersebut. Payload peristiwa ini berisi elemen yang umum untuk semua jenis peristiwa interaksi, serta elemen yang khusus untuk jenis peristiwa tersebut.

Untuk mempelajari kolom dalam peristiwa interaksi lebih lanjut, lihat dokumentasi referensi Event Google Chat API.

Bidang umum

Kolom berikut selalu disediakan dalam payload peristiwa interaksi:

Kolom Deskripsi
type Jenis peristiwa yang diterima aplikasi Chat, seperti MESSAGE atau ADDED_TO_SPACE.
eventTime Stempel waktu yang menunjukkan waktu peristiwa dikirim.
common Menampilkan informasi tentang klien pengguna, seperti lokal atau platform.

Kolom menurut jenis peristiwa interaksi

Bergantung pada jenis peristiwa, payload mungkin berisi kolom tambahan berikut:

Kolom Deskripsi Jenis peristiwa
message Pesan yang terkait dengan peristiwa. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space Ruang yang terkait dengan acara. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user Pengguna yang terkait dengan peristiwa. Pengguna selalu orang (bukan aplikasi Chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action Fungsi yang dipicu pengguna saat mereka mengklik kartu atau dialog interaktif. CARD_CLICKED.

Contoh payload peristiwa

Bagian ini menjelaskan hal yang memicu peristiwa interaksi dan memberikan contoh payload JSON untuk setiap jenis peristiwa berikut:

Pesan

Peristiwa interaksi ini menunjukkan saat seseorang mengirim pesan ke aplikasi Chat, seperti:

  • Pesan apa pun di ruang pesan langsung (DM) dengan aplikasi Chat.
  • Pesan di ruang yang berisi beberapa orang tempat seseorang @menyebut aplikasi Chat, atau menggunakan salah satu perintah garis miringnya.
  • Jika Anda telah mengonfigurasi pratinjau link untuk aplikasi Chat, pengguna akan memposting pesan yang berisi link yang cocok dengan pola URL yang dikonfigurasi.

Contoh JSON berikut menunjukkan peristiwa interaksi MESSAGE saat pengguna @menyebut aplikasi Chat di ruang dengan beberapa orang:

{
  "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"
  }
}

Ditambahkan ke ruang

Peristiwa interaksi ini menunjukkan bahwa aplikasi Chat Anda ditambahkan ke ruang. Aplikasi biasanya merespons peristiwa interaksi ini dengan memposting semacam pesan selamat datang dalam rangkaian pesan baru di ruang.

Contoh JSON berikut menunjukkan isi permintaan untuk peristiwa interaksi ADDED_TO_SPACE saat pengguna menambahkan aplikasi Chat ke ruang:

{
  "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"
  }
}

Diinstal oleh administrator Google Workspace

Peristiwa interaksi ADDED_TO_SPACE juga dapat menunjukkan bahwa administrator Google Workspace telah menginstal aplikasi Chat Anda untuk pengguna di organisasi mereka.

Administrator hanya dapat menginstal aplikasi Chat untuk pesan langsung antara aplikasi Chat dan pengguna. Aplikasi yang diinstal akan muncul di panel pesan langsung pengguna. Saat administrator menginstal aplikasi Chat, pengguna tidak dapat meng-uninstal-nya. Untuk mempelajari aplikasi Chat yang diinstal oleh administrator, lihat dokumentasi Bantuan Admin Google Workspace, Menginstal aplikasi Marketplace di domain Anda.

Contoh JSON berikut menunjukkan isi permintaan untuk peristiwa interaksi ADDED_TO_SPACE saat administrator Google Workspace menginstal aplikasi Chat untuk pengguna. Karena administrator menginstal aplikasi Chat, adminInstalled disetel ke 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"
  }
}

Dihapus dari ruang

Peristiwa interaksi ini menunjukkan bahwa aplikasi Chat Anda dihapus dari ruang. Aplikasi chat tidak merespons dengan pesan ke peristiwa ini, karena telah dihapus.

Contoh JSON berikut menampilkan isi permintaan untuk peristiwa interaksi REMOVED_FROM_SPACE saat pengguna menghapus aplikasi Chat dari ruang:

{
  "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"
  }
}

Di-uninstal oleh administrator Google Workspace

Peristiwa interaksi REMOVED_FROM_SPACE juga dapat menunjukkan bahwa administrator Google Workspace meng-uninstal aplikasi Chat Anda untuk pengguna di organisasi mereka. Jika di-uninstal, aplikasi Chat tidak akan muncul lagi di panel pesan langsung pengguna.

Jika pengguna menginstal aplikasi Chat Anda sebelum administrator, aplikasi Chat akan tetap terinstal bagi pengguna. Dalam hal ini, karena aplikasi Chat masih terinstal, aplikasi Chat tidak menerima peristiwa interaksi REMOVED_FROM_SPACE.

Contoh JSON berikut menunjukkan isi permintaan untuk peristiwa interaksi REMOVED_FROM_SPACE saat administrator Google Workspace meng-uninstal aplikasi Chat untuk pengguna. Karena aplikasi Chat telah di-uninstal oleh administrator, adminInstalled disetel ke 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"
  }
}

Kartu diklik

Peristiwa interaksi ini menunjukkan bahwa pengguna mengklik tombol dalam dialog atau pesan kartu.

Untuk menerima peristiwa interaksi, tombol harus memicu interaksi lain dengan aplikasi Chat. Misalnya, aplikasi Chat tidak menerima peristiwa interaksi CARD_CLICKED jika pengguna mengklik tombol yang membuka link ke situs, tetapi menerima peristiwa interaksi dalam contoh berikut:

  • Pengguna mengklik tombol Send feedback pada kartu, yang membuka dialog bagi pengguna untuk memasukkan informasi.
  • Pengguna mengklik tombol Submit setelah memasukkan informasi ke dalam kartu atau dialog.

Contoh JSON berikut menampilkan isi permintaan untuk peristiwa interaksi CARD_CLICKED saat pengguna mengklik tombol dalam pesan kartu yang menetapkan tiket dukungan masuk kepada mereka:

{
  "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
  }
}

Klik kartu untuk dialog

Saat pengguna berinteraksi dengan dialog, payload untuk peristiwa interaksi CARD_CLICKED menyertakan kolom tambahan berikut:

  • isDialogEvent: Menetapkan ke true untuk peristiwa interaksi yang melibatkan dialog.
  • DialogEventType: Jenis interaksi dengan dialog, termasuk jika pengguna membuka, mengirim, atau membatalkan dialog.

Contoh JSON berikut menunjukkan sebagian isi permintaan untuk peristiwa interaksi CARD_CLICKED. Dalam contoh ini, pengguna telah mengklik tombol dalam dialog yang mengirimkan informasi ke aplikasi Chat:

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

Untuk mempelajari cara memproses payload peristiwa interaksi dan menampilkan respons, lihat panduan berikut: