Các loại sự kiện tương tác với ứng dụng trong 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ủa bạn 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à trả lời các lượt tương tác với ứng dụng Chat.

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

Người dùng có thể tương tác với các ứng dụng trong Chat 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 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 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 không gian.
  • Đã nhấp vào thẻ: Người dùng nhấp vào thẻ hoặc hộp thoại tương tác do ứng dụng Chat 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 một 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 tải trọng của một sự kiện tương tác:

Trường Nội dung 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.

Các 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 Nội dung 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 nhấp vào một thẻ hoặc hộp thoại tương tác. CARD_CLICKED.

Ví dụ về tải trọng sự kiện

Phần này mô tả những yếu tố kích hoạt mộ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 bằng @hoặc sử dụng một trong các lệnh dấu gạch chéo.
  • 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 một thông báo chứa đường liên kết khớp với mẫu URL đã định cấu hình.

Ví dụ JSON sau đây minh hoạ một sự kiện tương tác MESSAGE, trong đó một người dùng đề cập đến một ứng dụng trong Chat 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 thông báo chào mừng trong một chuỗi mới trong không gian.

Ví dụ JSON sau đây thể hiện nội dung yêu cầu của một 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 một 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ần cài đặt sẽ xuất hiện trong bảng tin nhắn trực tiếp của người dùng. Khi quản trị viên cài đặt các ứng dụng trong Chat, 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 trong Chat do quản trị viên cài đặt, hãy xem tài liệu trên 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 sau đây thể hiện nội dung yêu cầu của một sự kiện tương tác ADDED_TO_SPACE khi một quản trị viên Google Workspace cài đặt một ứng dụng Chat cho một 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 ứ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 thể hiện nội dung yêu cầu của một 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"
  }
}

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 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 tin nhắn trực tiếp của người dùng nữa.

Nếu người dùng đã cài đặt ứng dụng Chat trước khi 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 sẽ không nhận được sự kiện tương tác REMOVED_FROM_SPACE.

Ví dụ JSON sau đây cho thấy nội dung yêu cầu của một sự kiện tương tác REMOVED_FROM_SPACE khi quản trị viên Google Workspace gỡ cài đặt một ứng dụng Chat của một 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 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ẻ. Khi đó, một hộp thoại sẽ mở ra để 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 sau đây thể hiệ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ẽ gán 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ẻ cho 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 sau đây cho thấy một phần của nội dung yêu cầu cho một 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ý tải trọng của sự kiện tương tác và trả về một phản hồi, hãy xem các hướng dẫn sau: