335 lines
8.1 KiB
Markdown
335 lines
8.1 KiB
Markdown
# 飞书多维表格自动AI对话 API接口文档
|
||
|
||
本文档描述了飞书多维表格自动AI对话功能的REST API接口。
|
||
|
||
## 基本信息
|
||
|
||
- 基础URL: `/api/feishu/`
|
||
- 认证方式: JWT Token (需要在请求头中添加 `Authorization: Bearer <token>`)
|
||
- 请求方式: 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();
|
||
``` |