API 接口文档

千牛监控软件提供完整的WebSocket和HTTP API接口，让您轻松集成千牛客服系统

概述

懒猫旅行千牛监控软件提供WebSocket和HTTP两种方式的API接口，用于与千牛客服系统进行交互。

接口地址
  • WebSocket地址: ws://127.0.0.1:9005
  • HTTP基础地址: http://127.0.0.1:9005

WebSocket API

连接说明

WebSocket连接建立后，支持双向通信。客户端可以发送消息到服务器，服务器也会主动推送消息到客户端。

WS 连接地址
ws://127.0.0.1:9005

消息格式

所有WebSocket消息均采用JSON格式：

{ "requestId": "请求唯一标识", "action": "操作类型", "params": { "参数名": "参数值" }, "version": "1.0" }

心跳机制

PING Ping消息

发送格式

{ "type": "ping", "timestamp": 1640995200000 }

响应格式

{ "type": "pong", "result": true }

消息发送

ACTION 发送消息到千牛

Action: sendMessage

请求格式

{ "requestId": "req123456", "action": "sendMessage", "params": { "recipient": "cntaobaob13337308195", "content": "要发送的消息内容" }, "version": "1.0" }

参数说明

参数名 类型 必填 说明
requestId String 是 请求唯一标识符
recipient String 是 接收者ID（千牛用户ID）
content String 是 消息内容

响应格式

{ "success": true, "data": { "messageId": "msg_123456", "recipient": "cntaobaob13337308195", "sendTime": "2024-01-27T10:30:00Z", "message": "消息发送成功" } }

系统操作

ACTION 获取客户端版本

Action: getClientVersion

{ "requestId": "req123456", "action": "getClientVersion", "params": {}, "version": "1.0" }
ACTION 执行JavaScript代码

Action: jsCode

{ "requestId": "req123456", "action": "jsCode", "params": { "code": "document.title" }, "version": "1.0" }

聊天操作

ACTION 打开聊天窗口

Action: openChat

{ "requestId": "req123456", "action": "openChat", "params": { "userNick": "cntaobaob13337308195", "domain": "taobao", "role": "buyer" }, "version": "1.0" }
ACTION 获取聊天记录

Action: getChatHistory

{ "requestId": "req123456", "action": "getChatHistory", "params": { "buyerUid": "123456789", "location": "local", "count": 20 }, "version": "1.0" }

账户管理

ACTION 设置挂起状态

Action: setSuspendStatus

{ "requestId": "req123456", "action": "setSuspendStatus", "params": { "accountIds": ["account1", "account2"], "suspended": true }, "version": "1.0" }
ACTION 获取旺旺UID

Action: getWangwangUid

{ "requestId": "req123456", "action": "getWangwangUid", "params": { "searchKey": "b13337308195" }, "version": "1.0" }

HTTP API

消息发送接口

POST /api/sendMessage

发送消息到千牛系统的HTTP接口。

请求参数

  • 请求方法: POST
  • Content-Type: application/json

请求体

{ "requestId": "req123456", "action": "sendMessage", "params": { "recipient": "cntaobaob13337308195", "content": "要发送的消息内容" }, "version": "1.0" }

成功响应

{ "success": true, "data": { "messageId": "msg_123456", "recipient": "cntaobaob13337308195", "sendTime": "2024-01-27T10:30:00Z", "message": "消息发送成功" }, "timestamp": "2024-01-27T10:30:00Z" }

错误响应

{ "success": false, "error": "错误描述", "timestamp": "2024-01-27T10:30:00Z" }

Cookie获取接口

GET /api/cookies

获取千牛客户端的Cookie信息。

请求参数

  • 请求方法: GET
  • Accept: application/json

成功响应

{ "success": true, "cookies": { "sessionId": "session_value", "userId": "user_id_value", "token": "auth_token_value" }, "timestamp": "2024-01-27T10:30:00Z" }

错误码说明

错误码 说明
200 成功
400 请求参数错误
401 认证失败
404 接口不存在
500 服务器内部错误
1001 千牛客户端未启动
1002 千牛窗口未找到
1003 消息发送失败
1004 用户不在线

使用示例

JavaScript WebSocket客户端示例

// 创建WebSocket连接 const socket = new WebSocket('ws://127.0.0.1:9005'); // 连接成功 socket.onopen = function() { console.log('WebSocket连接已建立'); // 发送测试消息 const message = { requestId: 'req' + Date.now(), action: 'sendMessage', params: { recipient: 'cntaobaob13337308195', content: '你好，这是测试消息' }, version: '1.0' }; socket.send(JSON.stringify(message)); }; // 接收消息 socket.onmessage = function(event) { const data = JSON.parse(event.data); console.log('收到消息:', data); }; // 连接关闭 socket.onclose = function() { console.log('WebSocket连接已关闭'); }; // 连接错误 socket.onerror = function(error) { console.error('WebSocket连接错误:', error); };

HTTP API调用示例

// 发送消息 async function sendMessage(recipient, content) { const response = await fetch('http://127.0.0.1:9005/api/sendMessage', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': 'application/json' }, body: JSON.stringify({ requestId: 'req' + Date.now(), action: 'sendMessage', params: { recipient: recipient, content: content }, version: '1.0' }) }); const result = await response.json(); return result; } // 获取Cookie async function getCookies() { const response = await fetch('http://127.0.0.1:9005/api/cookies', { method: 'GET', headers: { 'Accept': 'application/json' } }); const result = await response.json(); return result; }

注意事项

重要提醒
  1. 连接限制: 同时只能建立一个WebSocket连接
  2. 消息格式: 所有消息必须为有效的JSON格式
  3. 编码: 统一使用UTF-8编码
  4. 超时: HTTP请求超时时间为30秒，WebSocket连接超时为60秒
  5. 频率限制: 发送消息频率不能超过每秒10次
  6. 依赖: 需要千牛客服软件正常运行
  7. 权限: 部分操作需要千牛客服具有相应权限