Định cấu hình API Google Chat

Mỗi ứng dụng Google Chat mà bạn tạo đều cần có dự án trên đám mây của Google Cloud riêng, trong đó Chat API được bật và định cấu hình.

Để thực hiện các lệnh gọi API chỉ có thể đọc bằng tính năng xác thực người dùng, chẳng hạn như lấy không gian và liệt kê tin nhắn, bạn chỉ cần bật API và tạo ứng dụng OAuth.

Để thực hiện các lệnh gọi API tạo, cập nhật và xoá, hoặc để triển khai và kiểm thử một ứng dụng Chat tương tác (được xây dựng dưới dạng tiện ích bổ sung của Google Workspace giúp mở rộng Chat), bạn cũng phải định cấu hình API Chat. Chế độ cài đặt cấu hình Chat API là nơi bạn chỉ định tất cả thông tin chi tiết về ứng dụng Chat, bao gồm cả tên hiển thị, hình đại diện, điểm cuối triển khai và các tính năng tương tác.

Điều kiện tiên quyết

Chọn tên hiển thị, hình đại diện và nội dung mô tả cho ứng dụng Chat của bạn

Khi bật Chat API, bạn sẽ định cấu hình thông tin chi tiết về ứng dụng Chat mà người dùng nhìn thấy trong Chat, bao gồm tên hiển thị, hình đại diện và nội dung mô tả. Những thông tin này chỉ xuất hiện trong Chat. Để xuất bản ứng dụng Chat lên Marketplace, bạn cũng phải chỉ định thông tin chi tiết xuất hiện trong trang thông tin của ứng dụng Chat trên Marketplace.

Trước khi định cấu hình ứng dụng Chat, hãy chuẩn bị những thông tin sau:

Trường Mô tả Định dạng
Tên ứng dụng Tên hiển thị của ứng dụng Chat. Tối đa 25 ký tự chữ-số
URL hình đại diện Hình ảnh hiển thị dưới dạng hình đại diện của ứng dụng Chat. Một URL loại HTTPS trỏ đến hình ảnh đồ hoạ hình vuông (PNG hoặc JPEG). Kích thước đề xuất là 256 x 256 pixel trở lên.
Mô tả Nội dung mô tả ngắn về ứng dụng Chat, xuất hiện khi người dùng tìm ứng dụng trong Chat. Tối đa 40 ký tự chữ-số
Nội dung mô tả dài Không bắt buộc. Nội dung mô tả về những việc mà ứng dụng Chat có thể làm, xuất hiện khi người dùng bắt đầu cuộc trò chuyện với ứng dụng Chat hoặc mở trang chủ phiên cho một nhân viên hỗ trợ. Được cung cấp trong Chương trình Bản dùng trước cho nhà phát triển. Hiện chỉ được hỗ trợ khi cập nhật cấu hình ứng dụng bằng Google Cloud Console và không được hỗ trợ thông qua API tiện ích bổ sung của Google Workspace. Tối đa 250 ký tự

Tên, hình đại diện và nội dung mô tả của ứng dụng Chat sẽ xuất hiện cho người dùng trong giao diện người dùng của Chat. Đối với một số yêu cầu ghi của API Chat, Chat sử dụng thông tin này để ghi nhận các hành động mà ứng dụng Chat thực hiện trong Chat.

Ví dụ: nếu bạn gọi phương thức spaces.create(), Chat sẽ đưa tên của ứng dụng Chat vào phần mô tả về người đã tạo không gian, như trong hình sau:

Ứng dụng Google Chat tạo không gian cho người dùng.
Hình 1. Thông báo ghi nhận tác giả mà Chat hiển thị khi phương thức spaces.create() được dùng để tạo không gian thay mặt cho người dùng.

Để tương tác với ứng dụng Chat, người dùng cũng có thể xem hoặc sử dụng thông tin này theo những cách sau:

  • @đề cập đến ứng dụng Chat để thêm ứng dụng đó vào không gian hoặc gửi tin nhắn cho ứng dụng đó.
  • Tìm và bắt đầu một tin nhắn trực tiếp với ứng dụng Chat. Trong trình đơn Ứng dụng, tin nhắn trực tiếp sẽ hiển thị tên và hình đại diện của ứng dụng Chat.
  • Trên thanh soạn tin, người dùng có thể duyệt xem các ứng dụng Chat và xem tên, hình đại diện cũng như nội dung mô tả của các ứng dụng đó.

