Chuyển tới nội dung chính

Thiết lập trò chuyện của Google

Kết nối Đại lý Hermes với Google Chat dưới dạng bot. Việc tích hợp sử dụng Cloud Pub/Sub kéo đăng ký cho các sự kiện gửi đến và API trò chuyện REST cho các tin nhắn gửi đi. Công thái học tương đương với Chế độ ổ cắm Slack hoặc bỏ phiếu dài trên Telegram: chiếc Hermes của bạn quá trình không cần URL công khai, đường hầm hoặc chứng chỉ TLS. Nó kết nối, xác thực và lắng nghe khi đăng ký - giống như cách bot Telegram lắng nghe trên một mã thông báo.

Phiên bản không gian làm việc

Google Chat là một phần của Google Workspace. Bạn có thể sử dụng sự tích hợp này với một Không gian làm việc cá nhân (@yourdomain.com được đăng ký thông qua Google) hoặc một công việc Không gian làm việc nơi bạn có quyền Quản trị viên để xuất bản ứng dụng. Tài khoản chỉ dành cho Gmail không thể lưu trữ ứng dụng Trò chuyện.

Tổng quan​

ComponentValue
Librariesgoogle-cloud-pubsub, google-api-python-client, google-auth
Inbound transportCloud Pub/Sub pull subscription (no public endpoint)
Outbound transportChat REST API (chat.googleapis.com)
AuthenticationService Account JSON with roles/pubsub.subscriber on the subscription
User identificationChat resource names (users/{id}) + email

Bước 1: Tạo hoặc chọn dự án GCP​

Bạn cần có dự án Google Cloud để lưu trữ chủ đề Pub/Sub. Nếu bạn không có một cái, tạo nó tại console.cloud.google.com — tài khoản cá nhân nhận được cấp độ miễn phí dễ dàng đáp ứng lưu lượng truy cập bot.

Lưu ý ID dự án (ví dụ: my-chat-bot-123). Bạn sẽ sử dụng nó trong mọi lần tiếp theo bước.

Bước 2: Kích hoạt hai API​

Trong bảng điều khiển, đi tới APIs & Services → Library và bật:

  • API trò chuyện của Google
  • Cloud Pub/Sub API

Cả hai đều miễn phí đối với khối lượng mà bot cá nhân tạo ra.

Bước 3: Tạo tài khoản dịch vụ​

IAM & Quản trị viên → Tài khoản dịch vụ → Tạo tài khoản dịch vụ.

  • Tên: hermes-chat-bot
  • Bỏ qua bước "Cấp quyền truy cập tài khoản dịch vụ này vào dự án". IAM trên cụ thể đăng ký là tất cả những gì bạn cần - KHÔNG cấp vai trò Pub/Sub cấp dự án.

Sau khi tạo, hãy mở SA, đi tới Keys → Add Key → Create new key → JSON và tải xuống tập tin. Hãy lưu nó ở nơi mà chỉ Hermes mới có thể đọc được (ví dụ: ~/.hermes/google-chat-sa.json, chmod 600).

KHÔNG có vai trò "Chat Bot Caller"

Một lỗi phổ biến là tìm kiếm vai trò IAM dành riêng cho Trò chuyện và cấp vai trò đó theo cấp dự án. Vai trò đó không tồn tại. Quyền của bot trò chuyện xuất phát từ việc được cài đặt trong không gian chứ không phải từ IAM. Tất cả nhu cầu SA của bạn là đăng ký Pub/Sub trên đăng ký bạn tạo ở bước tiếp theo.

Bước 4: Tạo chủ đề Pub/Sub và đăng ký​

Pub/Sub → Chủ đề → Tạo chủ đề.

  • ID chủ đề: hermes-chat-event
  • Để mặc định cho mọi thứ khác.

Sau khi tạo, trang chi tiết của chủ đề có tab Đăng ký. Tạo một:

  • ID đăng ký: hermes-chat-events-sub
  • Kiểu giao hàng: Kéo
  • Lưu giữ tin nhắn: 7 ngày (để tồn đọng vẫn tồn tại sau khi khởi động lại Hermes)
  • Các phần còn lại để mặc định.

