[API]Chat

根据机器人实例ID与其进行会话。

请求参数

参数名

类型

是否必填

描述

AccessKeyId

String

机器人详情->会话接口,页面显示的AccessKey

Version

String

API 版本号,为日期形式:YYYY-MM-DD,本版本对应为2017-10-11。

Action

String

接口唯一标识

InstanceId

String

机器人实例ID。登录云小蜜控制台,机器人详情->会话接口,查看机器人实例信息,可获得该实例ID。

Utterance

String

机器人访问者的输入

SessionId

String

会话ID,用于标识一个访问者的会话和保持上下文信息。对于一个新的访问者,首次调用Chat接口时无需传递此字段,机器人会开启一个会话,并在Chat接口的响应中返回该会话的SessionId。对于该访问者的后续轮次的会话,调用Chat接口时传递当前会话的SessionId,机器人即可基于SessionId继续该轮次会话。长度限制是64个字符

KnowledgeId

String

知识库中知识标题的ID。若指定此ID,那么机器人会直接返回指定知识标题的答案

IntentName

String

对话流中意图名称。

若指定此名称,机器人会直接进入此意图做问答

SenderId

String

访问者ID。用于识别当前会话中的用户

SenderNick

String

当前会话中访问的昵称

Perspective

List

视角编码,用于调用同一知识标题下不同视角的答案。在拼装请求参数时,需要以Perspective={视角编码}的格式传递参数。如:&Perspective=["FZJBY3raWr"]。使用SDK时以SDK中定义的参数为准。

VendorParam

JSON

是一个json格式的用户自定义参数集,可以传入用户自定义的参数到对话工厂,在函数脚本的main函数中,可以在event.environment.VENDOR_PARAM中取到这些值,详细参见对话工厂使用手册,例如:{"phone":123456789}

IntentName 系统内置名称及描述

IntentName

对应事件

TIMEOUT

触发对话工厂超时话术

GUIDEPOST

触发对话工厂异步服务,详见异步服务使用手册

返回参数

名称

类型

描述

MessageId

String

本条会话应答消息的ID

SessionId

String

本次会话的ID

Messages

Array of Message

消息的列表

Associate

Array of Associate

推荐信息

Message

字段名

类型

描述

AnswerType

String

本条消息的类型,枚举值如下:

枚举值如下:

Text:文本,

Recommend:知识库知识推荐,

Knowledge:知识库知识直出,

AnswerSource

String

当AnswerType为Recommend时,此字段表示推荐的答案来源,枚举值如下:

TABLEQA:表格问答

KBQA:图谱问答

KNOWLEDGE:知识问答

Title

String

当AnswerType为Recommend时,此字段表示推荐或者反问的话术

Text

Text

当AnswerType为Text时,此字段包含机器人返回的Text对象

Knowledge

Knowledge

当AnswerType为Knowledge时,此字段包含机器人返回的Knowledge对象

Recommends

Array of Recommend

当AnswerType为Recommend时,此字段包含机器人返回的Recommend的列表

CardList

Array of JSON

当AnswerType为CardAnswer时,此字段包含机器人返回的Card的列表

Associate

名称

类型

描述

Title

String

推荐问题

Text

字段名

类型

描述

Content

String

文本消息的内容

AnswerSource

String

区分答案类型。

ChitChat:系统预置闲聊;USER_DEFINED_CHAT:自定义闲聊;

BotFramework:对话工厂;NO_ANSWER:无答案;

MACHINE_READ:机器阅读;CardAnswer:卡片答案;

SENSITIVE_WORD: 全局敏感词

HitStatement

String

命中语句

UserDefinedChatTitle

String

当AnswerSource为

USER_DEFINED_CHAT

时,此字段返回自定义语聊主题名称

ArticleTitle

String

当AnswerSource为MACHINE_READ时,此字段返回命中文章标题

DialogName

String

当AnswerSource为BotFramework时,此字段返回对话单元名称

IntentName

String

当AnswerSource为BotFramework时,此字段返回意图名称

Slots

Array of Entity

当AnswerSource为BotFramework时,此字段返回专有名词列表

NodeId

String

当AnswerSource为BotFramework时,此字段返回节点Id

NodeName

String

当AnswerSource为BotFramework时,此字段返回节点名称

ExternalFlags

Map<String, Object>

当AnswerSource为BotFramework时,此字段返回透传参数

Ext

Map<String, Object>

此字段返回透传参数

ContentType

String

纯文本/富文本答案的标示

枚举值如下:

PLAIN_TEXT:纯本文

RICH_TEXT: 富文本