Định cấu hình ứng dụng Chat trong Google Cloud Console

Khi bạn có thông tin chi tiết về ứng dụng Chat, hãy mở dự án trên Cloud và định cấu hình API Chat:

  1. Trong Google Cloud Console, hãy chuyển đến trang Chat API rồi nhấp vào trang Configuration (Cấu hình):

    Chuyển đến trang Cấu hình Chat API

  2. Trong phần Application info (Thông tin ứng dụng), hãy điền vào các trường App name (Tên ứng dụng), Avatar URL (URL hình đại diện) và Description (Nội dung mô tả).

  3. Không bắt buộc: Điền vào trường Nội dung mô tả dài (được cung cấp trong Chương trình Bản dùng trước cho nhà phát triển của Google Workspace).

  4. Không bắt buộc: Trong trình đơn Cú pháp đánh dấu, hãy chọn cú pháp đánh dấu mặc định (Markdown hoặc Chat) cho tin nhắn của ứng dụng Chat. Để tìm hiểu thêm về định dạng văn bản và cách Chat xác định cú pháp đánh dấu cho các yêu cầu API, hãy xem bài viết Định dạng tin nhắn.

  5. Trong phần Tính năng tương tác, hãy định cấu hình xem ứng dụng Chat của bạn có phản hồi các hoạt động tương tác của người dùng hay không:

    Để tạo một ứng dụng Chat có tính tương tác, hãy bật chế độ Bật tính năng tương tác rồi hoàn tất các bước sau:

    1. Trong phần Chức năng:
      • Không bắt buộc: Chọn Hỗ trợ Trang chủ ứng dụng để hiển thị thẻ trang chủ trong thẻ Trang chủ của tin nhắn trực tiếp 1:1 với ứng dụng Chat.
      • Chọn Tham gia không gian và cuộc trò chuyện nhóm để người dùng có thể cài đặt và sử dụng ứng dụng Chat của bạn. Theo mặc định, người dùng có thể cài đặt và nhắn tin với ứng dụng Chat trong một không gian riêng giữa người dùng và ứng dụng Chat. Người dùng cũng có thể thêm và tương tác với ứng dụng Chat trong không gian có nhiều người.
    2. Trong phần Cài đặt kết nối, hãy chọn cấu trúc mà bạn muốn dùng để nhận đối tượng sự kiện từ Chat:

      • Để sử dụng dịch vụ HTTP, hãy chọn URL điểm cuối HTTP rồi cung cấp một URL.
      • Để sử dụng một dự án Google Apps Script, hãy chọn Apps Script rồi cung cấp mã triển khai cho dự án đó.
      • Để sử dụng một tác nhân Dialogflow, hãy chọn Dialogflow, chọn Dialogflow CX hoặc Dialogflow ES, rồi cung cấp tên tài nguyên của tác nhân.
      • Để sử dụng Pub/Sub, hãy chọn Cloud Pub/Sub rồi nhập tên chủ đề.
    3. Không bắt buộc: Để định tuyến đối tượng sự kiện đến các điểm cuối hoặc hàm cụ thể, hãy chuyển đến phần Cài đặt kết nối > Trình kích hoạt rồi cung cấp hoặc cập nhật các điểm cuối hoặc hàm gọi lại cho các Trình kích hoạt Chat sau:

      • Trang chủ của ứng dụng (nếu bạn bật chế độ Hỗ trợ trang chủ của ứng dụng): Người dùng mở thẻ Trang chủ trong tin nhắn trực tiếp 1:1 bằng ứng dụng Chat.
      • Đã thêm vào không gian: Người dùng thêm ứng dụng Chat vào một cuộc trò chuyện nhóm hoặc không gian, hoặc cài đặt ứng dụng Chat cho tin nhắn trực tiếp.
      • Tin nhắn: Người dùng gửi tin nhắn đến ứng dụng Chat. Ví dụ: người dùng gửi tin nhắn trực tiếp đến ứng dụng Chat hoặc @đề_cập đến ứng dụng Chat trong một không gian có nhiều người.
      • Đã xoá khỏi không gian: Người dùng gỡ cài đặt hoặc xoá ứng dụng Chat khỏi không gian.
      • Lệnh trong ứng dụng: Người dùng gọi một lệnh nhanh, lệnh dấu gạch chéo hoặc hành động tin nhắn từ ứng dụng Chat.
    4. Không bắt buộc: Thêm các tính năng tương tác khác như phiên, câu lệnh mở đầu, lệnh (lệnh nhanh, lệnh dấu gạch chéo, và hành động đối với tin nhắn) hoặc bản xem trước đường liên kết.

    5. Trong phần Chế độ hiển thị, hãy chọn Cung cấp ứng dụng Chat này cho một số người và nhóm rồi nhập địa chỉ email của các cá nhân hoặc Nhóm Google trong tổ chức Google Workspace của bạn:

      • Để tự cài đặt và kiểm thử ứng dụng, hãy nhập địa chỉ email của riêng bạn.
      • Để chia sẻ ứng dụng Chat nội bộ với một nhóm hoặc toàn bộ tổ chức mà không cần xuất bản lên Marketplace, hãy nhập một hoặc nhiều nhóm trên Google Groups. Nhóm không có giới hạn về số lượng thành viên. Nếu ứng dụng của bạn yêu cầu phạm vi chat.app.*, bạn vẫn phải xuất bản ứng dụng để quản trị viên phê duyệt.
      • Nếu quản trị viên của bạn hạn chế việc cài đặt ứng dụng trên Marketplace đối với các ứng dụng trong danh sách cho phép, thì Google Cloud Console sẽ giới hạn trường này ở 5 địa chỉ email của người dùng cá nhân cho mục đích phát triển. Chế độ hiển thị của nhóm chỉ áp dụng sau khi quản trị viên thêm ứng dụng vào danh sách cho phép.
  6. Không bắt buộc: Trong phần Nhật ký, hãy chọn hộp đánh dấu Ghi lỗi vào Logging để sử dụng Google Cloud Logging. Để biết thêm thông tin, hãy xem bài viết Truy vấn nhật ký lỗi cho ứng dụng Chat.

  7. Nhấp vào Lưu.