Bước 5: IAM ràng buộc về chủ đề (quan trọng)​

Trên chủ đề (không phải đăng ký), hãy thêm tiền gốc IAM:

  • Hiệu trưởng: chat-api-push@system.gserviceaccount.com
  • Vai trò: Nhà xuất bản Pub/Sub

Nếu không có điều này, Google Chat không thể xuất bản các sự kiện theo chủ đề của bạn và bot của bạn sẽ không bao giờ nhận được bất cứ điều gì.

Bước 6: IAM ràng buộc đăng ký​

Trên đăng ký, thêm Tài khoản dịch vụ của riêng bạn làm tài khoản chính:

  • Hiệu trưởng: hermes-chat-bot@<your-project>.iam.gserviceaccount.com
  • Vai trò: Người đăng ký Pub/Sub

Đồng thời cấp Pub/Sub Viewer trên cùng một đăng ký - Hermes gọi subscription.get() khi khởi động để kiểm tra khả năng tiếp cận.

Bước 7: Cấu hình ứng dụng Chat​

Đi tới API và dịch vụ → API Google Chat → Cấu hình.

  • Tên ứng dụng: bất cứ điều gì bạn muốn người dùng nhìn thấy ("Hermes" là hợp lý).
  • URL hình đại diện: mọi PNG công khai (Google có một số giá trị mặc định).
  • Mô tả: một câu ngắn hiển thị trong thư mục ứng dụng.
  • Chức năng: bật Nhận tin nhắn 1:1 và Tham gia không gian và nhóm cuộc trò chuyện.
  • Cài đặt kết nối: chọn Cloud Pub/Sub, nhập tên chủ đề dự án/<your-project>/topics/hermes-chat-events.
  • Chế độ hiển thị: giới hạn ở không gian làm việc của bạn (hoặc người dùng cụ thể) — không xuất bản cho mọi người trong khi bạn đang kiểm tra.

Cứu.

Bước 8: Cài đặt bot vào không gian thử nghiệm​

Mở Google Trò chuyện trong trình duyệt. Bắt đầu DM với ứng dụng của bạn bằng cách tìm kiếm tên của nó trong menu + Trò chuyện mới. Lần đầu tiên bạn nhắn tin, Google sẽ gửi một Sự kiện ADDED_TO_SPACE mà Hermes sử dụng để lưu vào bộ nhớ đệm người dùng/{id} của bot cho tự lọc tin nhắn.

Bước 9: Cấu hình Hermes​

Thêm phần Google Chat vào ~/.hermes/.env:

# Required
GOOGLE_CHAT_PROJECT_ID=my-chat-bot-123
GOOGLE_CHAT_SUBSCRIPTION_NAME=projects/my-chat-bot-123/subscriptions/hermes-chat-events-sub
GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=/home/you/.hermes/google-chat-sa.json

# Authorization — paste the emails of people allowed to talk to the bot
GOOGLE_CHAT_ALLOWED_USERS=you@yourdomain.com,coworker@yourdomain.com

# Tùy chọn
GOOGLE_CHAT_HOME_CHANNEL=dấu cách/AAAA... # đích phân phối mặc định cho công việc định kỳ
GOOGLE_CHAT_MAX_MESSAGES=1 # Pub/Sub FlowControl; 1 tuần tự hóa các lệnh mỗi phiên
GOOGLE_CHAT_MAX_BYTES=16777216 # 16 MiB — giới hạn byte tin nhắn trên chuyến bay

ID dự án cũng quay trở lại GOOGLE_CLOUD_PROJECT và đường dẫn SA rơi xuống quay lại GOOGLE_APPLICATION_CREDENTIALS — sử dụng bất kỳ quy ước nào bạn thích.