ExternalFlags 常见字段释义

参数名称

参数类型

对应事件

Interruptible

Boolean

透传给外呼平台,机器人播报话术是否可被打断

HangUp

Boolean

透传给外呼平台,机器人播报话术后是否主动挂断

Entity

字段名

类型

描述

Name

String

名称

Value

String

具体值

Origin

String

原始值

IsHit

Boolean

是否命中

Knowledge

字段名

类型

描述

Id

String

命中问题在知识库中的ID

Title

String

命中问题的标题

Summary

String

命中问题的简介

Content

String

命中问题的内容

AnswerSource

String

区分答案类型。

KnowledgeBase:知识库条;

HitStatement

String

命中语句

Category

String

知识类目

KeyWords

List

核心词

RelatedKnowledges

List

关联知识列表

ContentType

String

纯文本/富文本答案的标示

枚举值如下:

PLAIN_TEXT:纯本文

RICH_TEXT: 富文本

RelatedKnowledge

字段名

类型

描述

KnowledgeId

String

知识关联知识的ID

Title

String

知识的关联知识的标题

Recommend

字段名

类型

描述

KnowledgeId

String

推荐的知识id

Title

String

推荐内容,可能是

图谱问答的实体、

知识问答的知识标题、

表格问答的列值

Score

Double

推荐内容的分数,当AnswerSource为KNOWLEDGE时,此字段有值

Ext

AnswerSource=BotFramework时:

字段名

类型

描述

DIALOG_ID

String

对话流ID

DIALOG_NAME

String

对话流名称

INTENT_NAME

String

命中的意图名称

INTENT_SOURCE

String

意图识别命中的来源方法,包括:Simialrity - 相似度匹配方法,Lgf - LGF语法匹配方法,Classify - 有监督模型方法

INTENT_DETAIL

String

意图命中的方式细节,主要在INTENT_SOURCE=Similarity或者Lgf的时候有用,当为Similarity时,这个字段的值就是匹配的意图话术,当为Lgf时,这个字段的值就是匹配的Lgf语法

IS_SESSION_FINISHED

Boolean

会话是否完结标志

DsScore

String

命中对话流的分数

IntentName

String

与INTENT_NAME相同

TASK_ID

String

异步服务返回的任务ID

错误码

错误代码

描述

Http状态码

语义

InvalidInstanceId.NotFound

404

指定的InstanceId不存在

SessionBusy

ErrorMessage字段包含最大session数、当前session数:{"maxSessions":5,"currentSessions":5,"tenantId":7202}

400

会话session数达到上限

InvalidParameter

400

参数不合法

Robot not publish

400

机器人没有发布

InternalError

500

内部错误

You are not authorized to do this operation.


403

无权限

InstanceFreezing


403

实例冻结

PerspectiveError


400

视角传递错误

Third party interface error


499

第三方接口出错

错误示例

{
    "RequestId":"6efc514c-8bc1-4951-8a6e-2c0850450f58",
    "HttpStatus":403,
    "ErrorMessage":"You are not authorized to do this operation.",
    "ErrorCode":"You are not authorized to do this operation."
}
特别说明
  • 请在完成会话后调用CloseSession接口主动关闭会话session,在线问答场景浏览器尽最大努力捕捉问答窗口关闭事件进行关闭,导航外呼场景可在通话结束时调用;

  • 如果不调用CloseSession接口主动关闭,会话session会在5分钟后自动关闭。

示例

请求参数

http://chatbot.cn-shanghai.aliyuncs.com:8081/?Action=Chat&InstanceId=1492&Utterance=%E4%B9%B0%E6%89%8B%E6%9C%BA&Version=2017-10-11&AccessKeyId=AFD672296A1FC407

响应报文:

FAQ问答-直出
{
  "QuerySegList": [
    "测试",
    "富文",
    "本"
  ],
  "Messages": [
    {
      "Knowledge": {
        "Score": 100.0,
        "Category": "第一个类目",
        "ContentType": "RICH_TEXT",
        "AnswerSource": "KnowledgeBase",
        "Content": "<p>富文本答案啊</p>",
        "Summary": "富文本答案啊",
        "Title": "测试富文本",
        "Id": "4549"
      },
      "Type": "Knowledge",
      "AnswerType": "Knowledge"
    }
  ],
  "RequestId": "1b8b19de-7e6d-4e45-b7f1-9daca21af8b0",
  "HttpStatus": 200,
  "SessionId": "1234",
  "MessageId": "1b8b19de-7e6d-4e45-b7f1-9daca21af8b0"
}
FAQ问答-推荐
{
  "QuerySegList": [
    "文本"
  ],
  "Messages": [
    {
      "AnswerSource": "KNOWLEDGE",
      "Recommends": [
        {
          "Score": 46.0,
          "Title": "测试纯文本",
          "KnowledgeId": "4548"
        }
      ],
      "Type": "Recommend",
      "AnswerType": "Recommend"
    }
  ],
  "RequestId": "5af5d5f9-76b1-45e9-8003-fcd07ab9a5e4",
  "HttpStatus": 200,
  "SessionId": "1234",
  "MessageId": "5af5d5f9-76b1-45e9-8003-fcd07ab9a5e4"
}
对话工厂
{
  "QuerySegList": [
    "查",
    "天气"
  ],
  "Messages": [
    {
      "Text": {
        "Ext": {
          "MATCHED_ENTRY_NAME": "intentWithout_city",
          "MATCHED_INTENT_SOURCE": "",
          "INTENT_ID": 724414,
          "BOT_ANSWER_SOURCE": "Lgf",
          "IntentName": "查天气意图",
          "INTENT_DETAIL": "[我想|我要]查天气",
          "LGF_EXPRESSION": "[我想|我要]查天气",
          "IS_SESSION_FINISHED": false,
          "DsScore": 100.0,
          "DIALOG_ID": "299034",
          "FINISH_LABEL": false,
          "MODULE_START": false,
          "INTENT_NAME": "查天气意图",
          "INTENT_SOURCE": "Lgf",
          "DIALOG_NAME": "示例_查天气"
        },
        "ContentType": "PLAIN_TEXT",
        "NodeName": "示例_查天气.查天气填槽.__city",
        "AnswerSource": "BotFramework",
        "Slots": [
          {
            "Origin": "",
            "Hit": false,
            "Value": "",
            "Name": "查天气意图.city"
          }
        ],
        "Score": 100.0,
        "DialogName": "示例_查天气",
        "IntentName": "查天气意图",
        "Content": "请问您要查哪里的天气?",
        "NodeId": "1410-c7a72a78.__city",
        "ExternalFlags": {
          
        }
      },
      "Type": "Text",
      "AnswerType": "Text"
    }
  ],
  "RequestId": "dc6757ef-9d03-4255-92ec-d262752a88ed",
  "HttpStatus": 200,
  "SessionId": "1234",
  "MessageId": "dc6757ef-9d03-4255-92ec-d262752a88ed"
}
闲聊-系统语聊
{
  "QuerySegList": [
    "你好"
  ],
  "Messages": [
    {
      "Text": {
        "Ext": {
          
        },
        "ContentType": "PLAIN_TEXT",
        "UserDefinedChatTitle": "其他",
        "AnswerSource": "ChitChat",
        "HitStatement": "你好",
        "Content": "哔~哔~哔~,我来了"
      },
      "Type": "Text",
      "AnswerType": "Text"
    }
  ],
  "RequestId": "8f267d8c-c118-4d6a-9ba1-2a5bdc720fed",
  "HttpStatus": 200,
  "SessionId": "1234",
  "MessageId": "8f267d8c-c118-4d6a-9ba1-2a5bdc720fed"
}

闲聊-自定义语聊

{
  "QuerySegList": [
    "谢谢你"
  ],
  "Messages": [
    {
      "Text": {
        "Ext": {
          
        },
        "ContentType": "PLAIN_TEXT",
        "UserDefinedChatTitle": "感谢",
        "AnswerSource": "USER_DEFINED_CHAT",
        "HitStatement": "谢谢你",
        "Content": "能为您服务是我的荣幸~"
      },
      "Type": "Text",
      "AnswerType": "Text"
    }
  ],
  "RequestId": "56d89830-09fe-4606-afb2-240199509503",
  "HttpStatus": 200,
  "SessionId": "1234",
  "MessageId": "56d89830-09fe-4606-afb2-240199509503"
}
无答案
{
  "QuerySegList": [
    "公积金",
    "贷款"
  ],
  "Messages": [
    {
      "Text": {
        "ContentType": "PLAIN_TEXT",
        "AnswerSource": "NO_ANSWER",
        "Content": "我还没有学会这个问题,已经记录会尽快学习为您解答,请尝试询问我其他问题"
      },
      "Type": "Text",
      "AnswerType": "Text"
    }
  ],
  "RequestId": "1ad8733a-7180-4e3b-a969-96f47d774256",
  "HttpStatus": 200,
  "SessionId": "1234",
  "MessageId": "1ad8733a-7180-4e3b-a969-96f47d774256"
}