资源工坊

配置第三方机器人 ​

功能概述 ​

第三方机器人是WPS服务台的核心开放能力之一。在配置第三方机器人后，WPS服务台仅作为输出形象，由第三方机器人接管服务台用户咨询，用户消息由服务台转发至第三方机器人，回复由第三方机器人通过接口返回至服务台并展示。

实现步骤 ​

  • 进入 服务台管理后台-服务台设置-开放配置 中开启 第三方机器人 功能
  • 按规则配置接收服务台请求的 URL 地址

服务台机器人回调接口签名说明 ​

接口概览 ​

提供两种类型的回调接口：

  • 流式接口：用于实时流式返回 AI 回答内容
  • 非流式接口：用于一次性返回完整的 AI 回答内容

两种接口使用相同的签名方式和入参结构。

通用签名说明 ​

签名生成过程 ​

go
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
)

// 通用请求体结构
type CallbackRequestBody struct {
    HelpdeskId   int64  `json:"helpdesk_id"`
    SessionId    string `json:"session_id"`
    Question     string `json:"question"`
    UserId       string  `json:"user_id"`
}

// 生成签名的核心函数
func GenerateSignature(secretKey string, helpdeskId int64, sessionId, question string, userId string) (string, error) {
    // 1. 构造请求体
    body := &CallbackRequestBody{
        HelpdeskId:   helpdeskId,
        SessionId:    sessionId,
        Question:     question,
        UserId:       userId,
    }
    
    // 2. 序列化为 JSON
    marshal, err := json.Marshal(body)
    if err != nil {
        return "", fmt.Errorf("JSON序列化失败: %v", err)
    }
    
    // 3. 计算 HMAC-SHA256 签名
    hm := hmac.New(sha256.New, []byte(secretKey))
    hm.Write(marshal)
    signatureStr := hex.EncodeToString(hm.Sum(nil))
    
    return signatureStr, nil
}

请求头设置 ​

将签名放入 HTTP Header 中：

http
signature: {生成的签名值}

流式接口 ​

基本信息 ​

  • 接口路径: POST
  • 请求头: accept: text/event-stream
  • 签名: 采用工作台签名规则

请求参数 ​

名称位置类型是否必传说明
helpdesk_idbodyinteger是服务台id
session_idbodystring是请求唯一id
questionbodystring是问题内容
user_idbodystring否当前设备登录用户,第三方联合id

响应参数 ​

响应采用 Server-Sent Events (SSE) 格式：

名称位置类型是否必须说明与示例
session_idbodystring是请求唯一id
startbodyobject否开始内容
start.textbodystring是ai loading文本，例如：正在理解问题
deltabodyobject否正文内容
delta.textbodystring是正文内容，连续传递会追加
referencebodyobject否引用内容，限制5个
reference.itemsbody[]object是引用
reference.items[].urlbodystring是引用链接
reference.items[].namebodystring是引用描述
reference.descbodystring是描述
finishbodyint64否结束标识，可以传当前时间戳，秒级别
heartbeatbodyint64否心跳检测，可以传当前时间戳，秒级别。服务台会有心跳检测，每一段数据超过10s则会断开

流式输出示例 ​

text
event:message
data:{"code": 0, "data": {"session_id": "1", "start": {"text": "正在理解问题"}}}

event:message
data:{"code": 0, "data": {"session_id": "1", "reference": {"items": [{"url": "http://www.kdocs.cn/xxx", "name": "文档"}], "desc": "参考文档"}}}

event:message
data:{"code": 0, "data": {"session_id": "1", "delta": {"text": "以下是问题答案：1.xxx"}}}

event:message
data:{"code": 0, "data": {"session_id": "1", "delta": {"text": "2.xxx"}}}

event:message
data:{"code": 0, "data": {"session_id": "1", "heartbeat": 123}}

event:message
data:{"code": 0, "data": {"session_id": "1", "finish": 123}}

非流式接口 ​

基本信息 ​

  • 接口路径: POST
  • 请求头: Accept: application/json
  • 签名: 采用工作台签名规则

请求参数 ​

名称位置类型是否必传说明
helpdesk_idbodyinteger是服务台id
session_idbodystring是请求唯一id
questionbodystring是问题内容
user_idbodystring否当前设备登录用户,第三方联合id

响应参数 ​

名称位置类型是否必须说明与示例
session_idbodystring是请求唯一id
textbodystring否文本内容，支持markdown格式

非流式输出示例 ​

json
{
    "code": 0,
    "data": {
        "session_id": "123",
        "text": "正在理解问题\n\n以下是问题答案：\n1. xxx\n2. yyy"
    }
}

注意事项 ​

  1. 签名密钥：secret_key 从服务台页面获取
  2. 心跳机制：流式接口需要定期发送心跳，超过10秒无数据会断开连接
  3. 引用限制：流式接口的引用内容最多5个
  4. 消息限制：返回的消息整体限制在4000字符以内