boss_dp/复聊配置API使用指南.md

复聊配置 API 使用指南

API 端点

1. 复聊配置管理

获取配置列表

GET /api/followup-configs

查询参数：

• position: 岗位类型（可选）
• is_active: 是否启用（可选）

响应示例：

[
  {
    "id": 1,
    "name": "Python开发复聊配置",
    "position": "Python开发",
    "is_active": true,
    "scripts": [
      {
        "id": 1,
        "day_number": 1,
        "content": "后续沟通会更及时，您方便留一下您的微信号吗？我这边加您。",
        "interval_hours": 24,
        "order": 1
      }
    ]
  }
]

创建配置

POST /api/followup-configs
Content-Type: application/json

{
  "name": "Python开发复聊配置",
  "position": "Python开发",
  "is_active": true
}

更新配置

PUT /api/followup-configs/{id}
Content-Type: application/json

{
  "name": "Python开发复聊配置（更新）",
  "is_active": true
}

删除配置

DELETE /api/followup-configs/{id}

2. 复聊话术管理

获取话术列表

GET /api/followup-scripts?config_id=1

查询参数：

• config_id: 配置ID（可选）
• day_number: 第几天（可选）

创建话术

POST /api/followup-scripts
Content-Type: application/json

{
  "config_id": 1,
  "day_number": 1,
  "content": "您好，期待与您进一步沟通。",
  "interval_hours": 24,
  "order": 1,
  "is_active": true
}

字段说明：

• day_number:
  • 1 = 第一天
  • 2 = 第二天
  • 0 = 往后一直使用这个话术
• interval_hours: 距离上次发送的间隔小时数
• order: 同一天有多条话术时的排序

更新话术

PUT /api/followup-scripts/{id}
Content-Type: application/json

{
  "content": "更新后的话术内容",
  "interval_hours": 48
}

删除话术

DELETE /api/followup-scripts/{id}

3. 复聊记录查询

获取记录列表

GET /api/followup-records?contact_id=1

查询参数：

• contact_id: 联系人ID（可选）
• config_id: 配置ID（可选）
• got_reply: 是否得到回复（可选）
• page: 页码（默认1）
• page_size: 每页数量（默认20）

响应示例：

{
  "total": 10,
  "page": 1,
  "page_size": 20,
  "results": [
    {
      "id": 1,
      "contact_id": 1,
      "config_id": 1,
      "script_id": 1,
      "day_number": 1,
      "content": "您好，期待与您进一步沟通。",
      "sent_at": "2026-03-05T10:30:00Z",
      "got_reply": true,
      "reply_content": "好的，我的微信是 wx123456",
      "replied_at": "2026-03-05T10:35:00Z"
    }
  ]
}

手动发送复聊消息

POST /api/followup-records/send
Content-Type: application/json

{
  "contact_id": 1,
  "content": "您好，我想和您聊聊这个职位。"
}

使用场景

场景1：创建Python开发的复聊配置

# 1. 创建配置
curl -X POST http://localhost:8000/api/followup-configs \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Python开发复聊配置",
    "position": "Python开发",
    "is_active": true
  }'

# 假设返回的 config_id = 1

# 2. 添加第1天的话术
curl -X POST http://localhost:8000/api/followup-scripts \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": 1,
    "day_number": 1,
    "content": "后续沟通会更及时，您方便留一下您的微信号吗？我这边加您。",
    "interval_hours": 24,
    "order": 1,
    "is_active": true
  }'

# 3. 添加第2天的话术
curl -X POST http://localhost:8000/api/followup-scripts \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": 1,
    "day_number": 2,
    "content": "您好，不知道您是否方便留个联系方式？",
    "interval_hours": 24,
    "order": 1,
    "is_active": true
  }'

# 4. 添加"往后一直"的话术
curl -X POST http://localhost:8000/api/followup-scripts \
  -H "Content-Type: application/json" \
  -d '{
    "config_id": 1,
    "day_number": 0,
    "content": "您好，如果您感兴趣可以随时联系我。",
    "interval_hours": 72,
    "order": 1,
    "is_active": true
  }'

