跳到主要内容

API

对话类API​

  • 包括 HTTP 轮询模式和 HTTP SSE 模式，通过参数 sse 控制。下面先讲 HTTP 轮询模式（sse == False），后面 “接口使用说明” 一节再讲 HTTP SSE 模式（sse == True）

“启动对话”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_begin （需要把<your_server_url>替换为具体的url，下同）
  • HTTP GET 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由60位字符或数字组成的字符串
    • start_tree：启动的对话树名称（不带 “.xmind” 或 “.py” 后缀）
    • infoitem_params：启动对话树时传入的初始信息项的值，格式为 “{信息项1}=值|{\信息项2}=值|...”，这里不能有 “?”、“=”、“&”、“|” 等字符，否则需要自己单独进行URL的转义和反转义；但整个接口的 URL 长度最好不超过 2000 字符（转义后），因为某些 Web 服务器或代理会限制长度，如果有更大量的参数要传递，建议不用使用该接口的 infoitem_params，而是在对话树中调用相关 API 或 HTTP 来获取
    • audio_back：首次交互中，除了文本是否还要同时返回语音（即返回的 json 文本中是否包含 audio 字段），True/False，不传该参数的话缺省为 False
    • sse：是否使用 HTTP 的 SSE 模式，True/False，不传该参数的话缺省为 False
  • HTTP GET 返回值 返回值如果是以 “<...>” 标签开头的一段 HTML，则可能是服务器还未就绪，否则就是一段 json 文本，类似 \{"return_code":"......", "return_content":"......", ...\}，其中 return_code 是任何一个 API 接口返回时必有的字段，然后根据 return_code 值的不同再具有其它字段（下面其它接口类同，不再赘述）。return_code 字段是：
    • “error” 时表示出错。此时：
      • return_content 和 return_content_delta 字段都是出错的完整内容
    • “wait_result” 时表示成功启动对话, 需要继续调用 “对话结果” 接口，以流式的方式来获取对话机器人返回的完整话语。此时：
      • session_id 字段是所启动的对话的 id
      • return_content 和 return_content_delta 字段都是对话机器人的首次部分话语
      • audio_delta 字段（audio_back 参数为 True 时）是对话机器人的增量语音（含一段或多段语音的 list / 每段都是 base64 编码 mp3 格式 / 也可能是空 list）
      • structured_output 字段是返回的完整结构化信息（一般应该是 json 或 xml，可能为空）
  • 其它说明
    • 返回的 json 值中有回车、换行、单双引号等转义字符，Python 的 json.loads() 能自动处理好，其它编程语言也需要注意（下同）
    • 返回值中的话语如果要显示在浏览器中，可能需要对大于小于号、单引号、双引号、回车、反斜杠等字符进行相关替换处理，以免和 HTML Tag 冲突（下同）
    • 成功启动对话后，对话 session 的失效时间是最后一次调用 API 接口（5 种接口中的任何一种）之后 2 个小时

“对话交互”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_chat
  • HTTP GET 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由 60 位字符或数字组成的字符串
    • session_id：“启动对话”接口返回的 session_id
    • user_input：用户输入的文本
    • sse：是否使用 HTTP SSE 模式，True/False，不传该参数的话缺省为 False（下面先讲 False 的情况，即 HTTP 轮询模式；True 的情况，即 SSE 模式，见后面 “接口说明” 一节）
  • HTTP GET 返回值 return_code 字段是：
    • “error” 时表示出错。此时：
      • return_content 和 return_content_delta 字段都是出错的内容
    • “wait_result” 时表示对话机器人已经接收到用户的输入，需要继续调用 “对话结果” 接口，以流式的方式来获取对话机器人返回的完整话语。此时：
      • return_content 和 return_content_delta 字段都是对话机器人的首次部分话语
      • structured_output 字段是返回的完整结构化信息（一般应该是 json 或 xml，可能为空）

“对话交互(语音)”接口​

  • 接口类型：HTTP POST
  • 接口地址：https://<your_server_url>/sapi/intentchat_chat_audio
  • HTTP POST 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由 60 位字符或数字组成的字符串
    • session_id：“启动对话”接口返回的 session_id
    • audio_format：指上传的音频格式，可选 wav, pcm, mp3, speex, silk, m4a, aac, amr, ogg-opus（返回的音频格式只会是mp3）
    • audio_back：本次交互中，系统返回文本之外是否还同时返回语音（即返回的json文本中是否包含audio字段），True/False，不传该参数的话缺省为 True
    • [files]：HTTP POST body，用户语音（原始音频数据/非 base64 编码），16K 采样频率，音频格式见 audio_format 参数
    • sse：是否使用HTTP的SSE模式，True/False，不传该参数的话缺省为 False（下面先讲 False 的情况，即 HTTP 轮询模式；True 的情况，即 SSE 模式，见后面“接口说明”一节）
  • HTTP POST 返回值 return_code 字段是：
    • “error” 时表示出错。此时：
      • return_content 和 return_content_delta 字段都是出错的内容。如果出错内容是 “input audio too long ...”，表示用户语音太长，对于压缩语音格式（如mp3、opus）应小于30秒，非压缩格式（如wav、pcm）则时间更短
    • “wait_result” 时表示对话机器人已经接收到用户的输入，需要继续调用 “对话结果” 接口，以流式的方式来获取对话机器人返回的完整话语。此时：
      • return_content 和 return_content_delta 字段都是对话机器人的首次部分话语
      • audio_delta 字段对话机器人话语的增量语音（list / 包含一段或多段语音 / 每段都是 base64 编码的 mp3 格式 / 可能是个空 list）
      • user_input 字段是用户语音的文字内容
      • structured_output 字段是返回的完整结构化信息（一般应该是 json 或 xml，可能为空）