Sau khi bạn lưu cấu hình, bất kỳ ai mà bạn chỉ định trong chế độ cài đặt Chế độ hiển thị của API Chat đều có thể cài đặt, thử nghiệm hoặc sử dụng ứng dụng Chat. Để bắt đầu thử nghiệm và gỡ lỗi ứng dụng Chat, hãy xem bài viết Thử nghiệm các tính năng tương tác cho ứng dụng Google Chat.

Định cấu hình ứng dụng Chat bằng API tiện ích bổ sung của Google Workspace

Thay vì định cấu hình ứng dụng Chat theo cách thủ công trong Google Cloud Console, bạn có thể sử dụng dự án trên đám mây của Google Cloud đã đăng ký tham gia Chương trình Bản dùng trước cho nhà phát triển Google Workspace để đọc và cập nhật cấu hình theo phương thức lập trình cho một ứng dụng Chat được xây dựng dưới dạng tiện ích bổ sung của Google Workspace bằng tài nguyên chatAppConfig trong Google Workspace add-ons API.

chatAppConfig là một tài nguyên đơn lẻ luôn tồn tại cho mỗi dự án trên đám mây. Trước khi bạn lưu cấu hình lần đầu tiên, tài nguyên sẽ chứa một cấu hình trống (đây cũng là nội dung mà GetChatAppConfig trả về nếu bạn đọc tài nguyên trước lần lưu đầu tiên). Vì tài nguyên đã tồn tại nên bạn không cần tạo riêng tài nguyên đó. Hãy sử dụng UpdateChatAppConfig để lưu cấu hình ban đầu và cập nhật cấu hình hiện có.

Điều kiện tiên quyết và xác thực

