@chat-adapter/ gchat (英语)

npm 软件包 : @chat-adapter/gchat

谷歌聊天适配器 聊天SDK。配置了服务账户认证和可选的Pub/Sub.

联合国 聊天-sdk.dev/适应者/正式/gchat 指南: vercel.com/kb/chat-sdk (英语)

安装

pnpm add @chat-adapter/gchat

带CLI的脚手架

使用这个适配器预选的新Google Chat bot:

npx create-chat-sdk@latest my-bot --adapter gchat memory

访问 适配器目录 见其他官方和供应商官方适配器.

使用量

适配器自动检测证书来自 GOOGLE_CHAT_CREDENTIALS 或者说 GOOGLE_CHAT_USE_ADC 环境变量:

import { Chat } from "chat";
import { createGoogleChatAdapter } from "@chat-adapter/gchat";

const bot = new Chat({
  userName: "mybot",
  adapters: {
    gchat: createGoogleChatAdapter(),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.post("Hello from Google Chat!");
});

谷歌聊天设置

1. 创建全球项目

1. 转到 控制台. cloud.google.com (中文(简体) )
2. 点击工程下拉 新项目
3. 输入工程名称并单击 创建

2. 启用所需的API

转到 APIs 服务 接下来 图书馆 并能够:

• 谷歌聊天 API
• Google 工作空间事件 API (用于接收所有信件)
• 云泡/Sub API (用于接收所有信件)

3. 创建服务账户

1. 转到 IAM 行政管理 接下来 服务账户
2. 点击 创建服务账户
3. 输入名称和描述
4. 点击 创建和继续
5. 跳过可选步骤,单击 完成

4. 创建服务账户密钥

1. 点击您的服务账户
2. 转到 密钥 选项卡
3. 点击 添加密钥 接下来 创建新密钥
4. 选择 贾森 并单击 创建
5. 复制 JSON 的全部内容为 GOOGLE_CHAT_CREDENTIALS

说明: 如果你的组织 iam.disableServiceAccountKeyCreation 启用约束, 您需要放松它或者为您的工程添加一个例外 IAM 行政管理 接下来 组织政策。 。 。 .

5. 配置谷歌聊天应用程序

1. 转到 聊天 API 配置
2. 点击 配置 并填写:
   • 应用名称: 您的机器人显示名
   • 阿凡达 URL: URL 到您的机器人的外观
   • 说明: 你的机器人会做什么
   • 交互式特性启用 接收 1:1 个消息 财务报告和审定财务报表 加入空格和分组对话
   • 连接设置选择 应用 URL
   • 应用 URL数字 : https://your-domain.com/api/webhooks/gchat
   • 可见度: 选择谁可以发现您的应用程序
3. 点击 保存

6. 将机器人添加到空格中

1. 打开谷歌聊天
2. 创建或打开空格
3. 然后单击空间名称 管理应用程序集成( I)
4. 点击 添加应用程序,搜索您的应用程序,并单击 添加

所有信件的 pub/ Sub (可选)

默认情况下,Google Chat只发送@mentions的webhooks. 要接收空间中的所有信息, 请与 Pub/ Sub 一起设置工作空间活动 .

createGoogleChatAdapter({
  pubsubTopic: process.env.GOOGLE_CHAT_PUBSUB_TOPIC,
  impersonateUser: process.env.GOOGLE_CHAT_IMPERSONATE_USER,
});

GOOGLE_CHAT_PUBSUB_TOPIC 财务报告和审定财务报表 GOOGLE_CHAT_IMPERSONATE_USER 也可以自动从 env vars 中发现,所以如果 env vars 被设定的话, 您可以在配置中省略它们 .

1. 创建 Pub/Sub专题

1. 转到 Pub/Sub 软件 接下来 专题
2. 点击 创建主题
3. 输入主题 ID( 例如 ), chat-events(中文(简体) )
4. 取消检查 添加默认订阅
5. 点击 创建
6. 复制全部主题名称为 GOOGLE_CHAT_PUBSUB_TOPIC (格式 : projects/your-project-id/topics/chat-events(中文(简体) )

2. Grant Chat服务账户访问

1. 转到您的 Pub/ Sub 话题
2. 点击 权限 选项卡
3. 点击 添加特等
4. 输入 [email protected]
5. 选择角色 Pub/ Sub 出版社
6. 点击 保存

3. 创建按下订阅

1. 转到 Pub/Sub 软件 接下来 订阅
2. 点击 创建订阅
3. 选择您的话题
4. 设定 交付类型 以推为单位
5. 设定 端点 URL 改为 https://your-domain.com/api/webhooks/gchat
6. 检查 启用认证 并选择一个服务账户。 每次推时都会标出OIDC的代号,其电子邮件是您设定的值 GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL
7. 点击 创建

4. 允许全域授权

创建工作空间活动订阅和启动模式草案需要全域授权.

步骤1——允许在服务账户上授权:

1. 转到 IAM 行政管理 接下来 服务账户
2. 点击您的服务账户
3. 检查 启用 Google 工作空间全域代表团 保存
4. 复制 客户身份 (数字标识,不是电子邮件)

步骤2 — 在 Google 管理控制台中授权 :

1. 转到 谷歌管理控制台
2. 转到 警卫 接下来 存取和数据控制 接下来 API 控件
3. 点击 管理域宽代表团 接下来 添加新内容
4. 输入数字 客户身份 从步骤1
5. 添加 OAuth 范围( 共分隔, 在一行):

   https://www.googleapis.com/auth/chat.spaces.readonly,https://www.googleapis.com/auth/chat.messages.readonly,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.spaces.create
   

6. 点击 授权

步骤3——设置环境变量:

设定 GOOGLE_CHAT_IMPERSONATE_USER 到您域中的管理用户电子邮件(例如, [email protected]) (中文(简体) ).

配置

大多数选项在未提供时会从环境变量中自动检测出. endpointUrl 必须在配置中通过.

*以太过 credentials, (中文(简体) ), GOOGLE_CHAT_CREDENTIALS 埃文・瓦尔, useApplicationDefaultCredentials,或 GOOGLE_CHAT_USE_ADC=true 需要时间.

使用峡谷 sender.name 从由您的 Chat app 创建的已校验信件中 botUserId。适配器不会从入境引用中得知其身份。 没有这个价值,它保守地对待每一个 BOT 发送器作为防止回复循环的自定义 .

依赖引用处理器的应用程序升级 botUserId 以保留提及处理。 没有它,bot 引用注释没有变化,默认 onNewMention 检测可能不再符合它们.

• 其中一个 googleChatProjectNumber, (中文(简体) ), endpointUrl, (中文(简体) ), pubsubAudience,或 disableSignatureVerification: true 需要 —— 构造器另投。 配置您实际收到的每次运输的验证器; 以 HTTP 401 拒绝其验证器未配置的形状的请求 .

§ 需要与 pubsubAudience。观众是您的公共推力端点,所以任何人都可以让Google 薄荷一个有效签名的代币从自己的项目中取名. 只有 email 索赔中指明了打电话者,这就是为什么 谷歌需要检查 计外 aud. 没有它,Pub/Sub推就被HTTP 401所拒绝,而不是仅仅信任他们的观众.

只有工作空间和聊天软件需要这个 他们的网络呼号是附加服务身份而不是 [email protected],每个附加项目共享相同 service-{projectNumber}@gcp-sa-gsuiteaddons 电子邮件形状——所以这个身份只是精确的比较意义. 没有它,添加的指使被HTTP 401拒绝,而不是被形状所信任. 独立聊天应用程序不受影响.

环境变量

GOOGLE_CHAT_CREDENTIALS={"type":"service_account",...}
GOOGLE_CHAT_BOT_USER_ID=users/123456789

# Optional: for receiving all messages
GOOGLE_CHAT_PUBSUB_TOPIC=projects/your-project/topics/chat-events
[email protected]

# Webhook verification — at least one verifier or the explicit opt-out is required
GOOGLE_CHAT_PROJECT_NUMBER=123456789          # Direct webhooks with project-number audience
GOOGLE_CHAT_PUBSUB_AUDIENCE=https://your-domain.com/api/webhooks/gchat  # For Pub/Sub JWT verification
GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL=pubsub@your-project.iam.gserviceaccount.com  # Push subscription identity
# Workspace Add-on Chat apps only — your own add-on service identity
GOOGLE_CHAT_WORKSPACE_ADDON_SERVICE_ACCOUNT_EMAIL=service-123456789@gcp-sa-gsuiteaddons.iam.gserviceaccount.com
# GOOGLE_CHAT_DISABLE_SIGNATURE_VERIFICATION=true  # Escape hatch for local dev only

# Optional: override the Google Chat API base URL
GOOGLE_CHAT_API_URL=...

Webhook 校验

适配器支持JWT验证两种webhook类型. 当配置时,适配器验证 Authorization: Bearer <JWT> 使用 Google 的公共密钥处理收到请求时的头条 。 用 HTTP 401 拒绝丢失或无效令牌的请求.

需要核查。 构造器抛出 ValidationError 除非以下一种设定:

• googleChatProjectNumber (或 GOOGLE_CHAT_PROJECT_NUMBER)——当Chat app的认证受众为"Project number"时,可直接使用webhooks
• endpointUrl ——当Chat app的认证对象为"HTTP endpoint URL"时,直接使用webhooks;在HTTP endpoint app中点击路由卡按钮也需要使用. 工作空间加载聊天应用程序 workspaceAddOnServiceAccountEmail,因为他们的代号由附加身份签名,而不是 [email protected]
• pubsubAudience (或 GOOGLE_CHAT_PUBSUB_AUDIENCE——普活分会/分会推送. 也设定 pubsubServiceAccountEmail (或 GOOGLE_CHAT_PUBSUB_SERVICE_ACCOUNT_EMAIL) 订阅的 push auth 设置中的身份, 或按下被拒绝
• disableSignatureVerification: true (或 GOOGLE_CHAT_DISABLE_SIGNATURE_VERIFICATION=true——明确选择退出,仅供当地发展使用

两种运输方式共用了1个HTTP端点,因此每个核查器只覆盖自己的请求形状. 如果您只配置了直网验证器,则以 HTTP 401 拒绝了输入的 Pub/ Sub- 形状的请求,反之亦然 —— 如果两者同时收到,则同时配置.

直接网络呼号( Google Chat API)

Google Chat与每个webhook请求一起发送一个签名的代号. 预期的JWT受众(aud chat app's的软件 认证受众 设置 :

createGoogleChatAdapter({
  googleChatProjectNumber: "123456789",
});

使用 googleChatProjectNumber 当设置是 项目编号在 GCP 控制台仪表板 (与项目ID不同).

createGoogleChatAdapter({
  endpointUrl: "https://your-domain.com/api/webhooks/gchat",
});

使用 endpointUrl 当设置是 HTTP 端点 URL. Workspace Add-on Chat apps 总是使用 URL 观众符号. 当两者 googleChatProjectNumber 财务报告和审定财务报表 endpointUrl 设置,接受任意一种符号类型.

两种模式带有不同的符号类型,适配器验证每个符号 Google的参考执行: 端点- URL 令牌是标准的 Google OIDC ID令牌(与 Google 的公共证书核对,加上 Chat 服务账户) email 索赔额 email_verified),而项目编号符号是由 JWTs 自行签名的 [email protected] (与该服务账户的X.509证书核对) [email protected]) (中文(简体) ). 配置 endpointUrl 必须完全匹配在 Chat API 控制台中注册的 URL —— 跟踪- slash 或方案错配失败 .

Pub/ Sub 推动消息

Google Cloud Pub/Sub发送了带有推送功能的签名OIDC JWT. JWT的观众是你在推订阅上配置的.

createGoogleChatAdapter({
  pubsubAudience: "https://your-domain.com/api/webhooks/gchat",
});

要对您的 Pub/ Sub 订阅进行认证推出 :

1. 转到 Pub/Sub 软件 接下来 订阅
2. 编辑您的按下订阅
3. 启用 认证
4. 选择一个带有 服务账户托肯创建器 角色
5. 设定 观众 切入到您的 Webhook URL
6. 使用与 GOOGLE_CHAT_PUBSUB_AUDIENCE

特征

通讯

丰富内容

对话

信件历史

限制

• 打字指标:不受Google Chat API的支持. startTyping() 是个禁忌.
• 添加反应:Google Chat API不支持服务账户(app)认证添加反应. 用于 addReaction() 或者说 removeReaction(),您需要使用 impersonateUser 已配置——但反应似乎来自冒充的用户,而不是机器人.

信件历史( E)fetchMessages(中文(简体) )

获取信件历史需要使用 impersonateUser 配置选项设置 。 冒名顶替的用户必须能够访问您想要读取的空格. 见 Pub/ Sub 设置 用于配置代表团和OAuth范围.

解决问题

401 在网络呼号上未经授权

• 用于直接网点: 校验 GOOGLE_CHAT_PROJECT_NUMBER 匹配您的 GCP 项目编号( 不是项目 ID)
• 对于Pub/Sub: 验证 GOOGLE_CHAT_PUBSUB_AUDIENCE 匹配您按下订阅时配置的观众
• 检查您的 Pub/ Sub 按下订阅是否启用认证
• 确保用于驱动认证的服务账户有: 服务账户托肯创建器 角色

未收到网签

• 在 Google 聊天配置中验证 App URL 正确
• 检查是否启用了 Chat API
• 确保服务账户拥有必要的权限

Pub/Sub不工作

• 校验 [email protected] 有 Pub/ Sub 出版者的作用
• 检查按下订阅 URL 是否正确
• 校验全域权限配置为正确的范围
• 检查 GOOGLE_CHAT_IMPERSONATE_USER 是有效的管理电子邮件

工作空间事件的“拒绝”

• 确保配置全域授权
• 校验 OAuth 范围完全相同
• 请检查date=中的日期值 (帮助)

DMs 的“ 许可不足 ”

• 模式草案要求全域授权 chat.spaces 财务报告和审定财务报表 chat.spaces.create 范围
• 范围变化需要24小时才能传播

未收到按钮

• 校验 交互式特性 在 Google 聊天应用程序配置中启用
• 检查 App URL 设置正确且可访问
• 按钮点击到与信件相同的网页hook URL

AI 编码代理

如果您使用OpenAI Codex, Claude Code, 或 Cursor 等AI编码代理, 在写入代码前安装 Chat SDK 技能, 使其了解 SDK API, 适配器模式, 以及项目常规 .

npx skills add vercel/chat

技术参考文献 node_modules/chat/docs,加上已发布的软件包中的适配器指南和启动模板.

您也可以安装 Vercel 插件 包括Chat SDK技术与专家代理、代理斜线指令

npx plugins add vercel/vercel-plugin

插件是可选的;单是技能就足以用Chat SDK来构建.

关于可代理阅读的文件,见 聊天- sdk.dev/llms.txt (页数索引)或 聊天- sdk.dev/llms- full.txt (全文).

许可证

麻省理工学院