“对话结果”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_result
  • HTTP GET 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由 60 位字符或数字组成的字符串
    • session_id：“启动对话”接口返回的 session_id
  • HTTP GET 返回值 return_code 字段是：
    • “error” 时表示出错。此时：
      • return_content 和 return_content_delta 字段都是出错的内容
    • “go_on_chat” 或 “end_chat” 或 “end_chat_by_redirect_to_human” 时，表示成功完成了一次流式对话交互，如果是 “go_on_chat” 则可以继续调用 “对话交互” 接口或 “对话交互(语音)” 接口进行下一次对话交互、如果是 “end_chat” 则应结束对话、如果是 “end_chat_by_redirect_to_human” 则可以将对话转接到人工并结束本次对话。此时：
      • return_content 是本轮对话交互中对话机器人到目前为止的全部话语
      • return_content_delta 是本次调用生成的增量话语内容
      • user_input 字段（如果本次交互是调用 “对话交互(语音)” 接口发起时）是用户语音的文字内容
      • audio_delta 字段（如果本次交互是调用 “对话交互(语音)” 接口发起时、或者是参数 audio_back 为 True 的 “启动对话” 接口发起时）包含了机器人话语的增量语音（list / 包含一段或多段语音 / 每段语音都是 base64 编码的 mp3 格式 / 也可能是空 list）
      • 此时可以继续调用 “获取执行踪迹” 接口，获取对话状态，特别是 “end_chat_by_redirect_to_human” 要转接人工时，需要获取对话状态以便知道转接的具体原因以及将相关上下文信息传递给人工，具体见下面的 “获取执行踪迹” 接口说明
    • “wait_result” 时表示还需继续调用本接口获取对话机器人的话语。此时：
      • return_content 字段是以流式方式返回的对话机器人不断增加的、目前已生成的所有话语内容
      • return_content_delta 字段则是本次生成的增量话语内容
      • user_input 字段（如果本次交互是调用 “对话交互(语音)” 接口发起时）是用户语音的文字内容
      • audio_delta 字段（如果本次交互是调用 “对话交互(语音)” 接口发起时、或者是参数 audio_back 为 True 的 “启动对话” 接口发起时）包含了机器人话语的增量语音（list / 包含一段或多段语音 / 每段都是 base64 编码的 mp3 格式 / 可能是个空 list）
  • 其它说明
    • HTTP 轮询模式时才需调用该接口，HTTP SSE 模式时则不需调用该接口，见后面 “接口说明” 一节

“获取执行踪迹”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_get_execution_trace
  • HTTP GET参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由 60 位字符或数字组成的字符串
    • session_id：“启动对话”接口返回的 session_id
  • HTTP GET 返回值 return_code 字段是：
    • “error” 时表示出错。此时：
      • return_content 字段是出错的内容
    • “success” 时表示成功。此时：
      • return_content 是 json 文本格式的执行踪迹内容。该 json 中包括的字段有：【本轮对话的用户输入】、【本轮对话前所在节点】、【本轮对话前的信息项内容】、【本轮对话执行的节点列表】、【本轮对话后所在节点】、【本轮对话中的脚本调试信息】、【本轮对话后的信息项内容】、【本轮对话后所在的主题】、【本轮对话后所在的触发】、【本轮对话后所在的对话树】、【对话记录】、【本轮对话服务器端TTFT】
  • 其它说明
    • 该接口应在通过 “对话结果” 接口或 HTTP SSE 接收完所有流式返回结果后（即返回的数据包的 return_code 不再是 “wait_result”）再调用，如果其它接口有错误返回再调用该接口则结果可能不正确
    • 当对话结束后（包括 “对话结果” 接口返回的 return_code 字段中是 “end_chat” 或 “end_chat_by_redirect_to_human” 的情况），可以调用该接口获取详细的最终对话状态信息，见上面的 json 字段说明，特别是其中的【本轮对话后的信息项内容】、【对话记录】等信息，对于分析对话过程、优化对话树、以及转接人工时传递上下文信息都非常有用