Trước khi gọi GetChatAppConfig hoặc UpdateChatAppConfig, hãy hoàn tất các điều kiện tiên quyết sau:

  1. Đăng ký dự án trên đám mây của bạn trên Google Cloud trong Chương trình Bản dùng trước cho nhà phát triển của Google Workspace.
  2. Bật API tiện ích bổ sung Google Workspace (gsuiteaddons.googleapis.com) trong dự án trên đám mây của bạn. Nếu muốn, bạn có thể bật Google Chat API (chat.googleapis.com) nếu muốn xem hoặc cập nhật cấu hình của ứng dụng Chat trong Google Cloud Console hoặc gọi Google Chat API.
  3. Xác thực với tư cách là người dùng bằng thông tin xác thực OAuth 2.0 bao gồm phạm vi https://www.googleapis.com/auth/cloud-platform. Phương thức xác thực tài khoản dịch vụ không được hỗ trợ cho các phương thức chatAppConfig.
  4. Đảm bảo người dùng đã xác thực có các quyền cần thiết về Quản lý danh tính và quyền truy cập (IAM) đối với dự án trên đám mây mục tiêu:
    • gsuiteaddons.chatAppConfigs.get và chat.bots.get để đọc cấu hình (GetChatAppConfig).
    • gsuiteaddons.chatAppConfigs.update và chat.bots.update để cập nhật cấu hình (UpdateChatAppConfig).
  5. Nếu bạn sử dụng thư viện ứng dụng, hãy tải thư viện ứng dụng Bản dùng trước cho nhà phát triển xuống bằng tài khoản Bản dùng trước cho nhà phát triển đã đăng ký.

Cập nhật cấu hình ứng dụng Chat

Để định cấu hình ứng dụng Chat lần đầu tiên hoặc cập nhật một cấu hình hiện có, hãy gửi yêu cầu PATCH (UpdateChatAppConfig) đến tài nguyên singleton chatAppConfig cho dự án trên đám mây của bạn:

  • Để lưu lần đầu trên một dự án trên đám mây có chatAppConfig trống, bạn cần có displayName (3 đến 25 ký tự) và description (1 đến 40 ký tự). Nếu bạn bỏ qua interactiveFeatureConfig trong lần lưu đầu tiên, ứng dụng Chat sẽ được định cấu hình là không tương tác.
  • Đối với các bản cập nhật tiếp theo, hãy sử dụng tham số truy vấn updateMask không bắt buộc để chỉ định các trường được phân tách bằng dấu phẩy cần cập nhật (hoặc bỏ qua updateMask để cập nhật tất cả các trường được cung cấp). Việc cập nhật một trường lặp lại (appCommands, urlPatterns hoặc allowlistedTestingPrincipals) sẽ thay thế toàn bộ danh sách.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Thay thế các thông tin sau trong URL, tiêu đề và nội dung của yêu cầu:

  • PROJECT_NUMBER: Số dự án dạng số của dự án trên đám mây lưu trữ ứng dụng Chat của bạn.
  • ACCESS_TOKEN: Mã truy cập OAuth 2.0 của người dùng được uỷ quyền với phạm vi https://www.googleapis.com/auth/cloud-platform.
  • USER_EMAIL: Địa chỉ email hoặc Nhóm Google trong tổ chức Google Workspace của bạn để đưa vào danh sách cho phép nhằm thử nghiệm ứng dụng Chat (ví dụ: địa chỉ email của chính bạn).
  • Các trường cấu hình mẫu trong nội dung yêu cầu (chẳng hạn như displayName, description, avatarUri và interactiveFeatureConfig, bao gồm cả cấu hình điểm cuối, lệnh, mẫu URL xem trước đường liên kết và đối tượng kiểm thử) bằng các giá trị cho ứng dụng Chat của bạn. Để biết thông tin chi tiết về tất cả các trường và tuỳ chọn điểm cuối được hỗ trợ, hãy xem tài liệu tham khảo về REST projects.chatAppConfig và projects.chatAppConfig.patch.

Lấy cấu hình ứng dụng Chat

Để đọc cấu hình ứng dụng Chat hiện tại cho một dự án trên đám mây, hãy gọi phương thức GetChatAppConfig. Bạn có thể truyền tham số truy vấn view không bắt buộc (ChatAppConfigView):

  • BASIC (mặc định): Trả về siêu dữ liệu cơ bản mà không có interactiveFeatureConfig.
  • FULL: Trả về tất cả các trường cấu hình, bao gồm cả interactiveFeatureConfig.

Nếu cấu hình ứng dụng Chat chưa được lưu cho dự án trên đám mây, thì phương thức này sẽ trả về một đối tượng ChatAppConfig trống.

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

Những điều cần lưu ý đối với các tiện ích bổ sung hiện có của Google Workspace