Cài đặt các phần phụ thuộc mà bộ điều hợp Google Chat cần (hiện chưa có phần bổ sung nào của Hermes được xuất bản - cài đặt chúng trực tiếp):

pip install google-cloud-pubsub google-api-python-client google-auth google-auth-oauthlib

Bắt đầu cổng:

hermes gateway

Bạn sẽ thấy một dòng nhật ký như:

[GoogleChat] Connected; project=my-chat-bot-123, subscription=<redacted>,
             bot_user_id=users/XXXX, flow_control(msgs=1, bytes=16777216)

Gửi "hola" trong DM thử nghiệm. Bot đăng một điểm đánh dấu "Hermes đang suy nghĩ...", sau đó chỉnh sửa tin nhắn tương tự bằng phản hồi thực sự — không có "tin nhắn đã bị xóa" bia mộ.

Định dạng và khả năng​

Google Chat hiển thị một tập hợp con giảm giá có giới hạn:

SupportedNot supported
*bold*, _italic_, ~strike~, `code`Headings, lists
Inline images via URLInteractive Card v2 buttons (v1 of this gateway)
Native file attachments (after /setup-files — see Step 10)Native voice notes / circular video notes

Lời nhắc hệ thống của tổng đài viên bao gồm gợi ý dành riêng cho Google Chat để họ biết những điều này giới hạn và tránh định dạng không hiển thị.

Giới hạn kích thước tin nhắn: 4000 ký tự mỗi tin nhắn. Phản hồi của tác nhân dài hơn là tự động chia thành nhiều tin nhắn.

Hỗ trợ chủ đề: khi người dùng trả lời bên trong một chủ đề, Hermes sẽ phát hiện thread.name và đăng câu trả lời của nó trong cùng một chủ đề, vì vậy mỗi chủ đề sẽ có một phiên Hermes riêng biệt.

Bước 10: Phân phối tệp đính kèm gốc (tùy chọn)​

Ngay lập tức, bot có thể đăng văn bản, hình ảnh nội tuyến qua URL và thẻ tải xuống cho âm thanh/video/tài liệu. Để gửi tệp đính kèm trò chuyện gốc — giống nhau tiện ích tệp bạn nhận được khi con người kéo và thả tệp - mỗi người dùng ủy quyền bot một lần thông qua luồng OAuth cho mỗi người dùng.

Tại sao lại có một luồng riêng biệt​

Xác thực tài khoản dịch vụ từ chối cứng điểm cuối media.upload của Google Chat:

Phương pháp này không hỗ trợ xác thực ứng dụng bằng tài khoản dịch vụ. Xác thực bằng tài khoản người dùng.

Không có vai trò hoặc phạm vi IAM nào khắc phục được vấn đề này. Điểm cuối chỉ chấp nhận người dùng thông tin xác thực. Vì vậy, bot phải hoạt động với tư cách là người dùng bất cứ khi nào nó tải tệp lên — cụ thể là người dùng đã yêu cầu tệp.

Thiết lập máy chủ một lần​

  1. Đi tới API & Dịch vụ → Thông tin xác thực trong cùng một dự án GCP.
  2. Tạo thông tin đăng nhập → ID ứng dụng khách OAuth → Ứng dụng dành cho máy tính để bàn.
  3. Tải xuống JSON. Di chuyển nó vào máy chủ chạy Hermes.
  4. Trên máy chủ, đăng ký máy khách với Hermes:
python -m gateway.platforms.google_chat_user_oauth \
    --client-secret /path/to/client_secret.json

Nó ghi ~/.hermes/google_chat_user_client_secret.json. Điều này được chia sẻ cơ sở hạ tầng — nó xác định OAuth ứng dụng chứ không phải bất kỳ người dùng cá nhân nào. một tập tin trên mỗi máy chủ là đủ cho dù sau này có bao nhiêu người dùng ủy quyền.

Ủy quyền cho mỗi người dùng (trong trò chuyện)​

