七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入
AI Agent

三方智能体对接

企业提供 Agent 接口，由七鱼传入访客问题和会话上下文，并通过 SSE 接收机器人答案、转人工或卡片消息。

企业需要提供一个 Agent 接口。七鱼会把访客问题及会话上下文发送给该接口，并通过 SSE 接收三方智能体的流式响应。

请求方式

  • Method：POST；七鱼也会使用 GET 校验接口有效性。
  • Content-Type：application/json;charset=UTF-8

请求参数

字段名是否必填字段类型描述
robotId是Long七鱼智能机器人 ID，用于标识机器人。可以从在线机器人模块的浏览器地址栏获取。
sourceType是Integer来源场景：0-机器人会话，1-辅助人工，2-测试机器人。
sessionId是Long当前会话 ID；来源场景为测试机器人时和 robotId 一致。
foreignId否StringCRM 同步过来的外部访客 ID。
question是String访客发送的消息内容。
historyMsg否Array历史消息列表。
historyMsg[].role否String角色：user、assistant。
historyMsg[].content否String消息内容。
historyMsg[].msgTime否Long消息时间。
historyMsg[].mType否Integer消息类型：1-文本消息，2-图片消息，100-自定义消息，102-卡片消息，110-机器人消息，1001-商品卡片，1002-订单卡片。
questionUid是String访客消息对应的七鱼唯一 ID。
msgTime是Long访客发送消息的时间。

返回结果

流式输出

响应 Header 需要包含：

Content-Type: text/event-stream;charset=UTF-8

响应内容需要返回对应的事件 ID 和结果内容，不同事件返回的实体不同。

流式事件

事件描述
chat.start聊天开始。七鱼访客端开始展示机器人回答加载动画。
message.delta单条消息内容输出中，实时输出大模型应用的内容。
message.completed单条消息完成。目前支持 ANSWER、TRANSFER_AGENT、CARD 三种类型。ANSWER 表示机器人答案，需要返回完整消息内容；TRANSFER_AGENT 表示转人工；CARD 表示卡片消息。
chat.completed聊天结束。七鱼访客端结束机器人回答加载动画。
done流式输出完成，返回内容固定为 [DONE]。

事件对应响应参数

chat.start 事件

字段名字段类型描述
sessionIdLong当前会话 ID；来源场景为测试机器人时和 robotId 一致。
createAtLong创建时间，毫秒时间戳。

message.delta 事件

字段名字段类型描述
sessionIdLong当前会话 ID；来源场景为测试机器人时和 robotId 一致。
createAtLong创建时间，毫秒时间戳。
typeString类型。ANSWER 表示机器人答案。
contentString本次增量返回的内容。

message.completed 事件

字段名字段类型描述
sessionIdLong当前会话 ID；来源场景为测试机器人时和 robotId 一致。
completedAtLong完成时间，毫秒时间戳。
typeString类型：ANSWER-机器人答案，TRANSFER_AGENT-转人工客服，CARD-卡片消息。
contentObject返回内容。ANSWER 时为完整答案；TRANSFER_AGENT 时为转人工引导信息；CARD 时为卡片消息。

type = ANSWER 时，消息体格式如下：

{
  "content": "【自有大模型-随机内容】亐竆买狜蘭谒转癄犴瀏莤芘宵荼愳声黫炈鷐锐呉桰閚劙咗櫒鈔閱戊聜籣勎陶院转严堏皎鱤辇睈颧鋰琉恆圡欖虌劆垤遒巂蠚鵙斖韒磘鞘狐竪棉瑗鷆嫮飌熽及嬁洕緥毘陁黌诐譾圲銴箫刏狢躧嗦蝿灠岰喇閂蜈枓滘兤念糓稢樷蠍們秴魡帮溋鑒漜搏蔞蒈豳拀托啬皥竵吿羂郊黼瀎珸磃燱",
  "completedAt": 1728704856906,
  "sessionId": 12345,
  "type": "ANSWER"
}

type = TRANSFER_AGENT 时，消息体格式如下：

{
  "content": {
    "transType": 1,
    "groupId": 100109,
    "message": "转人工提示语"
  },
  "completedAt": 1728704856906,
  "sessionId": 12345,
  "type": "TRANSFER_AGENT"
}

groupId 传 0 时走默认规则；客服组 ID 可以通过查询客服组列表（基础信息）接口获取。

type = CARD 时，消息体格式如下：