场景2：查看某个联系人的复聊记录

curl http://localhost:8000/api/followup-records?contact_id=1

场景3：手动发送复聊消息

curl -X POST http://localhost:8000/api/followup-records/send \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": 1,
    "content": "您好，我想和您聊聊这个职位。"
  }'

复聊逻辑说明

自动复聊流程

1. 第一次联系：发送询问微信号的消息
2. 等待回复：等待30秒，检查是否有回复
3. 第1天：如果没有回复，发送第1天的话术
4. 第2天：如果还没有回复，且距离上次发送超过24小时，发送第2天的话术
5. 第3天及以后：继续按配置的间隔时间发送话术
6. 往后一直：当没有特定天数的话术时，使用 day_number=0 的话术

消息过滤逻辑

问题：之前会识别到自己发送的包含"微信号"三个字的消息

解决方案：

1. 通过 fromId 字段区分消息来源
2. 只保留 fromId=0 的消息（对方发送的）
3. 在等待回复时，过滤掉包含发送话术内容的消息
4. 过滤掉包含"微信号"关键词但没有真实微信号的消息

间隔时间控制

• 每条话术都有 interval_hours 字段
• 系统会检查距离上次发送的时间
• 只有超过间隔时间才会发送下一条
• 避免频繁打扰候选人

数据库表结构

FollowUpConfig（复聊配置表）

CREATE TABLE follow_up_config (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(128),
    position VARCHAR(64),
    is_active BOOLEAN DEFAULT TRUE,
    created_at DATETIME,
    updated_at DATETIME
);

FollowUpScript（复聊话术表）

CREATE TABLE follow_up_script (
    id INT PRIMARY KEY AUTO_INCREMENT,
    config_id INT,
    day_number INT,  -- 1=第一天, 2=第二天, 0=往后一直
    content TEXT,
    interval_hours INT DEFAULT 24,
    order INT DEFAULT 0,
    is_active BOOLEAN DEFAULT TRUE,
    created_at DATETIME
);

FollowUpRecord（复聊记录表）

CREATE TABLE follow_up_record (
    id INT PRIMARY KEY AUTO_INCREMENT,
    contact_id INT,
    config_id INT,
    script_id INT,
    day_number INT,
    content TEXT,
    sent_at DATETIME,
    got_reply BOOLEAN DEFAULT FALSE,
    reply_content TEXT,
    replied_at DATETIME
);

前端集成示例

Vue.js 示例

// 获取复聊配置列表
async function getFollowUpConfigs() {
  const response = await fetch('/api/followup-configs');
  const configs = await response.json();
  return configs;
}

// 创建复聊配置
async function createFollowUpConfig(data) {
  const response = await fetch('/api/followup-configs', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(data)
  });
  return await response.json();
}

// 添加话术
async function addFollowUpScript(configId, scriptData) {
  const response = await fetch('/api/followup-scripts', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      config_id: configId,
      ...scriptData
    })
  });
  return await response.json();
}

// 查看复聊记录
async function getFollowUpRecords(contactId) {
  const response = await fetch(`/api/followup-records?contact_id=${contactId}`);
  const data = await response.json();
  return data.results;
}

注意事项

1. 配置优先级：先匹配岗位配置，如果没有则使用通用配置
2. 话术顺序：按 day_number 和 order 排序
3. 间隔控制：系统会自动检查间隔时间，避免频繁发送
4. 消息过滤：只识别对方发送的消息，避免误识别
5. 自动保存：提取到联系方式后自动保存到 ContactRecord 表

测试建议

1. 先创建一个测试配置，设置较短的间隔时间（如1小时）
2. 运行招聘任务，观察复聊是否正常工作
3. 检查 FollowUpRecord 表，确认记录是否正确保存
4. 根据实际效果调整话术内容和间隔时间