Mỗi người dùng chạy luồng một lần, trong DM của riêng họ bằng bot:

  1. Họ gửi /setup-files tới bot. Nó trả lời với trạng thái và tiếp theo bước.
  2. Họ gửi /setup-files start. Bot trả lời bằng URL OAuth.
  3. Họ mở URL, nhấp vào Cho phép và xem trình duyệt không tải được http://localhost:1/?...&code=.... Thất bại đó được mong đợi — auth mã nằm trong thanh URL.
  4. Họ sao chép URL bị lỗi (hoặc chỉ giá trị code=...) và dán lại vào trò chuyện dưới dạng /setup-files <PASTED_URL>. Bot trao đổi nó lấy một làm mới mã thông báo.

Mã thông báo sẽ đến ~/.hermes/google_chat_user_tokens/<sanitized_email>.json. Các yêu cầu tệp tiếp theo trong DM của người dùng đó sử dụng mã thông báo của họ, vì vậy bot tải lên khi họ và tin nhắn sẽ đến không gian của họ.

Để thu hồi sau: /setup-files revoke chỉ xóa mã thông báo của người dùng đó. Khác mã thông báo của người dùng không bị ảnh hưởng.

###Phạm vi

Luồng yêu cầu chính xác một phạm vi: chat.messages.create. Điều đó bao gồm cả media.upload và messages.create tham chiếu đến nội dung đã tải lên Tham chiếu dữ liệu tệp đính kèm. Không có Drive, không có phạm vi Trò chuyện rộng hơn — đây là đặc quyền tối thiểu có mục đích.

Hành vi của nhiều người dùng​

Khi người hỏi chưa có mã thông báo cho mỗi người dùng, bot sẽ quay trở lại trạng thái cũ mã thông báo một người dùng tại ~/.hermes/google_chat_user_token.json (nếu có từ cài đặt trước nhiều người dùng). Khi không có sẵn, bot sẽ đăng một thông báo rõ ràng thông báo văn bản yêu cầu người hỏi chạy /setup-files.

Người dùng thu hồi chỉ xóa vị trí của riêng họ. 401/403 từ mã thông báo của một người dùng chỉ xóa bộ nhớ cache của người dùng đó. Người dùng không làm phiền lẫn nhau.

Khắc phục sự cố​

Bot giữ im lặng sau khi gửi "hola."

  1. Kiểm tra đăng ký Pub/Sub có tin nhắn chưa được gửi trong bảng điều khiển hay không. Nếu đúng như vậy thì Hermes chưa được xác thực — hãy xác minh GOOGLE_CHAT_SERVICE_ACCOUNT_JSON và SA được liệt kê là Người đăng ký Pub/Sub trên đăng ký.
  2. Nếu đăng ký không có tin nhắn thì Google Chat sẽ không xuất bản. Kiểm tra kỹ liên kết IAM trên chủ đề: chat-api-push@system.gserviceaccount.com phải có Nhà xuất bản Pub/Sub.
  3. Kiểm tra nhật ký hermes Gateway để tìm [GoogleChat] Đã kết nối. Nếu bạn thấy [GoogleChat] Xác thực cấu hình không thành công, thông báo lỗi sẽ cho bạn biết điều gì env var để khắc phục.

Bot trả lời nhưng thông báo lỗi xuất hiện thay vì câu trả lời của tổng đài viên.

Kiểm tra nhật ký để biết [GoogleChat] Luồng Pub/Sub đã chết — nếu những điều này lặp lại, SA của bạn thông tin xác thực có thể đã được luân chuyển hoặc đăng ký đã bị xóa. Sau 10 lần thử bộ chuyển đổi tự đánh dấu là gây tử vong.

"403 Bị cấm" trên mọi tin nhắn gửi đi.

Bot đã bị xóa khỏi không gian hoặc bạn đã thu hồi nó trong bảng điều khiển Chat API. Cài đặt lại nó trong không gian (sự kiện ADDED_TO_SPACE tiếp theo sẽ kích hoạt lại nhắn tin tự động).

Quá nhiều cảnh báo "Tỷ lệ đạt giới hạn".

