Zoho 集成（CRM + Projects + Meeting）

由 Zone 99 开发 · GitHub · 贡献代码

快速开始

使用 zoho CLI 封装工具 — 它会自动处理 OAuth Token 刷新与缓存。

zoho help          # 显示所有命令
zoho token         # 打印当前访问令牌（自动刷新）

认证配置

步骤 1：注册您的应用

1. 访问 Zoho API 控制台
2. 点击 Add Client → 选择 Server-based Applications
3. 填写以下信息：
   • Client Name：您的应用名称（例如 “Clawdbot Zoho Integration”）
   • Homepage URL：您的域名或 https://localhost
   • Redirect URI： https://localhost/callback（或您可控的任意 URL — 您仅需该地址一次，用于获取授权码）
4. 点击 Create
5. 记录下 Client ID 和 Client Secret

步骤 2：生成授权码（Grant Token）

构造以下 URL 并在浏览器中打开（请替换占位符）：

https://accounts.zoho.com/oauth/v2/auth
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &scope=ZohoCRM.modules.ALL,ZohoCRM.settings.ALL,ZohoProjects.projects.ALL,ZohoProjects.tasks.ALL,ZohoMeeting.recording.READ,ZohoMeeting.meeting.READ,ZohoMeeting.meetinguds.READ,ZohoFiles.files.READ
  &redirect_uri=https://localhost/callback
  &access_type=offline
  &prompt=consent

重要提示：请根据您的数据中心区域，使用对应的 accounts URL：

区域	Accounts URL
US	https://accounts.zoho.com
EU	https://accounts.zoho.eu
IN	https://accounts.zoho.in
AU	https://accounts.zoho.com.au
JP	https://accounts.zoho.jp
UK	https://accounts.zoho.uk
CA	https://accounts.zohocloud.ca
SA	https://accounts.zoho.sa

授权完成后，您将被重定向至类似如下地址：

https://localhost/callback?code=1000.abc123...&location=us&accounts-server=https://accounts.zoho.com

复制 code 参数的值。该授权码有效期为 2 分钟 — 请立即进入步骤 3。

步骤 3：使用授权码换取 Refresh Token

运行以下 curl 命令（请替换占位符）：

curl -X POST "https://accounts.zoho.com/oauth/v2/token" 
  -d "client_id=YOUR_CLIENT_ID" 
  -d "client_secret=YOUR_CLIENT_SECRET" 
  -d "grant_type=authorization_code" 
  -d "redirect_uri=https://localhost/callback" 
  -d "code=PASTE_CODE_FROM_STEP_2"

响应示例：

{
  "access_token": "1000.xxxx.yyyy",
  "refresh_token": "1000.xxxx.zzzz",
  "api_domain": "https://www.zohoapis.com",
  "token_type": "Bearer",
  "expires_in": 3600
}

请妥善保存 refresh_token — 这是您的长期有效凭证。access_token 有效期为 1 小时，但 CLI 会通过 refresh_token 自动刷新它。

步骤 4：查找您的 Org ID

CRM/Projects Org ID：

# 在 .env 中配置 client_id、client_secret、refresh_token 后执行：
zoho raw GET /crm/v7/org | jq '.org[0].id'

Meeting Org ID：
登录 Zoho Meeting → Admin Settings → 在 URL 或设置页面中查找 Organization ID。该 ID 与 CRM 的 org ID 不同。

步骤 5：配置 .env

在 skill 目录下创建 .env 文件：

ZOHO_CLIENT_ID=1000.XXXXXXXXXXXXXXXXXXXXXXXXX
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REFRESH_TOKEN=1000.your_refresh_token_here
ZOHO_ORG_ID=123456789              # CRM/Projects org ID
ZOHO_MEETING_ORG_ID=987654321      # Meeting org ID（不同于 CRM）
ZOHO_CRM_DOMAIN=https://www.zohoapis.com
ZOHO_PROJECTS_DOMAIN=https://projectsapi.zoho.com/restapi
ZOHO_MEETING_DOMAIN=https://meeting.zoho.com
ZOHO_ACCOUNTS_URL=https://accounts.zoho.com

若您使用非 US 数据中心（例如 .eu、.in、.com.au），请相应调整各 domain URL。

OAuth 权限范围（Scopes）参考

若仅需 CRM 功能或仅需 Meeting 功能，可申请更少的 scopes。授权 URL 中的 scope 参数以英文逗号分隔。

认证问题排查

• "invalid_code" → 授权码已过期（有效期 2 分钟）。请重新执行步骤 2。
• "invalid_client" → Client ID 错误，或 accounts-server URL 与您的数据中心不匹配。
• "invalid_redirect_uri" → curl 请求中的 redirect_uri 必须与 API Console 中注册的完全一致。
• Token 刷新失败 → Refresh Token 可能已被撤销。请重新执行步骤 2–3 获取新的 Token。
• "Given URL is wrong" → 您正在调用错误的数据中心对应 API domain。

CRM 命令

# 列出任意模块的记录
zoho crm list Deals
zoho crm list Deals "page=1&per_page=5&sort_by=Created_Time&sort_order=desc"
zoho crm list Contacts
zoho crm list Leads

# 获取指定记录
zoho crm get Deals 1234567890

# 按条件搜索
zoho crm search Deals "(Stage:equals:Closed Won)"
zoho crm search Contacts "(Email:contains:@acme.com)"
zoho crm search Leads "(Lead_Source:equals:Web)"

