468 lines
11 KiB
Markdown
468 lines
11 KiB
Markdown
# Gmail模块API接口文档 - Apifox测试版
|
||
|
||
## 1. 认证管理
|
||
|
||
### 1.1 启动OAuth授权
|
||
|
||
- **接口URL**: `/api/gmail/auth/initiate/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 生成Google OAuth授权URL，供用户访问并获取授权码
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"client_secret_json": "String (必填,二选一): Google OAuth客户端凭证(JSON格式字符串)",
|
||
"client_secret_file": "File (必填,二选一): 上传的客户端凭证JSON文件"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"auth_url": "String: 用户需访问的授权URL",
|
||
"status": "String: 接口调用状态"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
生成Google OAuth授权链接，用户通过访问此链接授予应用访问Gmail账户的权限，并获取授权码用于后续步骤。
|
||
|
||
---
|
||
|
||
### 1.2 完成OAuth授权
|
||
|
||
- **接口URL**: `/api/gmail/auth/complete/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 使用授权码完成OAuth流程，获取并保存Gmail访问凭证
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"client_secret_json": "String (必填): Google OAuth客户端凭证(JSON格式)",
|
||
"auth_code": "String (必填): 用户从授权URL获得的授权码"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"id": "Integer: 凭证ID",
|
||
"email": "String: 关联的Gmail邮箱地址",
|
||
"is_default": "Boolean: 是否为默认账户",
|
||
"created_at": "DateTime: 创建时间",
|
||
"status": "String: 操作状态"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
完成OAuth2.0授权流程，将用户的授权码转换为访问令牌，并将凭证保存到系统中，以便后续API调用。
|
||
|
||
---
|
||
|
||
### 1.3 获取Gmail凭证列表
|
||
|
||
- **接口URL**: `/api/gmail/credentials/`
|
||
- **请求方式**: `GET`
|
||
- **接口描述**: 获取系统中所有已授权的Gmail账户凭证列表
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"results": [
|
||
{
|
||
"id": "Integer: 凭证ID",
|
||
"email": "String: Gmail邮箱地址",
|
||
"is_default": "Boolean: 是否为默认账户",
|
||
"created_at": "DateTime: 创建时间"
|
||
}
|
||
],
|
||
"count": "Integer: 总记录数"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
列出系统中所有已授权的Gmail账户，便于用户查看和管理多个Gmail账户。
|
||
|
||
---
|
||
|
||
### 1.4 设置默认Gmail账户
|
||
|
||
- **接口URL**: `/api/gmail/credentials/{id}/set_default/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 将指定ID的Gmail账户设置为默认账户
|
||
|
||
#### 路径参数
|
||
```json
|
||
{
|
||
"id": "Integer (必填): 凭证ID"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"status": "String: 操作状态",
|
||
"message": "String: 操作结果信息"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
设置系统默认使用的Gmail账户，当未指定账户时，系统操作将使用此默认账户。
|
||
|
||
---
|
||
|
||
## 2. 对话管理
|
||
|
||
### 2.1 创建Gmail对话
|
||
|
||
- **接口URL**: `/api/gmail/conversations/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 创建并保存用户与特定联系人的邮件对话
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"user_email": "String (必填): 用户Gmail邮箱",
|
||
"influencer_email": "String (必填): 对话方Gmail邮箱",
|
||
"kb_id": "Integer (可选): 关联的知识库ID"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"conversation_id": "Integer: 创建的会话ID",
|
||
"user_email": "String: 用户Gmail邮箱",
|
||
"influencer_email": "String: 对话方Gmail邮箱",
|
||
"created_at": "DateTime: 创建时间",
|
||
"status": "String: 操作状态"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
创建并保存特定邮箱之间的对话关系，为后续邮件往来、自动回复和内容分析建立基础。
|
||
|
||
---
|
||
|
||
### 2.2 获取对话列表
|
||
|
||
- **接口URL**: `/api/gmail/conversations/`
|
||
- **请求方式**: `GET`
|
||
- **接口描述**: 获取所有保存的Gmail邮件对话
|
||
|
||
#### 查询参数
|
||
```json
|
||
{
|
||
"user_email": "String (可选): 筛选特定用户的对话",
|
||
"influencer_email": "String (可选): 筛选与特定联系人的对话"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"results": [
|
||
{
|
||
"id": "Integer: 对话ID",
|
||
"user_email": "String: 用户Gmail邮箱",
|
||
"influencer_email": "String: 对话方Gmail邮箱",
|
||
"last_message_time": "DateTime: 最后消息时间",
|
||
"message_count": "Integer: 消息数量"
|
||
}
|
||
],
|
||
"count": "Integer: 总记录数"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
查询系统中保存的所有Gmail对话，可通过筛选参数查找特定用户或联系人的对话记录。
|
||
|
||
---
|
||
|
||
### 2.3 获取对话摘要
|
||
|
||
- **接口URL**: `/api/gmail/conversations/summary/{conversation_id}/`
|
||
- **请求方式**: `GET`
|
||
- **接口描述**: 获取特定对话的AI生成摘要信息
|
||
|
||
#### 路径参数
|
||
```json
|
||
{
|
||
"conversation_id": "Integer (必填): 对话ID"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"conversation_id": "Integer: 对话ID",
|
||
"summary": "String: AI生成的对话摘要",
|
||
"key_points": ["String: 关键点1", "String: 关键点2"],
|
||
"sentiment": "String: 情感分析结果",
|
||
"last_updated": "DateTime: 最后更新时间"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
使用AI技术自动分析对话内容，生成对话摘要、提取关键点并进行情感分析，帮助用户快速了解对话内容和进展。
|
||
|
||
---
|
||
|
||
## 3. 邮件管理
|
||
|
||
### 3.1 发送邮件
|
||
|
||
- **接口URL**: `/api/gmail/send/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 通过指定Gmail账户发送邮件
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"email": "String (必填): 发件人Gmail邮箱",
|
||
"to": "String (必填): 收件人邮箱，多个收件人用逗号分隔",
|
||
"subject": "String (必填): 邮件主题",
|
||
"body": "String (必填): 邮件正文内容(支持HTML)",
|
||
"cc": "String (可选): 抄送邮箱，多个用逗号分隔",
|
||
"bcc": "String (可选): 密送邮箱，多个用逗号分隔",
|
||
"attachments": ["String: 附件ID1", "String: 附件ID2"]
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"message_id": "String: 发送的邮件ID",
|
||
"thread_id": "String: Gmail线程ID",
|
||
"status": "String: 发送状态",
|
||
"timestamp": "DateTime: 发送时间戳"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
使用已授权的Gmail账户发送邮件，支持HTML内容、抄送、密送和附件，返回发送状态和邮件ID。
|
||
|
||
---
|
||
|
||
### 3.2 获取附件列表
|
||
|
||
- **接口URL**: `/api/gmail/attachments/{conversation_id}/`
|
||
- **请求方式**: `GET`
|
||
- **接口描述**: 获取特定对话中的所有附件
|
||
|
||
#### 路径参数
|
||
```json
|
||
{
|
||
"conversation_id": "Integer (必填): 对话ID"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"results": [
|
||
{
|
||
"id": "String: 附件ID",
|
||
"filename": "String: 文件名",
|
||
"size": "Integer: 文件大小(字节)",
|
||
"mime_type": "String: MIME类型",
|
||
"message_id": "String: 所属邮件ID",
|
||
"created_at": "DateTime: 创建时间"
|
||
}
|
||
],
|
||
"count": "Integer: 总记录数"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
检索特定对话中的所有邮件附件信息，包括文件名、大小和类型，便于管理和下载附件。
|
||
|
||
---
|
||
|
||
## 4. 推送通知
|
||
|
||
### 4.1 设置Gmail推送通知
|
||
|
||
- **接口URL**: `/api/gmail/notifications/setup/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 为指定Gmail账户设置实时邮件推送通知
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"email": "String (必填): 要监听的Gmail邮箱地址",
|
||
"topic_name": "String (可选): 自定义Pub/Sub主题名称"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"status": "String: 设置状态",
|
||
"topic": "String: Pub/Sub主题名称",
|
||
"expiration": "DateTime: 通知过期时间",
|
||
"message": "String: 操作结果信息"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
使用Google Pub/Sub为Gmail账户设置实时通知，当有新邮件时，系统会接收到推送通知，从而实现邮件的实时处理。
|
||
|
||
---
|
||
|
||
### 4.2 接收Gmail推送通知
|
||
|
||
- **接口URL**: `/api/gmail/webhook/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 接收Google Pub/Sub推送的Gmail新邮件通知
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"message": {
|
||
"data": "String (必填): Base64编码的通知数据",
|
||
"attributes": "Object (可选): 消息属性"
|
||
},
|
||
"subscription": "String (必填): 订阅名称"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"status": "String: 处理状态",
|
||
"received": "Boolean: 是否成功接收"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
作为Webhook端点接收Google Pub/Sub推送的Gmail新邮件通知，解析通知内容并触发相应的处理逻辑，如自动回复和更新对话。
|
||
|
||
---
|
||
|
||
## 5. 自动回复功能
|
||
|
||
### 5.1 设置对话目标
|
||
|
||
- **接口URL**: `/api/gmail/goals/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 为特定对话设置AI自动回复的目标
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"conversation_id": "Integer (必填): 对话ID",
|
||
"goal_description": "String (必填): 目标描述文本",
|
||
"priority": "Integer (可选): 优先级(1-5)",
|
||
"auto_reply": "Boolean (可选): 是否启用自动回复"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"id": "Integer: 目标ID",
|
||
"conversation_id": "Integer: 对话ID",
|
||
"goal_description": "String: 目标描述",
|
||
"priority": "Integer: 优先级",
|
||
"auto_reply": "Boolean: 是否启用自动回复",
|
||
"created_at": "DateTime: 创建时间",
|
||
"status": "String: 操作状态"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
为指定的Gmail对话设置AI处理目标，系统会根据目标生成推荐回复或自动回复邮件，帮助用户实现特定的沟通目标。
|
||
|
||
---
|
||
|
||
### 5.2 获取对话目标列表
|
||
|
||
- **接口URL**: `/api/gmail/goals/`
|
||
- **请求方式**: `GET`
|
||
- **接口描述**: 获取所有设置的对话目标
|
||
|
||
#### 查询参数
|
||
```json
|
||
{
|
||
"conversation_id": "Integer (可选): 筛选特定对话的目标",
|
||
"active": "Boolean (可选): 筛选活跃/非活跃目标"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"results": [
|
||
{
|
||
"id": "Integer: 目标ID",
|
||
"conversation_id": "Integer: 对话ID",
|
||
"goal_description": "String: 目标描述",
|
||
"priority": "Integer: 优先级",
|
||
"auto_reply": "Boolean: 是否启用自动回复",
|
||
"created_at": "DateTime: 创建时间"
|
||
}
|
||
],
|
||
"count": "Integer: 总记录数"
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
获取系统中设置的所有对话目标，可通过参数筛选特定对话的目标或活跃/非活跃目标。
|
||
|
||
---
|
||
|
||
### 5.3 获取推荐回复
|
||
|
||
- **接口URL**: `/api/gmail/recommended-reply/`
|
||
- **请求方式**: `POST`
|
||
- **接口描述**: 获取针对特定对话的AI推荐回复内容
|
||
|
||
#### 请求参数
|
||
```json
|
||
{
|
||
"conversation_id": "Integer (必填): 对话ID",
|
||
"last_message_id": "String (可选): 最后接收的邮件ID",
|
||
"custom_instructions": "String (可选): 自定义回复指示"
|
||
}
|
||
```
|
||
|
||
#### 响应参数
|
||
```json
|
||
{
|
||
"goal": {
|
||
"id": "Integer: 目标ID",
|
||
"description": "String: 目标描述"
|
||
},
|
||
"conversation_summary": "String: 对话摘要",
|
||
"last_message": {
|
||
"sender": "String: 发送者",
|
||
"subject": "String: 主题",
|
||
"content": "String: 内容摘要"
|
||
},
|
||
"recommended_reply": "String: AI推荐的回复内容",
|
||
"alternative_replies": ["String: 备选回复1", "String: 备选回复2"]
|
||
}
|
||
```
|
||
|
||
#### 接口作用
|
||
基于对话历史、设定目标和最新邮件内容，使用AI生成推荐回复，帮助用户快速回应邮件并实现沟通目标。
|
||
|
||
---
|
||
|
||
## 使用说明
|
||
|
||
1. **授权流程**:
|
||
- 先调用"启动OAuth授权"接口获取授权URL
|
||
- 用户访问URL并获取授权码
|
||
- 调用"完成OAuth授权"接口保存Gmail账户凭证
|
||
|
||
2. **实时通知设置**:
|
||
- 授权成功后调用"设置Gmail推送通知"接口
|
||
- 确保webhook端点可从公网访问
|
||
|
||
3. **自动回复流程**:
|
||
- 创建对话并设置目标
|
||
- 系统接收新邮件推送通知
|
||
- 自动分析内容并生成回复
|
||
- 根据设置决定是推荐回复还是自动回复 |