Hạn ngạch mặc định của Chat API cho phép 60 tin nhắn trên mỗi không gian mỗi phút. Nếu bạn tác nhân tạo ra các phản hồi phát trực tuyến dài vượt quá mức đó, bộ điều hợp sẽ thử lại với độ trễ theo cấp số nhân — nhưng bạn vẫn sẽ thấy độ trễ mà người dùng có thể nhìn thấy. Hãy xem xét phản hồi ngắn gọn hoặc tăng hạn ngạch trong bảng điều khiển GCP.

Bot liên tục đăng thông báo "/setup-files" thay vì các tập tin.

Người hỏi không có mã thông báo OAuth cho mỗi người dùng và không có dự phòng cũ. Chạy /setup-files trong DM của họ và làm theo Bước 10. Sau khi trao đổi hoàn tất yêu cầu tệp tiếp theo được tải lên nguyên bản mà không cần khởi động lại cổng.

/setup-files start cho biết "Không có thông tin xác thực ứng dụng khách nào được lưu trữ trên máy chủ."

Việc thiết lập máy chủ một lần chưa được thực hiện. Từ một thiết bị đầu cuối trên máy chủ chạy Hermes:

python -m gateway.platforms.google_chat_user_oauth \
    --client-secret /path/to/client_secret.json

Sau đó gửi lại /setup-files start.

/setup-files <PASTED_URL> cho biết "Trao đổi mã thông báo không thành công."

Mã xác thực chỉ sử dụng một lần và tồn tại trong thời gian ngắn (thường là vài phút). Gửi /setup-files start để nhận URL mới và thử lại.

Ghi chú bảo mật​

  • Phạm vi tài khoản dịch vụ: bộ điều hợp yêu cầu phạm vi chat.bot và pubsub. IAM phải là cơ quan thực thi thực tế — cấp SA của bạn ở mức tối thiểu (roles/pubsub.subscriber + roles/pubsub.viewer trên gói đăng ký), không phải Vai trò Pub/Sub cấp dự án hoặc cấp tổ chức.
  • Bảo vệ tải xuống tệp đính kèm: Hermes sẽ chỉ đính kèm người mang SA mã thông báo tới các URL có máy chủ khớp với danh sách ngắn cho phép của các miền do Google sở hữu (googleapis.com, drive.google.com, lh[3-6].googleusercontent.com và một số khác). Bất kỳ máy chủ nào khác đều bị từ chối trước yêu cầu HTTP, để bảo vệ chống lại các tình huống SSRF trong đó một sự kiện được tạo ra có thể chuyển hướng mã thông báo mang đến dịch vụ siêu dữ liệu GCE.
  • Xử lý: Email tài khoản dịch vụ, đường dẫn đăng ký và đường dẫn chủ đề bị agent/redact.py loại bỏ khỏi đầu ra nhật ký. Kết xuất phong bì gỡ lỗi (GOOGLE_CHAT_DEBUG_RAW=1) định tuyến thông qua cùng một bộ lọc biên tập và nhật ký ở cấp độ DEBUG.
  • Tuân thủ: nếu bạn định kết nối bot này với không gian làm việc được quản lý (bất cứ điều gì có chính sách lưu trữ dữ liệu hoặc quản lý AI), hãy nhận được sự chấp thuận đó trước lần cài đặt đầu tiên.
  • Phạm vi OAuth của người dùng: chỉ yêu cầu luồng tệp đính kèm cho mỗi người dùng chat.messages.create — mức tối thiểu bao gồm media.upload cộng với tiếp theo messages.create. Mã thông báo được duy trì dưới dạng JSON đơn giản tại ~/.hermes/google_chat_user_tokens/<sanitized_email>.json (hệ thống tập tin quyền là sự bảo vệ - mô hình tương tự như tệp khóa SA). Mỗi mã thông báo được sở hữu bởi chính xác một người dùng; thu hồi nằm trong phạm vi của người dùng đó.