Zoho集成（CRM + 项目 + 会议）

制作方Zone 99·GitHub·贡献

快速开始

使用zohoCLI包装器 — 它会自动处理OAuth令牌刷新和缓存。

zoho help          # Show all commands
zoho token         # Print current access token (auto-refreshes)

认证设置

步骤1：注册您的应用程序

1. 前往Zoho API控制台
2. 点击添加客户端→ 选择基于服务器的应用程序
3. 填写：
   • 客户端名称: 您的应用程序名称（例如"Clawdbot Zoho集成"）
   • 主页URL: 您的域名或https://localhost
   • 重定向URI:https://localhost/callback（或任何您控制的URL——您只需要它一次来获取代码）
4. 点击创建
5. 记下客户端ID和客户端密钥

步骤2：生成授权码（授权令牌）

构建此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

重要：使用与您数据中心匹配的账户URL：

地区	账户URL
美国	https://accounts.zoho.com
欧盟	https://accounts.zoho.eu
印度	https://accounts.zoho.in
澳大利亚	https://accounts.zoho.com.au
JP	https://accounts.zoho.jp
英国	https://accounts.zoho.uk
加拿大	https://accounts.zohocloud.ca
沙特阿拉伯	https://accounts.zoho.sa

授予访问权限后，您将被重定向到类似以下页面：

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

复制code参数值。此代码将在2分钟后过期— 请立即进入步骤3。

步骤3：用授权码交换刷新令牌

运行此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— 这是您的长期凭证。访问令牌将在1小时后过期，但CLI会自动使用刷新令牌来更新它。

步骤4：查找您的组织ID

CRM/项目组织ID：

# After setting up .env with client_id, client_secret, refresh_token:
zoho raw GET /crm/v7/org | jq '.org[0].id'

会议组织ID：登录Zoho Meeting→ 管理员设置 → 在URL或设置页面中查找组织ID。它与CRM的组织ID不同。

步骤5：配置.env

在技能目录中创建.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 (different from 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

如果您位于非美国数据中心（例如.eu、.in、.com.au），请调整域名URL。

OAuth 权限范围参考

如果您仅需要CRM功能或仅需要会议功能，可以请求更少的权限范围。授权URL中的scope参数以逗号分隔。

授权问题排查

• "invalid_code"→ 授权码已过期（有效期为2分钟）。请重新执行第2步。
• "invalid_client"→ 客户端ID错误，或针对您数据中心的账户服务器URL错误。
• "invalid_redirect_uri"→ curl命令中的redirect_uri必须与您在API控制台中注册的地址完全匹配。
• 令牌刷新失败→ 刷新令牌可能已被撤销。请重新执行第2-3步以获取新令牌。
• "提供的URL错误"→ 您正在访问错误的数据中心API域名。

CRM命令

# List records from any module
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

# Get a specific record
zoho crm get Deals 1234567890

# Search with criteria
zoho crm search Deals "(Stage:equals:Closed Won)"
zoho crm search Contacts "(Email:contains:@acme.com)"
zoho crm search Leads "(Lead_Source:equals:Web)"

# Create a record
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}]}'

# Update a record
zoho crm update Deals 1234567890 '{"data":[{"Stage":"Closed Won"}]}'

# Delete a record
zoho crm delete Deals 1234567890

CRM模块

潜在客户、联系人、客户、交易、任务、事件、通话、笔记、产品、报价、销售订单、采购订单、发票

搜索运算符

等于、不等于、以...开头、包含、不包含、在...中、不在...中、在...之间、大于、小于

项目命令

# List all projects
zoho proj list

# Get project details
zoho proj get 12345678

# Tasks
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"

# Other
zoho proj milestones 12345678
zoho proj tasklists 12345678
zoho proj bugs 12345678
zoho proj timelogs 12345678

任务字段

名称、开始日期（月-日-年）、结束日期、优先级（无/低/中/高）、负责人、描述、任务列表ID、完成百分比

会议命令

# List all recordings
zoho meeting recordings
zoho meeting recordings | jq '[.recordings[] | {topic, sDate, sTime, durationInMins, erecordingId}]'

# Download a recording (use downloadUrl from recordings list)
zoho meeting download "https://files-accl.zohopublic.com/public?event-id=..." output.mp4

# List meetings/sessions
zoho meeting list
zoho meeting list "fromDate=2026-01-01T00:00:00Z&toDate=2026-01-31T23:59:59Z"

# Get meeting details
zoho meeting get 1066944216

录制响应字段

关键字段来自Zoho会议录制：

• erecordingId— 加密录制ID（用于去重/追踪）
• 主题— 会议标题
• sDate，sTime— 开始日期/时间（人类可读格式）
• startTimeinMs— 开始时间，以纪元毫秒数表示（用于日期筛选）
• durationInMins— 录制时长
• downloadUrl/publicDownloadUrl— MP4 下载链接
• transcriptionDownloadUrl— Zoho 生成的转录文本（如果可用）
• summaryDownloadUrl— Zoho 生成的摘要（如果可用）
• fileSize/fileSizeInMB— 录制文件大小
• status— 例如已上传
• 会议密钥— 会议标识符
• 创建者姓名— 谁开始了录制

会议录制流水线

用于自动站立会议/会议摘要：

# 1. List recordings, filter by today's date (epoch ms)
zoho meeting recordings | jq --argjson start "$START_MS" --argjson end "$END_MS" \
  '[.recordings[] | select(.startTimeinMs >= $start and .startTimeinMs <= $end)]'

# 2. Download recording
zoho meeting download "$DOWNLOAD_URL" /tmp/recording.mp4

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

# 4. Transcribe via Gemini Flash API (great for Arabic + English mix)
# See scripts/standup-summarizer.sh for full implementation

# 5. Summarize transcript with Claude/GPT
# 6. Clean up temp files

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

原始 API 调用

对于子命令未涵盖的任何内容：

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

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

# Custom modules
zoho raw GET /crm/v7/Custom_Module

使用模式

检查交易/销售管道时

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 <project_id> | jq '.tasks[] | {name, status: .status.name, percent_complete, priority}'

从对话创建任务时

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

总结会议录制时

# Quick list of recent recordings
zoho meeting recordings | jq '[.recordings[:5] | .[] | {topic, sDate, sTime, durationInMins, fileSize}]'

# Download latest recording
URL=$(zoho meeting recordings | jq -r '.recordings[0].downloadUrl')
zoho meeting download "$URL" /tmp/latest.mp4

速率限制

• CRM：每分钟 100 个请求
• 项目：因计划而异
• 会议：标准 API 限制
• 令牌刷新：无需时不调用（自动缓存）

参考资料

• CRM API 字段
• 项目API端点
• 会议API参考