@chatopera/sdk

Chatopera开发者平台：809987971， 点击链接加入群聊

Chatopera

---

Chatopera提供聊天机器人开发者平台，Chatopera SDK 用于在 Node.js 应用中集成聊天机器人服务。

安装

---

npm install @chatopera/sdk --save

SDK 使用方法

var Chatbot = require("@chatopera/sdk").Chatbot;

var chatbot = new Chatbot(*ClientId*, *Secret* [, ServiceProvider]);

提示: 对于私有部署，使用 ServiceProvider 定义服务地址

获取 ClientId 和 Secret

请点击这里。

• 创建聊天机器人

登录 Chatopera 控制台后，创建聊天机器人。

• 获得认证信息

在【设置】页面，获得 ClientId 和 Secret。

快速开始

通过示例程序快速开始使用 SDK。

API 接口

请先完成注册 Chatopera并创建一个聊天机器人。

说明：

1. 除创建机器人实例外，接口调用都是基于 async/await 方式。
2. 在非正常返回情况下，接口会抛出异常 Error(msg)。
3. 下面各接口的返回值，按正常情况下介绍。

高级封装接口

command接口是实例化一个 Chatbot 对象后，最核心的调用 Chatbot 各种服务的接口。

var resp = await chatbot.command(METHOD, PATH, PAYLOAD);

其中，METHOD 是调用 HTTPRequest 时的 method, 有效值包含 POST, PUT, DELETE, HEAD, GET；PATH 是 HTTPRequest 中的 URL path 参数，PAYLOAD 是 JSONArray 或 JSONObject 作为 HTTPRequest 的 Body。

获得聊天机器人实例

var Chatbot = require("@chatopera/sdk").Chatbot;
var chatbot = new Chatbot(*ClientId*, *Secret*);

获得聊天机器人详情

var detail = await chatbot.detail();

返回值

{
    "rc": 0,
    "data": {
        "name": "bar",
        "fallback": "我不明白您的意思。",
        "description": "",
        "welcome": "你好！我是机器人客服。",
        "primaryLanguage": "zh_CN"
    }
}

进行多轮对话

var reply = await chatbot.conversation("张三", "今天北京天气怎么样", 0.8, 0.6);

参数说明：

name	type	sample	description
userid	String	张三	必填，代表该用户的唯一标识
query	String	今天北京天气怎么样	必填，用户的文字消息
faq_best_reply	Number	0.8	选填，最佳回复的阀值，(0,1)区间，默认值 0.8
faq_sugg_reply	Number	0.6	选填，建议回复的阀值，(0, faq_best_reply) 区间，默认值 0.6

返回值

{
    "rc": 0,
    "data": {
        "state": "default",
        "createdAt": 1540796868205,
        "string": "白天天气晴好，早晚会感觉偏凉，午后舒适、宜人。",
        "topicName": "weather",
        "subReplies": [],
        "service": {
            "provider": "conversation"
        },
        "logic_is_fallback": false,
        "botName": "bar"
    }
}

说明：多轮对话的返回值的含义参考文档中心。

进行 FAQ 对话

var reply = await chatbot.faq("张三", "停效期间的保单是否能办理减保", 0.8, 0.6);

参数说明：

name	type	sample	description
userid	String	张三	必填，代表该用户的唯一标识
query	String	停效期间的保单是否能办理减保	必填，用户的文字消息
faq_best_reply	Number	0.8	选填，最佳回复的阀值，(0,1)区间，默认值 0.8
faq_sugg_reply	Number	0.6	选填，建议回复的阀值，(0, faq_best_reply) 区间，默认值 0.6

返回值