data:{
  "content": {
    "cards": [
      {
        "type": "product",
        "data": [
          {
            "title": "商品标题",
            "picture": "https://123.com/123.jpg",
            "desc": "商品描述",
            "price": "100",
            "action": 0,
            "url": "htttps://123.com/mainpage"
          }
        ],
        "style": {
          "divider": 0
        }
      }
    ],
    "showStyle": 0, // 访客端卡片展示样式：0-平铺，1-换一换；换一换仅对商品卡片生效
    "cardLimit": 1 // 卡片展示数量限制；换一换样式下表示每批次展示数量
  },
  "completedAt": 1728704856906,
  "sessionId": 12345,
  "type": "CARD"
}

// 横向卡片列表
data:{
  "content": {
    "floatCards": [
      {
        "type": "product",
        "data": [
          {
            "title": "商品标题",
            "picture": "https://123.com/123.jpg",
            "desc": "商品描述",
            "price": "100",
            "action": 0,
            "url": "htttps://123.com/mainpage"
          }
        ],
        "style": {
          "divider": 0
        }
      }
    ]
  },
  "completedAt": 1728704856906,
  "sessionId": 12345,
  "type": "CARD"
}

卡片类型

商品卡片

商品卡片示例

{
  "cards": [
    {
      "type": "product",
      "data": [
        {
          "picture": "https://123.com/123.jpg", // 图片地址
          "title": "商品标题",
          "desc": "商品描述",
          "price": "100", // 商品价格
          "action": 0, // 点击动作：0-跳转 URL，1-发送对应商品卡片
          "url": "htttps://123.com/mainpage" // action=0 时的目标地址
        }
      ],
      "style": {
        "divider": 0 // 是否需要分割线：0-不需要，1-需要
      }
    }
  ],
  "showStyle": 0, // 访客端展示样式：0-平铺，1-换一换；换一换仅对商品卡片生效
  "cardLimit": 1 // 换一换样式下，每批次展示数量
}

订单卡片

订单卡片示例

{
  "cards": [
    {
      "type": "order",
      "orderId": "E20230510", // 订单 ID
      "orderTime": "2023-05-10 09:30", // 下单时间
      "data": [
        {
          "picture": "https://123.com/123.jpg", // 图片地址
          "title": "商品标题",
          "desc": "商品描述",
          "sku": "商品sku描述",
          "payMoney": "100", // 订单金额
          "count": 999, // 订单商品数量
          "status": "交易状态",
          "action": 0, // 点击动作：0-跳转 URL，1-发送对应商品卡片
          "url": "htttps://123.com/mainpage" // action=0 时的目标地址
        },
        {
          "picture": "https://123.com/123.jpg",
          "title": "商品标题",
          "desc": "商品描述",
          "sku": "商品sku描述",
          "payMoney": "100",
          "count": 999,
          "status": "交易状态",
          "action": 0,
          "url": "htttps://123.com/mainpage"
        }
      ],
      "style": {
        "divider": 0
      }
    }
  ]
}

节点流程卡片

节点流程卡片示例

{
  "cards": [
    {
      "type": "flow",
      "data": [
        {
          "title": "标题",
          "subtitle": "副标题",
          "current": 0 // 是否为当前步骤：0-否，1-是
        },
        {
          "title": "标题",
          "subtitle": "副标题",
          "current": 0
        },
        {
          "title": "标题",
          "subtitle": "副标题",
          "current": 1
        }
      ],
      "style": {
        "divider": 0
      }
    }
  ]
}

操作按钮

操作按钮卡片示例

// 若需要在按钮上方展示一段文字，可以在列表第一个对象传入富文本卡片内容
{
  "cards": [
    {
      "type": "rich",
      "content": "此处将展示一段文字",
      "style": {
        "divider": 1
      }
    },
    {
      "type": "button",
      "numInRow": 1, // 一行显示的按钮数
      "data": [
        {
          "title": "操作按钮标题",
          "action": 0, // 点击动作：0-跳转 URL，1-发送内容
          "url": "htttps://123.com/mainpage", // action=0 时的目标地址
          "content": "发送内容" // action=1 时发送的文本
        }
      ],
      "style": {
        "divider": 0
      }
    }
  ]
}

图片卡片

图片卡片示例

{
  "cards": [
    {
      "type": "image",
      "img": "https://123.com/123.jpg", // 图片地址
      "style": {
        "divider": 0
      }
    },
    {
      "type": "title",
      "content": "标题文字",
      "img": "https://123.com/123.jpg", // 左侧图片地址
      "style": {
        "divider": 0
      }
    },
    {
      "type": "rich",
      "content": "此处展示副标题文字",
      "style": {
        "divider": 1
      }
    },
    {
      "type": "link",
      "content": "操作按钮",
      "url": "htttps://123.com/mainpage", // 跳转链接
      "style": {
        "divider": 0
      }
    }
  ]
}