Ứng dụng Chat yêu cầu cấu hình khác so với các tiện ích bổ sung của Google Workspace giúp mở rộng các ứng dụng khác của Google Workspace. Nếu tiện ích bổ sung của bạn mở rộng các ứng dụng khác của Google Workspace, hãy cân nhắc các yêu cầu sau để định cấu hình ứng dụng Chat:

  • Cả cá nhân và quản trị viên Google Workspace đều phải cài đặt được tiện ích bổ sung của bạn từ Marketplace. Bạn định cấu hình các chế độ cài đặt này trong SDK của Marketplace.
  • Ứng dụng Chat không sử dụng tên và biểu trưng mà bạn định cấu hình cho các ứng dụng khác của Google Workspace trong đối tượng addons.common của tệp kê khai.
  • Đối với các tiện ích bổ sung được xuất bản lên Google Workspace Marketplace, bạn không thể lưu bản nháp của bất kỳ thay đổi nào đối với chế độ cài đặt cấu hình của Google Chat API. Sau khi bạn cập nhật và lưu chế độ cài đặt cấu hình API Chat, ứng dụng Chat đã cập nhật sẽ ngay lập tức được cung cấp cho tất cả người dùng hiện tại. Để cập nhật trang thông tin của bạn trên Marketplace, bạn có thể tạo bản nháp trước khi gửi mọi thay đổi.
  • Nếu bạn tạo tiện ích bổ sung bằng Apps Script:
  • Nếu bạn xây dựng tiện ích bổ sung bằng dịch vụ HTTP, hãy bỏ qua mọi thông tin chi tiết về cấu hình ứng dụng Chat trong tệp kê khai projects.deployments mà bạn tạo bằng API tiện ích bổ sung của Google Workspace. Các bản triển khai HTTP mà bạn chỉ định trong SDK Google Workspace Marketplace chỉ được dùng cho các ứng dụng khác của Google Workspace. Thay vào đó, hãy định cấu hình ứng dụng Chat trong Google Cloud Console hoặc sử dụng tài nguyên chatAppConfig trong API Tiện ích bổ sung của Google Workspace.

Cấp cho người khác quyền định cấu hình API Chat

Bạn có thể cấp cho một số người dùng quyền truy cập vào trang cấu hình ứng dụng Chat bằng cách cấp cho họ vai trò Quản lý danh tính và quyền truy cập (IAM) trên Google Cloud là Chủ sở hữu ứng dụng Chat hoặc Người xem ứng dụng Chat. Người dùng có các vai trò này không thể điều hướng đến trang cấu hình ứng dụng Chat bằng cách sử dụng trang tổng quan API và dịch vụ, nhưng có thể truy cập vào trang cấu hình bằng cách điều hướng đến Google Cloud Console cho dự án trên đám mây lưu trữ ứng dụng Chat như sau:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

Trong đó, PROJECT_ID là mã dự án của dự án trên Google Cloud lưu trữ ứng dụng Chat.

Ứng dụng Chat không phải là tiện ích bổ sung: Định cấu hình Google Chat API

Nếu bạn duy trì một ứng dụng Chat không phải là tiện ích bổ sung của Google Workspace, thì cấu hình của bạn sẽ sử dụng một điểm cuối duy nhất cho tất cả sự kiện tương tác thay vì trình kích hoạt theo sự kiện:

  1. Trong Google Cloud Console, hãy chuyển đến trang Cấu hình của Chat API:

    Chuyển đến trang Cấu hình Chat API

  2. Trong phần Tính năng tương tác, hãy bật chế độ Bật tính năng tương tác.

  3. Xoá Xây dựng ứng dụng Chat này dưới dạng tiện ích bổ sung của Google Workspace. Một hộp thoại sẽ mở ra để yêu cầu bạn xác nhận. Trong hộp thoại, hãy nhấp vào Tắt.

  4. Trong phần Chức năng, hãy chọn Hỗ trợ Trang chủ ứng dụng hoặc Tham gia không gian và cuộc trò chuyện nhóm nếu cần.

  5. Trong phần Cài đặt kết nối, hãy chỉ định một điểm cuối duy nhất cho ứng dụng Chat (URL điểm cuối HTTP, mã triển khai Apps Script, tên chủ đề Cloud Pub/Sub, hoặc Dialogflow).

  6. Định cấu hình các mục không bắt buộc như Lệnh, Bản xem trước đường liên kết, Chế độ hiển thị và Nhật ký, sau đó nhấp vào Lưu.

Để nâng cấp một ứng dụng Chat không phải là tiện ích bổ sung thành một tiện ích bổ sung của Google Workspace giúp mở rộng Google Chat, hãy xem bài viết Chuyển đổi ứng dụng Google Chat thành tiện ích bổ sung của Google Workspace.