{
    "rc": 0,
    "data": [
        {
            "id": "AWa-Ogcaf3EIFA_CgZ3o",
            "score": 0.747,
            "post": " 停效期间的保单是否能办理减保？",
            "replies": {"rtype": "plain", "content": " 停效期间的保单可以办理减保""}
        },
        ...
    ]
}

说明：返回值为数组，id代表问答对 ID，score是相似度分数，reply是回复。

在含有多个元素时按score降序排列，score的分数在[0,1]之间，越接近 1 越相似。

进行意图识别对话

• 创建 session

var session = await chatbot.intentSession(uid, channel);
# 得到sessionID: session.id

其中，uid代表用户的唯一表示，channel代表用户访问的渠道。这两个字段是用户自定义字符串。

• 请求意图识别对话

var reply = await chatbot.intentChat(sessionId, uid, textMessage);

• 获得 session 详情

var session = await chatbot.intentSessionDetail(sessionId)

在意图识别对话中，session 记录着这次会话的信息，包括用户意图、槽位参数等。

查看用户列表

let users = await chatbot.users();

返回值

{
    "rc": 0,
    "data": [
        {
            "userId": "张三",
            "lasttime": "2018-10-29T07:07:47.812Z",
            "created": "2018-10-29T05:02:13.084Z"
        },
        ...
    ]
}

说明: 按最后对话时间将序排列。

查看用户聊天历史

let chats = await chatbot.chats("张三");

返回值

{
    "rc": 0,
    "data": [
        {
            "userId": "张三",
            "created": "2018-10-29T05:29:41.833Z",
            "textMessage": "白天天气晴好，早晚会感觉偏凉，午后舒适、宜人。",
            "direction": "outbound",
            "service": "conversation",
            "confidence": 1
        }
    ]
}

说明：按照每条消息的生成时间升序排列。

屏蔽用户

以该用户 ID 发送给聊天机器人信息时，将不能得到回复，此时回复内容参考文档。

await chatbot.mute("张三");

返回值为 JSONObject

{"rc":0,"data":{}}

rc 等于 0 代表接口调用成功。

取消屏蔽

将一个用户取消屏蔽。

await chatbot.ummute("张三");

返回值为 JSONObject

{"rc":0,"data":{}}

rc 等于 0 代表接口调用成功。

查看用户是否被屏蔽

查看一个用户是否被这个机器人屏蔽了。

let result = await chatbot.ismute("张三");

返回值为 JSONObject

{"rc":0,"data":{"mute":false}}

关于各接口返回值的更多描述参考开发者平台文档。

技能接口

技能是 Chatopera 云服务中，预置的机器人的对话能力，不需要用户管理知识库、脚本等，开箱即用。每项技能是单独的接口。

心理咨询

心理咨询服务是 Chatopera 云服务中专门为心理咨询平台和心理咨询师等行业用户，打造的面向心理健康、心理支持的对话服务。此处，仅介绍 API 接口，详细介绍参考文档 https://docs.chatopera.com/products/psych-assistant/index.html

聊天接口

chatbot.psychChat(channel, channelId, userId, textMessage)

实现多轮对话。

  const chatbot = new Chatbot(clientId, clientSecret);
  let channel = "test";
  let channelId = "nodejs";
  let userId = "uid001";
  let textMessage = "确定自己是否有抑郁倾向，想要知道自己当下该怎么办";
  let resp = await chatbot.psychChat(channel, channelId, userId, textMessage);
  debug("resp: %s", JSON.stringify(resp, null, " "));

参数说明：

name	type	sample	description
channel	string	"test"	用户自定义渠道，使用字母和数字，字母开头
channelId	string	"nodejs"	用户自定义渠道标识，使用字母和数字，字母开头
userId	string	"uid001"	访问者唯一标识，使用字母和数字，字母开头
textMessage	string	"你好"	对话文本内容

返回值： Promise

查询接口

chatbot.psychSearch(query [,threshold])

查询知识库。

  const chatbot = new Chatbot(clientId, clientSecret);
  let query = "确定自己是否有抑郁倾向，想要知道自己当下该怎么办";
  let threshold = 0.2;
  let resp = await chatbot.psychSearch(query, threshold);
  debug("resp: %s", JSON.stringify(resp, null, " "));

参数说明：

name	type	sample	description
query	string	"确定自己是否有抑郁倾向，想要知道自己当下该怎么办"	查询条件
threshold	float	0.2	匹配度，可适当调整，默认 0.2

返回值： Promise

关于返回值具体内容，详细介绍，参考https://docs.chatopera.com/products/psych-assistant/index.html。

CLI 使用方法

Chatopera Node.js SDK 包括一些常用的命令，辅助开发者实现对话机器人。

connect

在命令行终端连接 Bot 并进行对话。

Usage: connect [options]

Options:
  -c, --clientid <value>      ClientId of the bot, *required.
  -u, --username <value>      Username to chat with bot, *required.
  -s, --clientsecret [value]  Client Secret of the bot, optional, default null
  -p, --provider [value]      Chatopera Superbrain Instance URL, optional, default https://bot.chatopera.com
  -h, --help                  output usage information

其中，Client ID和Client Secret来自于平台，在独立使用智能问答引擎时，可以省略Client Secret。username代表用户名，是一个不含空格或特殊符号的字符串，每个用户的唯一标识，provider是智能问答引擎地址，默认为 Chatopera 机器人平台。

示例：

bot connect -c 5cd29bf7xxx -s 0d8e43cc4de22e9e2cb89f69xxx -u zhangsan

deploy

在命令行终端发布 botarchive 文件到多轮对话中。

Usage: deploy [options]

Options:
  -c, --clientid <value>      ClientId of the bot, *required.
  -b, --botarchive <value>    Conversation Bundle, *required.
  -s, --clientsecret [value]  Client Secret of the bot, optional, default null.
  -p, --provider [value]      Chatopera Superbrain Instance URL, optional, default https://bot.chatopera.com
  -h, --help                  output usage information

其中botarchive为机器人的文件目录和xx.c66文件，支持相对路径或绝对路径。

标准目录结构:

botarchive
├── index.json
├── plugin.js
└── zh_CN.greeting.ms

其中，index.json描述机器人多轮对话属性：

{
    "name": "大白",
    "primaryLanguage": "zh_CN",
    "version": "0.5.0",
    "conversations": [
        {
            "name": "greeting",
            "enabled": true
        }
    ],
    "config": // 环境变量Key-Value
    {
    }
}

plugin.js是函数，参考说明文档。

获得帮助

bot --help

Contribute

打印调试日志

export DEBUG=chatopera*
cp sample.env .env # edit .env
npm run test

license

Apache 2.0

Copyright 2017-2018, 北京华夏春松科技有限公司. All rights reserved. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Changelog

2.0.0

• 提供 Chatbot#command 接口，对 RestAPI 进一步封装，提高灵活性
• 将 Chatbot 作为成员类 exports 出来
• 增加 DeprecationWarning，以后统一使用 Chatbot#command 接口
• queryString 中增加 sdklang=nodejs 参数
• 调整接口的返回值为包含标准rc, data, msg, error, status的字段。