267 lines
6.5 KiB
Markdown
267 lines
6.5 KiB
Markdown
# 智能客服API接口文档
|
||
|
||
## 一、接口说明
|
||
|
||
本接口用于连接微信小程序与Dify聊天机器人，实现智能客服功能。
|
||
|
||
## 二、配置说明
|
||
|
||
### 1. 安装插件
|
||
|
||
在ThinkPHP后台的插件管理页面中，找到智能客服插件（aikefu）并点击安装按钮。
|
||
|
||
### 2. 配置插件
|
||
|
||
1. 进入智能客服配置页面
|
||
2. 输入从Dify平台获取的API密钥
|
||
3. 配置API基础地址（默认：https://api.dify.ai/v1）
|
||
4. 配置聊天接口端点（默认：/chat-messages）
|
||
5. 启用智能客服功能
|
||
|
||
### 3. 获取Dify API密钥
|
||
|
||
1. 登录Dify平台
|
||
2. 进入工作台
|
||
3. 选择您的聊天机器人项目
|
||
4. 点击"发布"按钮
|
||
5. 在API访问页面获取API密钥
|
||
|
||
## 三、接口列表
|
||
|
||
### 1. 智能客服聊天接口
|
||
|
||
**接口地址**：`/api/kefu/chat`
|
||
|
||
**请求方式**：POST
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| message | string | 是 | 用户输入的消息内容 |
|
||
| user_id | string | 否 | 用户ID，默认使用当前登录会员ID |
|
||
| conversation_id | string | 否 | 会话ID，第一次聊天可不传，系统会自动创建 |
|
||
| stream | bool | 否 | 是否使用流式响应，默认false |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"conversation_id": "conv_123456789",
|
||
"reply": "您好，我是智能客服，有什么可以帮助您的？",
|
||
"message_id": "msg_123456789",
|
||
"finish_reason": "stop",
|
||
"usage": {
|
||
"prompt_tokens": 10,
|
||
"completion_tokens": 20,
|
||
"total_tokens": 30
|
||
}
|
||
},
|
||
"timestamp": 1640995200
|
||
}
|
||
```
|
||
|
||
### 2. 获取会话历史
|
||
|
||
**接口地址**：`/api/kefu/getHistory`
|
||
|
||
**请求方式**：POST
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| conversation_id | string | 是 | 会话ID |
|
||
| user_id | string | 否 | 用户ID，默认使用当前登录会员ID |
|
||
| limit | int | 否 | 每页条数，默认20 |
|
||
| offset | int | 否 | 偏移量，默认0 |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"messages": [
|
||
{
|
||
"id": "msg_123456789",
|
||
"role": "user",
|
||
"content": "你好",
|
||
"created_at": "2023-01-01T00:00:00Z"
|
||
},
|
||
{
|
||
"id": "msg_987654321",
|
||
"role": "assistant",
|
||
"content": "您好，我是智能客服，有什么可以帮助您的？",
|
||
"created_at": "2023-01-01T00:00:01Z"
|
||
}
|
||
],
|
||
"total": 2,
|
||
"limit": 20,
|
||
"offset": 0
|
||
},
|
||
"timestamp": 1640995200
|
||
}
|
||
```
|
||
|
||
### 3. 创建新会话
|
||
|
||
**接口地址**：`/api/kefu/createConversation`
|
||
|
||
**请求方式**：POST
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| user_id | string | 否 | 用户ID，默认使用当前登录会员ID |
|
||
|
||
**响应示例**：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"conversation_id": "conv_123456789",
|
||
"name": "智能客服会话",
|
||
"created_at": "2023-01-01T00:00:00Z"
|
||
},
|
||
"timestamp": 1640995200
|
||
}
|
||
```
|
||
|
||
## 四、前端调用示例
|
||
|
||
### Uniapp调用示例
|
||
|
||
```javascript
|
||
// 引入请求封装（根据项目实际情况调整）
|
||
import { request } from '@/utils/request';
|
||
|
||
// 智能客服聊天
|
||
async function chatWithAI(message, conversationId = '') {
|
||
try {
|
||
const res = await request({
|
||
url: '/api/kefu/chat',
|
||
method: 'POST',
|
||
data: {
|
||
message: message,
|
||
conversation_id: conversationId,
|
||
// user_id: 'your-user-id', // 可选
|
||
// stream: false // 可选
|
||
}
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
return res.data;
|
||
} else {
|
||
console.error('聊天失败:', res.message);
|
||
return null;
|
||
}
|
||
} catch (error) {
|
||
console.error('聊天请求失败:', error);
|
||
return null;
|
||
}
|
||
}
|
||
|
||
// 获取会话历史
|
||
async function getChatHistory(conversationId, limit = 20, offset = 0) {
|
||
try {
|
||
const res = await request({
|
||
url: '/api/kefu/getHistory',
|
||
method: 'POST',
|
||
data: {
|
||
conversation_id: conversationId,
|
||
limit: limit,
|
||
offset: offset
|
||
// user_id: 'your-user-id', // 可选
|
||
}
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
return res.data;
|
||
} else {
|
||
console.error('获取历史记录失败:', res.message);
|
||
return null;
|
||
}
|
||
} catch (error) {
|
||
console.error('获取历史记录请求失败:', error);
|
||
return null;
|
||
}
|
||
}
|
||
|
||
// 创建新会话
|
||
async function createNewConversation() {
|
||
try {
|
||
const res = await request({
|
||
url: '/api/kefu/createConversation',
|
||
method: 'POST',
|
||
data: {
|
||
// user_id: 'your-user-id', // 可选
|
||
}
|
||
});
|
||
|
||
if (res.code === 0) {
|
||
return res.data.conversation_id;
|
||
} else {
|
||
console.error('创建会话失败:', res.message);
|
||
return null;
|
||
}
|
||
} catch (error) {
|
||
console.error('创建会话请求失败:', error);
|
||
return null;
|
||
}
|
||
}
|
||
```
|
||
|
||
## 五、使用流程
|
||
|
||
1. **初始化会话**：小程序端进入客服页面时，调用`createConversation`接口创建新会话，或使用本地存储的会话ID
|
||
2. **发送消息**：用户输入消息后，调用`chat`接口发送消息，获取机器人回复
|
||
3. **显示消息**：将用户消息和机器人回复显示在聊天界面
|
||
4. **加载历史记录**：需要时调用`getHistory`接口加载历史消息
|
||
5. **维护会话**：保持会话ID，用于后续消息交流
|
||
|
||
## 六、注意事项
|
||
|
||
1. 请确保Dify API密钥的安全性，不要泄露给前端
|
||
2. 建议对用户ID进行加密处理，避免直接使用敏感信息
|
||
3. 对于大量用户的场景，建议实现会话管理机制，定期清理过期会话
|
||
4. 建议添加请求频率限制，防止恶意请求
|
||
5. 在生产环境中，建议关闭DEBUG模式
|
||
|
||
## 七、测试建议
|
||
|
||
1. 首先在Dify平台测试聊天机器人功能是否正常
|
||
2. 在后端配置正确的API密钥
|
||
3. 使用Postman或类似工具测试后端API接口
|
||
4. 在小程序端集成并测试完整流程
|
||
5. 模拟不同场景下的用户输入，测试机器人回复效果
|
||
|
||
## 八、常见问题
|
||
|
||
### 1. 接口返回401错误
|
||
|
||
**原因**：Dify API密钥无效或过期
|
||
**解决方法**：重新获取有效的API密钥并更新插件配置
|
||
|
||
### 2. 接口返回500错误
|
||
|
||
**原因**：后端服务器错误或Dify API服务异常
|
||
**解决方法**：查看服务器日志，检查Dify API服务状态
|
||
|
||
### 3. 机器人回复为空
|
||
|
||
**原因**：Dify聊天机器人配置问题或请求参数错误
|
||
**解决方法**：检查Dify机器人配置，验证请求参数是否正确
|
||
|
||
### 4. 会话ID无效
|
||
|
||
**原因**：会话已过期或不存在
|
||
**解决方法**：创建新会话，获取新的会话ID
|