wanjia/operations_project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e707cfd4e8
operations_project/apps/gmail/README_GMAIL.md
wanjia 487a1a5960 将达人已回复导出到excel
2025-05-21 11:14:08 +08:00

11 KiB
Raw Blame History

Gmail模块API接口文档 - Apifox测试版

1. 认证管理

1.1 启动OAuth授权

  • 接口URL: /api/gmail/auth/initiate/
  • 请求方式: POST
  • 接口描述: 生成Google OAuth授权URL，供用户访问并获取授权码

请求参数

{
  "client_secret_json": "String (必填,二选一): Google OAuth客户端凭证(JSON格式字符串)",
  "client_secret_file": "File (必填,二选一): 上传的客户端凭证JSON文件"
}

响应参数

{
  "auth_url": "String: 用户需访问的授权URL",
  "status": "String: 接口调用状态"
}

接口作用

生成Google OAuth授权链接，用户通过访问此链接授予应用访问Gmail账户的权限，并获取授权码用于后续步骤。

1.2 完成OAuth授权

  • 接口URL: /api/gmail/auth/complete/
  • 请求方式: POST
  • 接口描述: 使用授权码完成OAuth流程，获取并保存Gmail访问凭证

请求参数

{
  "client_secret_json": "String (必填): Google OAuth客户端凭证(JSON格式)",
  "auth_code": "String (必填): 用户从授权URL获得的授权码"
}

响应参数

{
  "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账户凭证列表

响应参数

{
  "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账户设置为默认账户

路径参数

{
  "id": "Integer (必填): 凭证ID"
}

响应参数

{
  "status": "String: 操作状态",
  "message": "String: 操作结果信息"
}

接口作用

设置系统默认使用的Gmail账户，当未指定账户时，系统操作将使用此默认账户。

2. 对话管理

2.1 创建Gmail对话

  • 接口URL: /api/gmail/conversations/
  • 请求方式: POST
  • 接口描述: 创建并保存用户与特定联系人的邮件对话

请求参数

{
  "user_email": "String (必填): 用户Gmail邮箱",
  "influencer_email": "String (必填): 对话方Gmail邮箱",
  "kb_id": "Integer (可选): 关联的知识库ID"
}

响应参数

{
  "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邮件对话

查询参数

{
  "user_email": "String (可选): 筛选特定用户的对话",
  "influencer_email": "String (可选): 筛选与特定联系人的对话"
}

响应参数

{
  "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生成摘要信息

路径参数

{
  "conversation_id": "Integer (必填): 对话ID"
}

响应参数

{
  "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账户发送邮件

请求参数

{
  "email": "String (必填): 发件人Gmail邮箱",
  "to": "String (必填): 收件人邮箱，多个收件人用逗号分隔",
  "subject": "String (必填): 邮件主题",
  "body": "String (必填): 邮件正文内容(支持HTML)",
  "cc": "String (可选): 抄送邮箱，多个用逗号分隔",
  "bcc": "String (可选): 密送邮箱，多个用逗号分隔",
  "attachments": ["String: 附件ID1", "String: 附件ID2"]
}

响应参数

{
  "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
  • 接口描述: 获取特定对话中的所有附件

路径参数

{
  "conversation_id": "Integer (必填): 对话ID"
}

响应参数

{
  "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账户设置实时邮件推送通知

请求参数

{
  "email": "String (必填): 要监听的Gmail邮箱地址",
  "topic_name": "String (可选): 自定义Pub/Sub主题名称"
}

响应参数

{
  "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新邮件通知

请求参数

{
  "message": {
    "data": "String (必填): Base64编码的通知数据",
    "attributes": "Object (可选): 消息属性"
  },
  "subscription": "String (必填): 订阅名称"
}

响应参数

{
  "status": "String: 处理状态",
  "received": "Boolean: 是否成功接收"
}

接口作用

作为Webhook端点接收Google Pub/Sub推送的Gmail新邮件通知，解析通知内容并触发相应的处理逻辑，如自动回复和更新对话。

5. 自动回复功能

5.1 设置对话目标

  • 接口URL: /api/gmail/goals/
  • 请求方式: POST
  • 接口描述: 为特定对话设置AI自动回复的目标

请求参数

{
  "conversation_id": "Integer (必填): 对话ID",
  "goal_description": "String (必填): 目标描述文本",
  "priority": "Integer (可选): 优先级(1-5)",
  "auto_reply": "Boolean (可选): 是否启用自动回复"
}

响应参数

{
  "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
  • 接口描述: 获取所有设置的对话目标

查询参数

{
  "conversation_id": "Integer (可选): 筛选特定对话的目标",
  "active": "Boolean (可选): 筛选活跃/非活跃目标"
}

响应参数

{
  "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推荐回复内容

请求参数

{
  "conversation_id": "Integer (必填): 对话ID",
  "last_message_id": "String (可选): 最后接收的邮件ID",
  "custom_instructions": "String (可选): 自定义回复指示"
}

响应参数

{
  "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. 自动回复流程:

    • 创建对话并设置目标
    • 系统接收新邮件推送通知
    • 自动分析内容并生成回复
    • 根据设置决定是推荐回复还是自动回复