# 飞书多维表格自动AI对话 API接口文档 本文档描述了飞书多维表格自动AI对话功能的REST API接口。 ## 基本信息 - 基础URL: `/api/feishu/` - 认证方式: JWT Token (需要在请求头中添加 `Authorization: Bearer `) - 请求方式: POST/GET - 返回格式: JSON ## 注意事项 1. 请确保使用正确的URL路径：完整路径为 `/api/feishu/process-table/` 而非 `/api/v1/feishu/process-table/` 2. 飞书授权令牌有效期较短，为了避免授权问题，请在请求中提供正确的 `app_id` 和 `app_secret` 参数: ```json { "table_id": "your_table_id", "view_id": "your_view_id", "app_id": "cli_a5c97daacb9e500d", "app_secret": "fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y" } ``` 3. 查看运行日志中的错误信息，根据错误代码进行故障排除 ## 接口列表 ### 1. 处理飞书表格数据 从飞书多维表格读取数据，处理重复邮箱，可选择性地进行自动对话。 - **URL**: `/api/feishu/process-table/` - **方法**: `POST` - **权限**: 仅限组长角色 - **请求参数**: | 参数名 | 类型 | 必需 | 描述 | |--------|------|------|------| | table_id | string | 是 | 表格ID | | view_id | string | 是 | 视图ID | | app_token | string | 否 | 飞书应用TOKEN | | access_token | string | 否 | 用户访问令牌 | | goal_template | string | 否 | 目标内容模板 | | auto_chat | boolean | 否 | 是否自动执行AI对话 | | turns | integer | 否 | 自动对话轮次 | - **请求示例**: ```json { "table_id": "tbl3oikG3F8YYtVA", "view_id": "vewSOIsmxc", "app_id": "cli_a5c97daacb9e500d", "app_secret": "fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y", "goal_template": "与达人{handle}(邮箱:{email})建立联系，最终目标是达成合作。", "auto_chat": true, "turns": 5 } ``` - **成功响应**: ```json { "status": "success", "records_count": 100, "duplicate_emails_count": 5, "processing_results": { "total": 5, "success": 4, "failure": 1, "details": [ { "email": "example1@gmail.com", "handle": "example1", "status": "success" }, // ...其他处理结果 ] }, "chat_results": [ { "email": "example1@gmail.com", "result": { "status": "success", "turns_completed": 5, "goal_achieved": true, "summary_status": "success", "conversation_id": "feishu_ai_12345" } } // ...其他自动对话结果 ] } ``` ### 2. 执行自动对话 为指定邮箱的达人执行自动对话，支持真实邮件发送和接收。 - **URL**: `/api/feishu/auto-chat/` - **方法**: `POST` - **权限**: 仅限组长角色 - **请求参数**: | 参数名 | 类型 | 必需 | 描述 | |--------|------|------|------| | email | string | 是 | 达人邮箱 | | force_send | boolean | 否 | 是否强制发送新邮件(即使没有新回复) | | subject | string | 否 | 邮件主题(仅当force_send=true时使用) | | content | string | 否 | 邮件内容(仅当force_send=true时使用) | - **请求示例 (自动回复)**: ```json { "email": "example@gmail.com" } ``` - **请求示例 (强制发送)**: ```json { "email": "example@gmail.com", "force_send": true, "subject": "关于合作细节的讨论", "content": "您好，\n\n针对您提出的问题，我们可以提供以下方案...\n\n期待您的回复。\n\n祝好，\n运营团队" } ``` - **成功响应**: ```json { "status": "success", "email_sent": true, "turns_completed": 1, "goal_achieved": false, "summary_status": "not_needed", "conversation_id": "feishu_ai_12345" } ``` - **待回复响应** (没有检测到新的达人回复): ```json { "status": "success", "message": "没有新的达人回复，不需要回复", "turns_completed": 0, "goal_achieved": false, "email_sent": false, "conversation_id": "feishu_ai_12345" } ``` ### 3. 设置用户总目标 设置针对特定达人的对话总目标。 - **URL**: `/api/feishu/user-goal/` - **方法**: `POST` - **权限**: 仅限组长角色 - **请求参数**: | 参数名 | 类型 | 必需 | 描述 | |--------|------|------|------| | email | string | 是 | 达人邮箱 | | goal | string | 是 | 目标内容 | - **请求示例**: ```json { "email": "example@gmail.com", "goal": "与达人建立联系并了解其账号情况，评估合作潜力，处理合作需求，最终目标是达成合作并签约。" } ``` - **成功响应**: ```json { "status": "success", "action": "create", "goal": { "id": "12345", "content": "与达人建立联系并了解其账号情况，评估合作潜力，处理合作需求，最终目标是达成合作并签约。", "created_at": "2024-01-01 12:00:00", "updated_at": "2024-01-01 12:00:00" } } ``` ### 4. 获取用户总目标 获取当前用户的总目标设置。 - **URL**: `/api/feishu/user-goal/` - **方法**: `GET` - **权限**: 仅限组长角色 - **请求参数**: 无 - **成功响应**: ```json { "status": "success", "action": "retrieve", "goal": { "id": "12345", "content": "与达人建立联系并了解其账号情况，评估合作潜力，处理合作需求，最终目标是达成合作并签约。", "created_at": "2024-01-01 12:00:00", "updated_at": "2024-01-01 12:00:00" } } ``` ### 5. 检查目标完成状态 检查与特定达人的对话是否已达成目标。 - **URL**: `/api/feishu/check-goal/` - **方法**: `GET` - **权限**: 仅限组长角色 - **请求参数**: | 参数名 | 类型 | 必需 | 描述 | |--------|------|------|------| | email | string | 是 | 达人邮箱 | - **请求示例**: ``` GET /api/feishu/check-goal/?email=example@gmail.com ``` - **成功响应**: ```json { "status": "success", "email": "example@gmail.com", "goal_achieved": true, "last_message_time": "2024-01-01 12:00:00", "last_message": "好的，我们已经确认了合作细节。期待与您的成功合作！[目标已达成]", "summary": "本次对话主要讨论了合作条款和细节。达成了产品发布时间、价格区间、佣金比例等共识。双方已同意合作，下一步将签署正式合同。" } ``` ## 错误响应 所有接口在出错时会返回统一格式的错误信息： ```json { "error": "错误描述信息" } ``` 常见HTTP状态码： - 400: 请求参数错误 - 403: 权限不足 - 404: 资源不存在 - 500: 服务器内部错误 ## 使用示例 ### 使用curl命令 ```bash # 获取授权令牌 TOKEN=$(curl -s -X POST http://yourserver.com/api/auth/login/ -d '{"username":"admin","password":"yourpassword"}' -H "Content-Type: application/json" | jq -r '.token') # 处理飞书表格数据 curl -X POST http://yourserver.com/api/feishu/process-table/ \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{ "table_id":"tbl3oikG3F8YYtVA", "view_id":"vewSOIsmxc", "app_id":"cli_a5c97daacb9e500d", "app_secret":"fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y", "auto_chat":true }' # 检查目标完成状态 curl -X GET "http://yourserver.com/api/feishu/check-goal/?email=example@gmail.com" \ -H "Authorization: Bearer $TOKEN" ``` ### 使用JavaScript ```javascript // 获取授权令牌 async function getToken() { const response = await fetch('http://yourserver.com/api/auth/login/', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ username: 'admin', password: 'yourpassword' }), }); const data = await response.json(); return data.token; } // 处理飞书表格数据 async function processFeishuTable() { const token = await getToken(); const response = await fetch('http://yourserver.com/api/feishu/process-table/', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ table_id: 'tbl3oikG3F8YYtVA', view_id: 'vewSOIsmxc', app_id: 'cli_a5c97daacb9e500d', app_secret: 'fdVeOCLXmuIHZVmSV0VbJh9wd0Kq1o5y', auto_chat: true }), }); const data = await response.json(); console.log(data); } processFeishuTable(); ```