# 创建记录
zoho crm create Contacts '{"data":[{"Last_Name":"Smith","First_Name":"John","Email":"j@co.com"}]}'
zoho crm create Deals '{"data":[{"Deal_Name":"New Project","Stage":"Qualification","Amount":50000}]}'

# 更新记录
zoho crm update Deals 1234567890 '{"data":[{"Stage":"Closed Won"}]}'

# 删除记录
zoho crm delete Deals 1234567890

CRM 模块

Leads、Contacts、Accounts、Deals、Tasks、Events、Calls、Notes、Products、Quotes、Sales_Orders、Purchase_Orders、Invoices

搜索操作符

equals、not_equal、starts_with、contains、not_contains、in、not_in、between、greater_than、less_than

Projects 命令

# 列出全部项目
zoho proj list

# 获取项目详情
zoho proj get 12345678

# 任务相关
zoho proj tasks 12345678
zoho proj create-task 12345678 "name=Fix+login+bug&priority=High&start_date=01-27-2026"
zoho proj update-task 12345678 98765432 "percent_complete=50"

# 其他
zoho proj milestones 12345678
zoho proj tasklists 12345678
zoho proj bugs 12345678
zoho proj timelogs 12345678

Task 字段说明

name、start_date（MM-DD-YYYY 格式）、end_date、priority（None/Low/Medium/High）、owner、description、tasklist_id、percent_complete

Meeting 命令

# 列出全部录制文件
zoho meeting recordings
zoho meeting recordings | jq '[.recordings[] | {topic, sDate, sTime, durationInMins, erecordingId}]'

# 下载录制文件（使用 recordings 列表返回的 downloadUrl）
zoho meeting download "https://files-accl.zohopublic.com/public?event-id=..." output.mp4

# 列出会议/会话
zoho meeting list
zoho meeting list "fromDate=2026-01-01T00:00:00Z&toDate=2026-01-31T23:59:59Z"

# 获取会议详情
zoho meeting get 1066944216

录制响应字段说明

zoho meeting recordings 返回的关键字段：

• erecordingId — 加密后的录制 ID（可用于去重/追踪）
• topic — 会议标题
• sDate、sTime — 开始日期/时间（人类可读格式）
• startTimeinMs — 开始时间（毫秒级时间戳，可用于日期过滤）
• durationInMins — 录制时长（分钟）
• downloadUrl / publicDownloadUrl — MP4 下载地址
• transcriptionDownloadUrl — Zoho 生成的转录文本（如可用）
• summaryDownloadUrl — Zoho 生成的摘要（如可用）
• fileSize / fileSizeInMB — 录制文件大小
• status — 例如 UPLOADED
• meetingKey — 会议标识符
• creatorName — 启动录制的用户

会议录制处理流水线（Recording Pipeline）

适用于自动化站会/会议摘要场景：

# 1. 列出录制文件，并按今日时间范围（毫秒时间戳）过滤
zoho meeting recordings | jq --argjson start "$START_MS" --argjson end "$END_MS" 
  '[.recordings[] | select(.startTimeinMs >= $start and .startTimeinMs <= $end)]'

# 2. 下载录制文件
zoho meeting download "$DOWNLOAD_URL" /tmp/recording.mp4

# 3. 提取音频
ffmpeg -i /tmp/recording.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/audio.wav -y

# 4. 使用 Gemini Flash API 进行语音转文字（对阿拉伯语+英语混合场景效果优异）
# 完整实现见 scripts/standup-summarizer.sh

# 5. 使用 Claude/GPT 对转录文本进行摘要
# 6. 清理临时文件

完整的站会摘要脚本位于 scripts/standup-summarizer.sh。

原始 API 调用（Raw API Calls）

适用于未被子命令覆盖的场景：

# CRM 接口
zoho raw GET /crm/v7/settings/fields?module=Deals
zoho raw GET /crm/v7/org

# Meeting 接口
zoho raw GET "https://meeting.zoho.com/meeting/api/v2/{zsoid}/recordings.json"

# 自定义模块
zoho raw GET /crm/v7/Custom_Module

常用使用模式

检查成交/销售漏斗（Deals/Pipeline）时

zoho crm list Deals "sort_by=Created_Time&sort_order=desc&per_page=10" | jq '.data[] | {Deal_Name, Stage, Amount, Closing_Date}'

检查项目进度时

zoho proj list | jq '.projects[] | {name, status, id: .id_string}'
zoho proj tasks  | jq '.tasks[] | {name, status: .status.name, percent_complete, priority}'

从对话中创建任务时

zoho proj create-task  "name=Task+description&priority=High&start_date=MM-DD-YYYY&end_date=MM-DD-YYYY"

对会议录制进行摘要时

# 快速列出最近的录制文件
zoho meeting recordings | jq '[.recordings[:5] | .[] | {topic, sDate, sTime, durationInMins, fileSize}]'

# 下载最新录制文件
URL=$(zoho meeting recordings | jq -r '.recordings[0].downloadUrl')
zoho meeting download "$URL" /tmp/latest.mp4

速率限制（Rate Limits）

• CRM：100 次请求/分钟
• Projects：依所选套餐而定
• Meeting：遵循标准 API 限制
• Token 刷新：避免不必要的调用（CLI 已自动缓存）

参考资料

• CRM API 字段文档
• Projects API 接口列表
• Meeting API 参考文档