介绍
# Zoho Integration (CRM + Projects + Meeting)
由 [Zone 99](https://99.zone) 制作 · [GitHub](https://github.com/shreefentsar/clawdbot-zoho) · [Contribute](https://github.com/shreefentsar/clawdbot-zoho/issues)
## 快速开始
使用 `zoho` CLI 包装器 —— 它会自动处理 OAuth 令牌刷新和缓存。
```bash zoho help # Show all commands zoho token # Print current access token (auto-refreshes) ```
## 认证设置
### 第 1 步：注册您的应用程序
1. 前往 [Zoho API Console](https://api-console.zoho.com/) 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 步：生成授权码（许可令牌）
构建此 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： > | Region | 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 步：交换代码以获取刷新令牌
运行此 curl 命令（替换占位符）：
```bash 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" ```
响应： ```json { "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/Projects 组织 ID：** ```bash # After setting up .env with client_id, client_secret, refresh_token: zoho raw GET /crm/v7/org | jq '.org[0].id' ```
**Meeting 组织 ID：** 登录 [Zoho Meeting](https://meeting.zoho.com) → Admin Settings → 在 URL 或设置页面中查找 Organization ID。它与 CRM 组织 ID 不同。
### 第 5 步：配置 .env
在技能目录中创建 `.env`：
```bash 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 范围参考
| Scope | 用于 | |-------|----------| | `ZohoCRM.modules.ALL` | 读/写 CRM 记录（商机、联系人、线索等） | | `ZohoCRM.settings.ALL` | 读取 CRM 字段定义和组织设置 | | `ZohoProjects.projects.ALL` | 读/写项目 | | `ZohoProjects.tasks.ALL` | 读/写任务、里程碑、Bug、工时日志 | | `ZohoMeeting.recording.READ` | 列出和访问会议录制 | | `ZohoMeeting.meeting.READ` | 列出会议和会话详情 | | `ZohoMeeting.meetinguds.READ` | 下载录制文件 | | `ZohoFiles.files.READ` | 下载文件（录制、转录） |
如果您只需要 CRM 或只需要 Meeting，可以请求更少的范围。授权 URL 范围参数以逗号分隔。
### 认证故障排除
- **"invalid_code"** → 授权代码已过期（有效期 2 分钟）。重新执行第 2 步。 - **"invalid_client"** → 客户端 ID 错误，或者您所在数据中心的 accounts-server URL 错误。 - **"invalid_redirect_uri"** → curl 中的 redirect_uri 必须与您在 API Console 中注册的完全匹配。 - **令牌刷新失败** → 刷新令牌可能被撤销。重新执行第 2–3 步以获取新的令牌。 - **"Given URL is wrong"** → 您访问的数据中心对应的 API 域名不正确。
## CRM 命令
```bash # 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":"[email protected]"}]}' 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 模块 线索、联系人、客户、商机、任务、活动、通话、备注、产品、报价单、销售订单、采购订单、发票
### 搜索运算符 equals, not_equal, starts_with, contains, not_contains, in, not_in, between, greater_than, less_than
## Projects 命令
```bash # 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 ```
### 任务字段 name, start_date (MM-DD-YYYY), end_date, priority (None/Low/Medium/High), owner, description, tasklist_id, percent_complete
## Meeting 命令
```bash # 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 meeting recordings` 的关键字段： - `erecordingId` —— 加密录制 ID（用于去重/跟踪） - `topic` —— 会议标题 - `sDate`, `sTime` —— 开始日期/时间（人类可读） - `startTimeinMs` —— 开始时间（以纪元毫秒为单位，用于日期过滤） - `durationInMins` —— 录制时长 - `downloadUrl` / `publicDownloadUrl` —— MP4 下载 URL - `transcriptionDownloadUrl` —— Zoho 生成的转录（如果可用） - `summaryDownloadUrl` —— Zoho 生成的摘要（如果可用） - `fileSize` / `fileSizeInMB` —— 录制文件大小 - `status` —— 例如 `UPLOADED` - `meetingKey` —— 会议标识符 - `creatorName` —— 启动录制的人员
### 会议录制流程
用于自动站立会议/会议摘要：
```bash # 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 调用
对于子命令未涵盖的任何操作： ```bash # 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 ```
## 使用模式
### 检查商机/销售漏斗时 ```bash zoho crm list Deals "sort_by=Created_Time&sort_order=desc&per_page=10" | jq '.data[] | {Deal_Name, Stage, Amount, Closing_Date}' ```
### 检查项目进度时 ```bash zoho proj list | jq '.projects[] | {name, status, id: .id_string}' zoho proj tasks <project_id> | jq '.tasks[] | {name, status: .status.name, percent_complete, priority}' ```
### 从对话创建任务时 ```bash zoho proj create-task <project_id> "name=Task+description&priority=High&start_date=MM-DD-YYYY&end_date=MM-DD-YYYY" ```
### 总结会议录制时 ```bash # 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 次/分钟 - Projects：因计划而异 - Meeting：标准 API 限制 - 令牌刷新：不要不必要地频繁调用（自动缓存）
## 参考资料 - [CRM API 字段](references/crm-api.md) - [Projects API 端点](references/projects-api.md) - [Meeting API 参考](references/meeting-api.md)