Các loại sự kiện tương tác với ứng dụng Google Chat

Trang này mô tả các loại sự kiện tương tác mà ứng dụng Google Chat có thể nhận được từ Google Chat.

Để định cấu hình ứng dụng Chat nhằm nhận các sự kiện tương tác, hãy xem phần Nhận và phản hồi các lượt tương tác bằng ứng dụng Chat.

Định dạng cho sự kiện tương tác

Người dùng có thể tương tác với các ứng dụng nhắn tin theo nhiều cách. Đối với mỗi loại tương tác, Google Chat sẽ gửi một loại sự kiện tương tác khác nhau:

  • Tin nhắn: Người dùng gửi tin nhắn cho ứng dụng Chat của bạn hoặc gọi ứng dụng Chat trong một không gian.
  • Đã thêm vào không gian: Người dùng thêm ứng dụng Chat của bạn vào một không gian.
  • Bị xoá khỏi không gian: Một người dùng xoá ứng dụng Chat của bạn khỏi một không gian.
  • Đã nhấp vào thẻ: Người dùng nhấp vào hộp thoại hoặc thẻ tương tác do ứng dụng Chat của bạn gửi.

Mỗi khi người dùng tương tác với ứng dụng Chat, Google Chat sẽ gửi một sự kiện tương tác kèm theo nội dung yêu cầu. Đây là tải trọng JSON đại diện cho hoạt động tương tác đó. Tải trọng sự kiện này chứa các phần tử phổ biến cho tất cả các loại sự kiện tương tác, cũng như các phần tử dành riêng cho loại sự kiện.

Để tìm hiểu thêm về các trường trong một sự kiện tương tác, hãy xem tài liệu tham khảo về Event của API Google Chat.

Trường phổ biến

Các trường sau luôn được cung cấp trong trọng tải của một sự kiện tương tác:

Trường Mô tả
type Loại sự kiện mà ứng dụng Chat đang nhận, chẳng hạn như MESSAGE hoặc ADDED_TO_SPACE.
eventTime Dấu thời gian cho biết thời điểm sự kiện được gửi đi.
common Biểu thị thông tin về ứng dụng của người dùng, chẳng hạn như ngôn ngữ hoặc nền tảng.

Trường theo loại sự kiện tương tác

Tuỳ thuộc vào loại sự kiện, tải trọng có thể chứa các trường bổ sung sau:

Trường Mô tả Loại sự kiện
message Tin nhắn liên quan đến sự kiện. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space Không gian liên quan đến sự kiện. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user Người dùng liên quan đến sự kiện. Người dùng luôn là một người (không phải ứng dụng Chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action Hàm mà người dùng kích hoạt khi họ nhấp vào một thẻ hoặc hộp thoại tương tác. CARD_CLICKED.

Ví dụ về gói dữ liệu sự kiện

Phần này mô tả những yếu tố kích hoạt sự kiện tương tác và cung cấp tải trọng JSON mẫu cho từng loại sự kiện sau:

Thông điệp

Sự kiện tương tác này biểu thị thời điểm một người gửi tin nhắn đến ứng dụng Chat, chẳng hạn như:

  • Bất kỳ tin nhắn nào trong không gian tin nhắn trực tiếp (DM) bằng ứng dụng Chat.
  • Tin nhắn trong không gian nhiều người, trong đó một người đề cập đến ứng dụng Chat hoặc sử dụng một trong các lệnh dấu gạch chéo của ứng dụng đó.
  • Nếu bạn đã định cấu hình bản xem trước đường liên kết cho ứng dụng Chat, thì người dùng sẽ đăng tin nhắn chứa đường liên kết khớp với mẫu URL đã định cấu hình.

Ví dụ JSON sau đây thể hiện một sự kiện tương tác MESSAGE, trong đó người dùng đề cập đến một ứng dụng trong Chat bằng @ trong một không gian có nhiều người:

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

Đã thêm vào không gian

Sự kiện tương tác này cho biết rằng ứng dụng Chat của bạn đã được thêm vào một không gian. Các ứng dụng thường phản hồi sự kiện tương tác này bằng cách đăng một số loại tin nhắn chào mừng trong một chuỗi mới trong không gian.

Ví dụ JSON dưới đây cho thấy phần nội dung yêu cầu cho sự kiện tương tác ADDED_TO_SPACE khi người dùng thêm ứng dụng Chat vào một không gian:

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

Do quản trị viên Google Workspace cài đặt

Sự kiện tương tác ADDED_TO_SPACE cũng có thể cho biết rằng quản trị viên Google Workspace đã cài đặt ứng dụng Chat cho một người dùng trong tổ chức của họ.

Quản trị viên chỉ có thể cài đặt ứng dụng Chat cho tin nhắn trực tiếp giữa ứng dụng Chat và người dùng. Ứng dụng đã cài đặt sẽ xuất hiện trong bảng thông báo trực tiếp của người dùng. Khi quản trị viên cài đặt các ứng dụng nhắn tin, người dùng sẽ không thể gỡ cài đặt các ứng dụng đó. Để tìm hiểu về các ứng dụng nhắn tin do quản trị viên cài đặt, hãy xem tài liệu trong trang Trợ giúp dành cho quản trị viên Google Workspace, Cài đặt các ứng dụng trên Marketplace trong miền của bạn.

Ví dụ JSON dưới đây thể hiện phần nội dung yêu cầu cho sự kiện tương tác ADDED_TO_SPACE khi quản trị viên Google Workspace cài đặt một ứng dụng nhắn tin cho người dùng. Vì quản trị viên đã cài đặt ứng dụng Chat, nên adminInstalled được đặt thành 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"
  }
}

