跳到主要内容

生成回复建议

本接口用于根据上下文和聊天历史生成对话回复建议。调用此接口后，AI Agent 会基于指定的对话历史上下文，生成多条回复建议供用户选择。

使用场景​

  • 智能回复助手：在聊天应用中，为用户提供快速回复建议，提升回复效率。
  • 客服辅助：在客服场景中，为客服人员提供基于历史对话的回复建议。
  • 社交应用：在社交应用中，帮助用户快速生成合适的回复内容。

前置条件​

  • 已创建 AI Agent，获取 Agent 唯一标识（agentId）。创建方法请参考创建 AI Agent。
  • 已获取应用的 App Key / Secret，用于 API 请求签名。获取方法请参考API 请求签名。

请求方法​

POST：https://数据中心域名/v3/chat/suggest.json

签名规则：所有服务端 API 请求均需要进行规则校验，详见 API 请求签名。

正文参数​

HTTP 请求正文数据格式为 application/json，支持以下参数：

参数类型必传说明
agentIdString是Agent 唯一标识。
providerObject是上下文提供者，用于提供对话上下文信息，必填且不能为空。上下文提供者用于从指定数据源获取对话历史，为 AI Agent 生成回复建议提供上下文参考。详见下方 provider 参数说明。
provider.typeString是提供者类型：
・ chatHistory：融云历史消息数据源
variablesMap<String, String>否变量对象，用于传递变量到上下文处理中：
・ 最多支持 16 个键值对
・ 键长度：1–32 个字符
・ 值长度：≤ 128 个字符
metadataMap<String, String>否元数据对象，用于传递元数据信息：
・ 最多支持 16 个键值对
・ 键长度：1–32 个字符
・ 值长度：≤ 512 个字符

provider.chatHistory 参数​

参数类型必传说明
provider.userIdString是用户 ID：
・ 长度 ≤ 64 个字符
・ 用于标识会话中的一方用户
provider.targetIdString是Target ID：
・ 长度 ≤ 64 个字符
・ 用于标识会话中的另一方用户或会话目标
・ 单聊场景下，targetId 为对端用户的用户 ID
provider.limitInteger否最大消息数量：
・ 默认值：10
・ 范围：1–100
provider.conversationTypeInteger否会话类型：
・ 默认值：1
・ 固定值：1（单聊）
・ 当前仅支持单聊会话

请求示例​

以下示例展示了如何调用接口生成回复建议。示例中，userId 为 u_1001，targetId 为 u_2001，表示获取这两个用户之间的单聊历史消息，并基于这些消息生成回复建议。

HTTP
POST /v3/chat/suggest.json HTTP/1.1
Host: api.rong-api.com
App-Key: e0x9wycfx7flq
Nonce: 1068826355
Timestamp: 1741248603
Signature: 5c6b3f0deb891623b2e8bcef577bc4782a067ea8
Content-Type: application/json

{
  "agentId": "social_reply_bot",
  "provider": {
    "type": "chatHistory",
    "userId": "u_1001",
    "targetId": "u_2001",
    "limit": 10,
    "conversationType": 1
  },
  "variables": {},
  "metadata": {
    "age": "25",
    "location": "北京"
  }
}

返回结果​

接口调用成功后，将返回生成的回复建议列表。每个建议包含一个或多个消息，表示一条完整的回复内容。

参数类型说明
codeInt返回码，200 表示处理成功。
runIdString本次建议生成的运行 ID。
agentIdStringAgent 唯一标识。
timestampLong响应时间戳（Unix 时间戳，单位：毫秒）。
suggestionsArray<Object>回复建议列表。
suggestions[].idString建议唯一标识。
suggestions[].messagesArray<Object>建议消息列表。
suggestions[].messages[].contentString消息内容文本，为 AI 生成的回复建议内容。

返回示例​

以下示例展示了接口成功返回的结果。返回结果中包含两个回复建议（s_1 和 s_2），其中 s_1 包含两条消息，s_2 包含一条消息。

HTTP
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-ID: XXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
  "code": 200,
  "runId": "run_123456789",
  "agentId": "social_reply_bot",
  "timestamp": 1677652288000,
  "suggestions": [
    {
      "id": "s_1",
      "messages": [
        {
          "content": "小明，你怎么还没睡？"
        },
        {
          "content": "早点休息哦！"
        }
      ]
    },
    {
      "id": "s_2",
      "messages": [
        {
          "content": "早点休息。"
        }
      ]
    }
  ]
}

错误码​

详见 错误码说明。