接口使用说明​

  • 开始先执行一次【调用 “启动对话” 接口创建对话、再多次调用 “对话结果” 接口流式获取 AI 机器人的欢迎词、直至获取完】；然后再循环执行【调用 “对话交互” 或 “对话交互(语音)” 接口并传入用户的输入、再多次调用 “对话结果” 接口流式获取 AI 机器人的回复或问题、直至获取完】；直至对话结束
  • 不管是调用 “启动对话”、“对话交互”、“对话交互(语音)” 还是调用 “对话结果” 接口，返回的 return_content 都是本轮对话交互中 AI 回复或问题到目前为止的所有内容，而 return_content_delta 都是本次调用后产生的 AI 回复或问题文本的增量内容
  • 前面的“启动对话”、“对话交互”、“对话交互(语音)” 3 个接口中都有一个 sse 参数，如果此参数为 True 时：
    • 刚提到的 3 个接口都持续接收 HTTP SSE（的“data:”）数据包、然后解析该数据包并向上面所说一样处理 return_code、return_content 等字段即可
    • 上面的说明中要求（继续）调用 “对话结果” 的地方都替换为继续接收 HTTP SSE（的“data:”）数据包，不用再调用 “对话结果” 接口了
  • 建议通过 API 建立自动化测试机制
  • 具体参见下面两个代码示例

Python示例代码​

  • 点击下载 Python示例代码（HTTP SSE）（注意：下载后一定将文件名命名为 “demo_cmd_test_sse_for_docs.py”）
  • 点击下载 Python示例代码（HTTP 轮询）（注意：下载后一定将文件名命名为 “demo_cmd_test_polling_for_docs.py”）
  • 系统缺省的 user_name 和 access_key 是 firstuser / c6bfba3b9ae226482ecc7360c470b77acada28e5f544218c8e431a6ead75

对话管理类API​

“文件上传”接口​

  • 接口类型：HTTP POST
  • 接口地址：https://<your_server_url>/sapi/intentchat_file_upload
  • HTTP POST 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由60位字符或数字组成的字符串
    • file_type：可以是 “chattree” 对话树（.xmind/.py）、“knowledge” 知识库（.docx/.md/.zip）或 “codefile” 代码文件（.py）
    • [files]：上传的一个或多个文件，每个文件都是一个三元组：（文件名,文件内容,文件MIME类型），其中文件名需要进行 URL 编码（在 Python 用 urllib.parse.quote）
  • HTTP POST 返回值 如果 return_code：
    • 是 “error” 时表示出错，return_content 是出错的内容
    • 是 “uploaded” 时表示上传成功

“文件删除”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_file_delete
  • HTTP GET 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由 60 位字符或数字组成的字符串
    • file_type：可以是 “chattree” 对话树（.xmind/.py）、“knowledge” 知识库（.docx/.md/.zip）或 “codefile” 代码文件（.py）
    • file_name：需要删除的（一个）文件名
  • HTTP GET 返回值 如果 return_code：
    • 是 “error” 时表示出错，return_content 是出错的内容
    • 是 “deleted” 时表示删除成功

“文件刷新”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_file_refresh
  • HTTP GET 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由60位字符或数字组成的字符串
  • HTTP GET 返回值 如果 return_code：
    • 是 “error” 时表示出错，return_content 是出错的内容
    • 是 “refreshed” 时表示刷新成功

对话外呼类API​

“外呼”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_call_out
  • HTTP GET 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由 60 位字符或数字组成的字符串
    • start_tree：外呼时启动的对话树
    • infoitem_params：外呼启动对话树时传入的初始信息项的值，格式为 “{信息项1}=值|{\信息项2}=值|...”
    • number：外呼电话号码
  • HTTP GET 返回值 如果 return_code：
    • 是 “error” 时表示出错，return_content 是出错的内容
    • 是 “success” 时表示开始尝试呼叫，return_content 返回的呼叫序号，然后可以使用这个呼叫序号调用 “外呼状态” 接口获取外呼的状态（结果）

“外呼状态”接口​

  • 接口类型：HTTP GET
  • 接口地址：https://<your_server_url>/sapi/intentchat_call_out_get_state
  • HTTP GET 参数
    • user_name：用户名
    • access_key：API 访问密钥，一个由 60 位字符或数字组成的字符串
    • call_sn：外呼的呼叫序号（“外呼” 接口返回的）
  • HTTP GET 返回值 如果 return_code：
    • 是 “error” 时表示出错，return_content 是出错的内容
    • 是 “success” 时表示获取到了外呼状态，return_content 是外呼状态，如下：
      • “CAN_NOT_FIND_PHONE_ID”：内部错误，请联系系统管理员；
      • “WAITING”：表示系统忙，还在等待处理该外呼；
      • “CALLING”：表示正在外呼；
      • “CONNECTED”：表示已接通；
      • “DISCONNECTED”：表示已挂断(包括正常接通后挂断以及非后面原因的挂断)；
      • “LINE_OCCUPIED”：本机占线；
      • “REMOTE_BUSY”：对方占线；
      • “REMOTE_DECLINED”：对方拒接；
      • “TIMEOUT”：对方未接听；