Kore.ai BotKit SDK는 봇을 더 잘 제어하고 사용자 경험을 개선하는 데 사용할 수 있는 함수를 제공합니다.
BotKit SDK는 다음 함수를 지원합니다.
sdk.sendUserMessage
이 함수는 봇 사용자에게 메시지를 보냅니다.
사용법
on_bot_message 이벤트 콜백 내부에서 사용됩니다. on_bot_message 이벤트는 봇이 사용자에게 응답을 보낼 때 호출됩니다. SDK에서, message와 같은 페이로드 데이터는 수정한 후 봇 플랫폼으로 보낼 수 있습니다.
구문
sdk.sendUserMessage(payload, callback)
매개변수:
payload– 다음과 같은 JSON 응답 페이로드.{ "message":"Spell-corrected message sent by bot to the user", "originalMessage":"Original message sent by bot to the user", "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }위의 메시지 페이로드는 사용자 언어가 감지되고 철자 수정이 완료된 경우입니다. 사용자 언어가 감지되지 않는 경우, 메시지 구조는 다음과 같습니다
{ "message":"Original message sent by bot to the user", "originalMessage":"Original message sent by bot to the user", "languageInfo": { "currentLanguage": "current user language", "detectedLanguages": [ "language detected 1", "language detected 2" ], "spellCorrectedInput": [ "language 1": "spell correction in language 1", "language 2": "spell correction in language 2" ] } }callback– 업데이트된 메시지와 컨텍스트를 봇 플랫폼으로 다시 전송하는 데 사용되는 이벤트 완료 시 호출하는 함수.
예시
다음 코드 조각은 사용자에게 오류를 반환하는 sdk.sendUserMessage 함수의 예시를 보여줍니다.
return sdk.sendUserMessage(payload, function(err){
if(err)
console.log("err", err);
다음 코드 예시에서는, 사용자가 라이브 상담사로 전환될 때 사용자에게 초기 메시지가 표시됩니다.
formdata.welcome_message = "";
var visitorId = _.get(payload, 'channel.channelInfos.from');
if (!visitorId) {
visitorId = _.get(payload, 'channel.from');
}
visitorId = payload.context.session.UserContext._id;
userDataMap[visitorId] = payload;
data.message = "An Agent will be assigned to you shortly!!!";
sdk.sendUserMessage(payload, callback);
다음 코드 예시에서는, sdk.sendUserMessage 함수와 함께 사용자에게 보내는 메시지는 통화 변환을 위해 사용자 선택에 기반합니다. isTemplate 매개변수는 사용자 정의 형식 또는 기본 메시지 형식 중 어느 것을 사용할지 여부를 결정합니다.
on_user_message : function(requestId, payload, callback) {
message = payload.message.toLowerCase();console.log("MESSAGE",payload.message);
//payload .context.session.BotContext.currency = "koko";
if ( message == "Yes" || message == "yes")
{
var overrideMessagePayload = {
body : " Enter the currency code for which the amount will be converted",
isTemplate :false
};
data.overrideMessagePayload = overrideMessagePayload;
currCode = true;
return sdk.sendUserMessage(payload);
}
else if ( message == "No" || message == "no" )
{
var overrideMessagePayload = {
body : "Ok, Enter the country name so that I can fetch it on your behalf",
isTemplate :false
};
payload.overrideMessagePayload = overrideMessagePayload;
countryname = true;
return sdk.sendUserMessage(payload);
플랫폼 버전 8.0 릴리스 후, User Meta Tags, Message Meta Tags 및 Session Meta Tags를 추가할 수 있습니다. 다음은 필요한 페이로드에 대한 구문입니다.
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.sendBotMessage
이 함수는 봇에게 메시지를 보냅니다.
사용법
on_user_message 이벤트 콜백 내부에서 사용됩니다. on_user_message 이벤트는 사용자가 봇에게 메시지를 보낼 때 호출됩니다. SDK에서, message와 같은 페이로드 데이터는 수정한 후 봇 플랫폼으로 보낼 수 있습니다.
사용자 메시지에 대해 유효성 검사가 수행됩니다. 메시지는 3,000자를 초과할 수 없으며 각 단어는 1,200자를 초과할 수 없습니다.
구문:
sdk.sendBotMessage(payload, callback)
매개변수:
payload– 다음과 같은 JSON 응답 페이로드.{ "message":"Message sent by the user", "channel":"Channel name", "context": <context object> }callback– 업데이트된 메시지와 컨텍스트를 봇 플랫폼으로 다시 전송하는 데 사용되는 이벤트 완료 시 호출하는 함수.
예시
다음 코드 조각은 봇에게 사용자 응답을 보냅니다.
{
"message":"Message sent by the user",
"channel":"Channel name",
"context": <context object>
}
이on_user_message 함수에서, 메시지는 사용자에게 직접 반환되며, 라이브 상담사로 전환되지 않으면, 봇으로 보냅니다.
on_user_message: function(requestId, payload, callback) {
sdk.sendBotMessage(payload, callback);
},
플랫폼 버전 8.0 릴리스 후, User Meta Tags, Message Meta Tags 및 Session Meta Tags를 추가할 수 있습니다. 다음은 필요한 페이로드에 대한 구문입니다.
on_user_message: function(requestId, payload, callback) {
if (payload.message === "Hi") {
payload.message = "Hello";
//Sends back 'Hello' to user.
return sdk.sendUserMessage(payload, callback);
} else if (!payload.agent_transfer) {
//Forward the message to bot
return sdk.sendBotMessage(payload, callback);
} else {
payload.message = "Agent Message";
return sdk.sendUserMessage(payload, callback);
}
};
sdk.AsyncResponse
이 함수는 봇 플랫폼으로 보낼 비동기식 응답을 준비합니다.
사용법
대화 작업 실행 흐름이 webhook 노드에 도달하는 경우, 봇 플랫폼은 SDK에 대한 on_webhook 이벤트 호출을 수행합니다. on_webhook 이벤트 호출은 두 가지 유형의 응답을 지원합니다.
- 동기식 응답 – 비즈니스 로직 실행이 허용 가능한 시간 내에 완료될 수 있는 경우, SDK는
callback(null, payload)함수를 사용하여 동기적으로 응답할 수 있습니다. - 비동기식 응답 – 비즈니스 로직 실행에 더 많은 시간이 필요한 경우, SDK는
callback(null, new sdk.AsyncResponse())함수를 호출하고 HTTP 코드 202를 봇 플랫폼으로 전송하여 비동기식 응답을 봇 플랫폼으로 보낼 수 있습니다. 응답이 준비되면, SDK는sdk.respondToHook(payload)함수를 호출할 수 있습니다.
구문:
sdk.AsyncResponse() callback(null, new sdk.AsyncResponse())
매개변수:
없음.
예시
이 on_webhook 함수의 예시에서는, 봇이 사용자가 선택한 택시의 예약을 비동기식으로 대기합니다.
on_webhook : function(requestId, payload, componentName, callback) {
var context = payload.context;
if (componentName === 'FindNearbyCabs') {
findCabs()
.then(function(cabList) {
context.cabList = cabList;
callback(null, data);
});
} else if (componentName === 'BookTheCab') {
sdk.saveData(requestId, payload)
.then(function() {
bookTheCab(requestId, context.entities.selectedCab.id, context.session.UserSession.location, context.entities.whereTo);
callback(null, new sdk.AsyncResponse());
});
}
}
sdk.respondToHook
이 함수는 봇 플랫폼으로 webhook 응답을 보냅니다.
사용법
대화 작업 실행 흐름이 webhook 노드에 도달하는 경우, 봇 플랫폼은 SDK에 대한 on_webhook 이벤트 호출을 수행합니다. on_webhook 이벤트 호출은 두 가지 유형의 응답을 지원합니다.
- 동기식 응답 – 비즈니스 로직 실행이 허용 가능한 시간 내에 완료될 수 있는 경우, SDK는
callback(null, payload)함수를 사용하여 동기적으로 응답할 수 있습니다. - 비동기식 응답 – 비즈니스 로직 실행에 더 많은 시간이 필요한 경우, SDK는
callback(null, new sdk.AsyncResponse())함수를 호출하고 HTTP 코드 202를 봇 플랫폼으로 전송하여 비동기식 응답을 봇 플랫폼으로 보낼 수 있습니다. 응답이 준비되면, SDK는sdk.respondToHook(payload)함수를 호출할 수 있습니다.
구문:
sdk.respondToHook(payload)
매개변수:
payload– 다음과 같은 JSON 응답 페이로드.{ "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }
예시
다음 코드 조각에서는, 택시 예약이 실패하면, 이벤트가 동기식으로 처리됩니다. 반대로, 택시 예약은 webhook을 통해 비동기식으로 처리됩니다.
function onBookingFailure(requestId) {
sdk.getSavedData(requestId)
.then(function(payload) {
payload.context.successful = false;
sdk.respondToHook(payload);
});
}
//call cabBookingService with the requestId. This service is expected to respond asynchronously.
//'requestId' must be passed along all asynchronous flows, to allow the BotKit to respond
// back to the hook once the async process is completed.
function bookTheCab(requestId, cabId, userLoc, destination) {
cabBookingService(requestId, cabId, userLoc, destination, {
on_success: onBookingSuccess,
on_failure: onBookingFailure
});
}
sdk.registerBot
이 함수는 봇을 등록하고 실행 시 콜백 이벤트를 사용할 수 있도록 합니다.
사용법
BotKit SDK는 각 봇에 대해 하나의 Node.js 파일을 생성하도록 설계되었습니다. 해당 봇의 모든 콜백은 Node.js 파일에서 유지 관리됩니다. 봇을 등록하려면, 다음 변수와 함수를 다음과 같이 내보내야 합니다.
module.exports = {
botId : “xxxxx”,
botName : ““xxxxx”,
on_user_message : function(requestId, data, callback) {
//code goes here
},
on_bot_message : function(requestId, data, componentName, callback) {
//code goes here
},
on_webhook : function(requestId, data, componentName, callback) {
//code goes here
},
}
구문:
봇을 등록하려면, 다음을 호출합니다
sdk.registerBot(require('./<Bot Name>.js'));
매개변수:
- 등록할 봇의 Node.js 파일
예시
다음 코드 예시에서는 botId 및 botName를 사용한 봇의 등록을 보여줍니다.
module.exports = {
botId : botId,
botName : botName,
on_user_message : function(requestId, payload, callback) {
debug('on_user_message');
onUserMessage(requestId, payload, callback);
},
on_bot_message : function(requestId, payload, callback) {
debug('on_bot_message');
onBotMessage(requestId, payload, callback);
},
on_agent_transfer : function(requestId, payload, callback) { console.log("on agent transfer event");
debug('on_webhook');
onAgentTransfer(requestId, payload, callback);
},
gethistory: gethistory
};
sdk.saveData
이 함수는 Redis 인메모리 데이터 구조 저장소에 데이터를 저장합니다.
사용법
on_webhook 이벤트 호출에 비동기식으로 응답하는 경우, requestId를 사용하여 Redis 저장소에 페이로드를 저장할 수 있습니다. 비즈니스 로직 실행을 완료한 후, webhook 응답을 준비하는 동안 sdk.getSavedData(requestId)function 함수를 사용하여 데이터를 읽을 수 있습니다.
구문:
sdk.saveData(requestId, payload)
매개변수:
requestId– 비동기식on_webhook이벤트 호출의requestId.payload– 다음과 같은 JSON 응답 페이로드.{ "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }
예시
이 on_webhook 이벤트에서는, 택시 예약 요청이 Redis 스토어에 저장되고 예약의 비동기식 처리가 시작됩니다.
on_webhook : function(requestId, payload, componentId, callback) {
var context = data.context;
if (componentId === 'FindNearbyCabs') {
findCabs()
.then(function(cabList) {
context.cabList = cabList;
callback(null, payload);
});
} else if (componentName === 'BookTheCab') {
sdk.saveData(requestId, payload)
.then(function() {
//Assuming the cab booking was successful. A mock service to book the cab can be called here.
payload.successful = 'true';
payload.bookedCab = context.entities.selectedCab || {};
callback(null, payload);
});
}
}
sdk.getSavedData
이 함수는 Redis 인메모리 데이터 구조 저장소에서 데이터를 읽습니다.
사용법
on_webhook 이벤트 호출에 비동기식으로 응답하는 경우, requestId를 사용하여 Redis 저장소에 페이로드를 저장할 수 있습니다. 비즈니스 로직 실행을 완료한 후, webhook 응답을 준비하는 동안 sdk.getSavedData(requestId)function 함수를 사용하여 데이터를 읽을 수 있습니다.
구문:
sdk.getSavedData(requestId, payload)
매개변수:
requestId– 비동기식on_webhook이벤트 호출의requestId.payload– 다음과 같은 JSON 응답 페이로드.{ "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }
예시
이 코드 예시에서, sdk.getSavedData 함수는 선택한 택시와 예약 정보를 반환하는 데 사용되거나, 비동기식 예약 webhook 이벤트가 실패하는 경우, 선택한 예약에 대한 실패 메시지를 사용자에게 보냅니다.
/*/
* Responds to the webhook asynchronously with the success flag.
*/
function onBookingSuccess(requestId) {
sdk.getSavedData(requestId)
.then(function(payload) {
payload.context.bookedCab = payload.entities.selectedCab;
payload.context.successful = true;
sdk.respondToHook(payload);
});
}
function onBookingFailure(requestId) {
sdk.getSavedData(requestId)
.then(function(payload) {
payload.context.successful = false;
sdk.respondToHook(payload);
});
}
sdk.getMessages
이 함수는 봇과 사용자 간에 이전 대화 기록을 가져올 때 사용됩니다. 공용 API 대화 기록(대화 기록 API는 여기를 참조하세요)
사용법
봇 과 사용자 간에 대화형 메시지를 시간 역순으로 가져옵니다. 이 API는 페이징을 지원합니다. 오프셋/건너뛰기 및 한 번에 특정 수의 메시지를 가져올 수 있도록 제한을 제공할 수 있습니다.
구문:
sdk.getMessages(requestData, callback)
매개변수:
requestData다음과 같습니다.requestData.baseUrl + '/getMessages?' + "skip=" + offset + "&limit=" + limit + "&userId=" + userId+"&channelType"=channel-type
위치
stream_id– 봇 빌더의 구성 설정 페이지에서 접근할 수 있는 봇 IDuser_id– 대화 기록에 접근할 수 있는 사용자 IDskip– 건너뛸 메시지 수입니다.limit– 각 페이지에 표시할 메시지 수.channelType– 옵션, 대화가 호스팅 된 채널.
callback– 메시지 기록을 봇 플랫폼으로 다시 전송하는 데 사용되는 이벤트 완료 시 호출하는 함수.
예
//this example is from the LiveChat.js
//where the gethistory() function uses getMessage() to extract the messages
var userId = req.query.userId;
var data = userDataMap[userId];
if(data) {
data.limit = 100;
return sdk.getMessages(data, function(err, resp){
if(err){
res.status(400);
return res.json(err);
}
var messages = resp.messages;
res.status(200);
return res.json(messages);
});
sdk.clearAgentSession
이 함수는 상담사 세션을 지우고 봇과의 대화를 다시 설정하는 데 사용됩니다.
사용법
상담사 전환 시나리오에서, 상담사가 사용자와의 대화를 종료하면, 타사 공급자로부터 chat_closed 이벤트가 실행됩니다. 이러한 경우, 이 함수는 봇과 대화를 다시 설정하기 위해 호출됩니다
구문:
sdk.clearAgentSession(requestData, callback)
매개변수:
requestData다음과 같습니다.requestData.baseUrl+ '/clearAgentSession/' + requestData.requestId
위치
requestId– 세션 id
callback– 이벤트 완료 시 호출할 함수.
예
//this example is from the LiveChat.js
//where the function is invoked to clear agent session when the chat is closed by the user
if (event.type==="chat_closed"){
console.log('chat_closed');
delete userResponseDataMap[visitorId];
delete _map[visitorId];
sdk.clearAgentSession(data);
}
플랫폼 버전 8.0 릴리스 후, User Meta Tags, Message Meta Tags 및 Session Meta Tags를 추가할 수 있습니다. 다음은 필요한 페이로드에 대한 구문입니다.
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.startAgentSession
이 함수는 상담사 세션이 시작되었음을 플랫폼에 알리는 데 사용됩니다.
사용법
이 함수는 상담사 전환이 시작되고 상담사 전환이 진행 중임을 봇에게 알리려는 경우에 사용됩니다. 다음으로, 예를 들어, onMessages()에서 BotKit이 받은 데이터 개체는 상담사 세션을 true로 가집니다. 또한, sdk.clearAgentSession이 BotKit에서 호출되면, 플랫폼은 상담사 세션이 완료되었음을 알리고 BotKit이 받은 데이터 개체는 상담사 세션을 false로 설정합니다.
구문:
sdk.startAgentSession(requestData, callback)
매개변수:
requestData다음과 같습니다.requestData.baseUrl + '/startAgentSession/' + requestData.requestId
위치
requestId– 세션 id
callback– 이벤트 완료 시 호출할 함수.
예
//The following function call is used in the LiveChat.js for connectToAgent() function
//Invoking the startAgentSession before invoking the initChat function will ensure that
// the Bot is aware of the Agent transfer in progress
function connectToAgent(requestId, data, cb){
var formdata = {};
formdata.licence_id = config.liveagentlicense;
formdata.welcome_message = "";
var visitorId = _.get(data, 'channel.channelInfos.from');
if(!visitorId){
visitorId = _.get(data, 'channel.from');
}
userDataMap[visitorId] = data;
data.message="An Agent will be assigned to you shortly!!!";
sdk.sendUserMessage(data, cb);
sdk.startAgentSession(data, cb);
formdata.welcome_message = "Link for user Chat history with bot: "+ config.app.url +"/history/index.html?visitorId=" + visitorId;
return api.initChat(visitorId, formdata)
.then(function(res){
_map[visitorId] = {
secured_session_id: res.secured_session_id,
visitorId: visitorId,
last_message_id: 0
};
});
}
플랫폼 버전 8.0 릴리스 후, User Meta Tags, Message Meta Tags 및 Session Meta Tags를 추가할 수 있습니다. 다음은 필요한 페이로드에 대한 구문입니다.
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.resetBot
이 함수는 컨텍스트를 지우고 현재 세션을 묵시적으로 삭제하는 데 사용됩니다.
사용법
실행 시, 대화 실행 중에, 사용자 입력이 “reset bot” 명령어를 사용하여 봇을 지우려는 경우. 컨텍스트가 지워지고 작업이 삭제됩니다.
구문:
sdk.resetBot(requestData, callback)
매개변수:
requestData다음과 같습니다.requestData.resetBotUrl
callback– 이벤트 완료 시 호출할 함수.
예
on_user_message : function(requestId, data, callback) {
if (data.message==="reset bot"){
sdk.resetBot(data, callback);
}
sdk.extendRequestId
이 함수는 botKit이 플랫폼으로 메시지를 보내는 데 할당된 시간을 연장하는 데 사용됩니다.
사용법
이 함수는 상담사 전환이 시작되고 얼마 후 플랫폼이 메시지를 수신하지 못할 때 사용됩니다. 이것은 botKit이 플랫폼으로 메시지를 보내는 데 할당된 시간을 연장하여 해결할 수 있습니다.
구문:
sdk.extendRequestId(requestData, callback)
예
function onBotMessage(requestId, data, cb) {
console.log("bot message",JSON.stringify(data));
var visitorId = _.get(data, 'channel.from');
event = schedular.scheduleJob("*/4 * * * *", function() {
pub.get(visitorId+':data',function(err,reply){
if(err) throw err;
sdk.extendRequestId(data,cb);
})
});
}
on_user_message: function(requestId, data, callback) {
var visitorId = _.get(data, 'channel.from');
registerEvent(visitorId, data);
if(event){
event.cancel();
}else{
console.log(new Date(),'event not found');
}
event = schedular.scheduleJob("*/4 * * * *", function() {
pub.get(visitorId+':data',function(err,reply){
if(err) throw err;
sdk.extendRequestId(data,callback);
})
});
참고: 15분 동안 활성 대화가 없는 경우 시간을 연장하는 것은 효과적이지 않습니다. 세션이 비활성화되면 불문하고 agent_transfer 모드가 재설정됩니다.
sdk.skipBotMessage
이 기능은 특정 비즈니스 사용 사례의 특정 메시지를 건너뛸 때 사용합니다.
사용법
실행 시, 대화 실행 중에, BotKit이 메시지를 보내고 계속 진행하기를 기다리는 대신, 시스템은 다음 단계로 진행합니다.
구문:
sdk.skipBotMessage(requestData, callback)
매개변수:
requestData– 데이터callback– 이벤트 완료 시 호출할 함수.
예
if(data.message === "skipBotMessage"){ // condition for skipping a Bot message
sdk.skipBotMessage(data, cb);
}
플랫폼 버전 8.0 릴리스 후, User Meta Tags, Message Meta Tags 및 Session Meta Tags를 추가할 수 있습니다. 다음은 필요한 페이로드에 대한 구문입니다.
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.skipUserMessage
이 기능은 특정 비즈니스 사용 사례의 특정 메시지를 건너뛸 때 사용합니다.
사용법
실행 시, 대화 실행 중에, BotKit이 확인 메시지를 보내고 계속 진행하기를 기다리는 대신, 시스템은 다음 단계로 진행합니다.
구문:
sdk.skipUserMessage(requestData, callback)
매개변수:
requestData– 데이터callback– 이벤트 완료 시 호출할 함수.
예
if(data.message === "skipUserMessage"){ // condition for skipping a user message
sdk.skipUserMessage(data, cb);
}
플랫폼 버전 8.0 릴리스 후, User Meta Tags, Message Meta Tags 및 Session Meta Tags를 추가할 수 있습니다. 다음은 필요한 페이로드에 대한 구문입니다.
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.closeConversationSession
이 함수는 대화 세션을 종료하는 데 사용됩니다.
사용법
구문:
sdk.closeConversationSession(requestData, callback)
매개변수:
requestData– 데이터callback– 이벤트 완료 시 호출할 함수.
예
if(data.message === "closeConversationSession"){ // condition for skipping a user message
sdk.closeConversationSession(data, cb);
}
플랫폼 버전 8.0 릴리스 후, User Meta Tags, Message Meta Tags 및 Session Meta Tags를 추가할 수 있습니다. 다음은 필요한 페이로드에 대한 구문입니다.
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}