微信小程序卡片

在 content.cards[] 中将 type 设置为 miniProgram，即可返回微信小程序卡片。miniProgram 是 CARD 卡片对象 type 字段新增的枚举值。

小程序卡片必须包含以下字段，字段值均为非空字符串：

字段名类型是否必填描述
typeString是固定为 miniProgram，区分大小写。
appidString是目标微信小程序的 AppID。
nameString是小程序名称。
titleString是卡片标题。
thumburlString是卡片封面图片 URL。
pagepathString是点击卡片后进入的小程序页面路径，可包含业务查询参数。

卡片内容示例如下：

{
  "cards": [
    {
      "type": "miniProgram",
      "appid": "wx1234567890",
      "name": "示例小程序",
      "title": "查看业务详情",
      "thumburl": "https://example.com/card.jpg",
      "pagepath": "pages/detail/index?id=123"
    }
  ]
}

当前仅支持将 miniProgram 放在 content.cards[] 中，不支持放在 content.floatCards[] 中。content.floatCards[] 中的既有普通卡片类型仍按原协议处理。

chat.completed 事件

字段名字段类型描述
sessionIdLong当前会话 ID；来源场景为测试机器人时和 robotId 一致。
completedAtLong完成时间，毫秒时间戳。

done 事件

返回内容固定为 [DONE]。

流式输出示例

机器人答案类型

-- 聊天开始
event:chat.start
data:{"createAt":1728704841101,"sessionId":12345}

-- 单条消息内容输出
event:message.delta
data:{"content":"【自有大模型-随机内容】亐竆买狜蘭谒转癄犴瀏","createAt":1728704842783,"sessionId":12345,"type":"ANSWER"}

-- 单条消息内容输出
event:message.delta
data:{"content":"莤芘宵荼愳声黫炈鷐锐","createAt":1728704843992,"sessionId":12345,"type":"ANSWER"}

... 省略中间的单条消息内容输出事件

-- 单条消息内容输出
event:message.delta
data:{"content":"皥竵吿羂郊黼瀎珸磃燱","createAt":1728704855560,"sessionId":12345,"type":"ANSWER"}

-- 单条消息完成
event:message.completed
data:{"content":"【自有大模型-随机内容】亐竆买狜蘭谒转癄犴瀏莤芘宵荼愳声黫炈鷐锐呉桰閚劙咗櫒鈔閱戊聜籣勎陶院转严堏皎鱤辇睈颧鋰琉恆圡欖虌劆垤遒巂蠚鵙斖韒磘鞘狐竪棉瑗鷆嫮飌熽及嬁洕緥毘陁黌诐譾圲銴箫刏狢躧嗦蝿灠岰喇閂蜈枓滘兤念糓稢樷蠍們秴魡帮溋鑒漜搏蔞蒈豳拀托啬皥竵吿羂郊黼瀎珸磃燱","completedAt":1728704856906,"sessionId":12345,"type":"ANSWER"}

-- 聊天结束
event:chat.completed
data:{"completedAt":1728704858068,"sessionId":12345}

-- 流式结束
event:done
data:[DONE]

转接人工客服事件

-- 聊天开始
event:chat.start
data:{"createAt":1728704841101,"sessionId":12345}

-- 单条消息完成
event:message.completed
data:{"content":{"transType":1,"groupId":100109,"message":"转人工提示语"},"completedAt":1728704856906,"sessionId":12345,"type":"TRANSFER_AGENT"}

-- 聊天结束
event:chat.completed
data:{"completedAt":1728704858068,"sessionId":12345}

-- 流式结束
event:done
data:[DONE]

鉴权方式

七鱼调用企业提供的 Agent 接口，属于“七鱼服务器 → 企业服务器”的企业接口场景。鉴权字段与签名规则请参考企业接口接入 - 企业接口 header checkSum。

这篇文档有帮助吗？

批量更新用户标签

批量更新多个用户的标签。请求体为 JSON 数组，每项包含 foreignId/phone（至少一个）、tagIds（标签 ID 数组）、type（save/delete/replace）。单次最多 200 条（可配置）。需要企业开通客户标签服务。

API 工具对接

在七鱼 AI Agent 中创建自定义工具组，配置通用 Header、鉴权方式、API 工具及输入输出参数，并完成在线调试。

目录

请求方式
请求参数
返回结果
流式输出
流式事件
事件对应响应参数
chat.start 事件
message.delta 事件
message.completed 事件
卡片类型
商品卡片
订单卡片
节点流程卡片
操作按钮
图片卡片
微信小程序卡片
chat.completed 事件
done 事件
流式输出示例
机器人答案类型
转接人工客服事件
鉴权方式