Đã xoá khỏi không gian

Sự kiện tương tác này cho biết rằng ứng dụng Chat của bạn đã bị xoá khỏi một không gian. Các ứng dụng nhắn tin không phản hồi bằng tin nhắn cho sự kiện này vì các ứng dụng đó đã bị xoá.

Ví dụ JSON sau đây cho thấy phần nội dung yêu cầu cho sự kiện tương tác REMOVED_FROM_SPACE khi người dùng xoá ứng dụng Chat khỏi một không gian:

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

Đã bị quản trị viên Google Workspace gỡ cài đặt

Sự kiện tương tác REMOVED_FROM_SPACE cũng có thể cho biết rằng một quản trị viên Google Workspace đã gỡ cài đặt ứng dụng Chat của bạn cho một người dùng trong tổ chức của họ. Khi bị gỡ cài đặt, ứng dụng Chat sẽ không còn xuất hiện trong bảng thông báo trực tiếp của người dùng.

Nếu người dùng đã cài đặt ứng dụng Chat trước quản trị viên, thì ứng dụng Chat vẫn được cài đặt cho người dùng đó. Trong trường hợp này, vì ứng dụng Chat vẫn được cài đặt, nên ứng dụng Chat không nhận được sự kiện tương tác REMOVED_FROM_SPACE.

Ví dụ JSON dưới đây thể hiện phần nội dung yêu cầu cho sự kiện tương tác REMOVED_FROM_SPACE khi quản trị viên Google Workspace gỡ cài đặt ứng dụng Chat của người dùng. Vì quản trị viên đã gỡ cài đặt ứng dụng Chat, nên adminInstalled được đặt thành 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"
  }
}

Đã nhấp vào thẻ

Sự kiện tương tác này cho biết rằng người dùng đã nhấp vào một nút trong thông báo hoặc hộp thoại trên thẻ.

Để nhận được một sự kiện tương tác, nút này phải kích hoạt một lượt tương tác khác với ứng dụng Chat. Ví dụ: ứng dụng Chat sẽ không nhận được sự kiện tương tác CARD_CLICKED nếu người dùng nhấp vào nút mở ra đường liên kết đến một trang web, nhưng lại nhận được các sự kiện tương tác trong các ví dụ sau:

  • Người dùng nhấp vào nút Send feedback trên một thẻ, thao tác này sẽ mở ra một hộp thoại để người dùng nhập thông tin.
  • Người dùng nhấp vào nút Submit sau khi nhập thông tin vào thẻ hoặc hộp thoại.

Ví dụ JSON dưới đây thể hiện phần nội dung yêu cầu cho một sự kiện tương tác CARD_CLICKED khi người dùng nhấp vào một nút trong thông báo thẻ sẽ chỉ định một phiếu yêu cầu hỗ trợ cho họ:

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

Số lượt nhấp vào thẻ để mở hộp thoại

Khi người dùng tương tác với một hộp thoại, tải trọng cho sự kiện tương tác CARD_CLICKED sẽ bao gồm các trường bổ sung sau:

  • isDialogEvent: Đặt thành true cho các sự kiện tương tác liên quan đến hộp thoại.
  • DialogEventType: Loại tương tác với hộp thoại, bao gồm cả việc người dùng mở, gửi hoặc huỷ hộp thoại.

Ví dụ JSON dưới đây cho thấy một phần của nội dung yêu cầu cho sự kiện tương tác CARD_CLICKED. Trong ví dụ này, người dùng đã nhấp vào một nút trong hộp thoại để gửi thông tin đến ứng dụng Chat:

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

Để tìm hiểu cách xử lý các gói dữ liệu của sự kiện tương tác và trả về một phản hồi, hãy xem hướng dẫn sau đây: