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>"
}
]
}
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);
プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:
metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }
sdk.sendBotMessage
<span style="font-weight: 400">この関数は、ボットにメッセージを送信します。</span><br /><strong>使用方法
使用法
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ー イベント完了時に呼び出される関数で、更新されたメッセージとコンテキストを ボット プラットフォームに送信します。
サンプル
以下のコードスニペットは、ユーザーのレスポンスをボットに送信します。
on_user_message: function(requestId, payload, callback) { sdk.sendBotMessage(payload, callback); },
この on_user_message の関数では、メッセージはユーザーに直接返され、ライブ エージェントへの転送でない場合は、ボットに送られます。
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); } };
プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:
metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }
sdk.AsyncResponse
この関数は、ボット プラットフォームに送信する非同期レスポンスを用意します。
使用方法
ダイアログ タスクの実行フローが Webhook ノードに到達した場合、ボット プラットフォームは SDK に対して on_webhook イベント呼出しを行います。on_webhook イベント呼出しは、2 種類のレスポンスをサポートしています:
- 同期レスポンス ー ビジネス ロジックの実行が許容時間内に完了できる場合、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 イベント呼出しでは、2 種類のレスポンスをサポートしています。
- 同期レスポンス ー ビジネス ロジックの実行が許容時間内に完了できる場合、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.このサービスは、非同期にレスポンスすることが期待されています。//'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 は、各ボットに対して 1 つの 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–requestId非同期のon_webhookイベント呼出し 。（非同期の <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 イベントが失敗した場合に、選択した予約の失敗メッセージをユーザーに送信します。
/*/ * Webhook に成功フラグで非同期に応答します。*/ 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ー Bot ビルダーの「設定」ページからアクセスできるボット 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); }
プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:
metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }
sdk.startAgentSession
この関数は、エージェント セッションが開始されたことをプラットフォームに通知するために使用されます。
使用方法
この関数は、エージェント転送が開始され、エージェント転送が進行中であることをボットに表示したい場合に使用します。これに従うと、たとえば onMessages() で BotKit が受け取るデータ オブジェクトは、エージェント セッションが true になります。さらに、BotKit から sdk.clearAgentSession が呼び出されると、エージェント セッションが完了したことがプラットフォームに通知され、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 }; }); }
プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:
metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }
sdk.resetBot
この関数は、コンテキストを消去して、現在のタスクを表示せずに破棄するために使用されます。
使用方法
実行時、ダイアログの実行中に、ユーザー入力が「ボットのリセット」コマンドを使用してボットを消去したい場合に使用します。コンテキストを消去して、タスクを破棄することができます。
構文:
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.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); }
プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:
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 === "closeConversationSession"){ // condition for skipping a user message sdk.closeConversationSession(data, cb); }
プラットフォームの Ver 8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:
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); }
プラットフォームの Ver8.0 のリリース後は、ユーザー、メッセージ、およびセッションのメタタグを追加できるようになりました。必要なペイロードの構文は以下のようになります:
metaTags":{ "userMetaTags":[ { "name":"<string>", "value":"<string>" } ], "sessionMetaTags":[ { "name":"<string>", "value":"<string>" } ], "messageMetaTags":[ { "name":"<string>", "value":"<string>" } ] }
The Kore.ai BotKit SDK provides functions that you can use for greater control of your bot and provide a better user experience.
The following functions are supported by the BotKit SDK.
sdk.sendUserMessage
This function sends the message to the bot user.
Usage
Used inside the on_bot_message event callback. An on_bot_message event is called when the bot sends the reply to the user. In the SDK, payload data such as message can be modified and sent to the Bots Platform.
Syntax
sdk.sendUserMessage(payload, callback)
Parameters:
payload– A JSON response payload as follows:{ "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> }The above message payload is when the user language is detected and the spell correction is done. In case the user language is not detected then the following would be the message structure
{ "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– The function to call at event completion used to send the updated message and context back to the Bots Platform.
Examples
The following code snippet shows an example of the sdk.sendUserMessage function returning an error to the user.
return sdk.sendUserMessage(payload, function(err){
if(err)
console.log("err", err);
In the following code example, the initial message to a user is displayed when a user switches to a Live Agent.
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);
In the next code example, the message sent to the user with the sdk.sendUserMessage function is based on user selection for converting currency. The isTemplate parameter determines if custom or default message formatting should be used.
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);
Post the release of ver8.0 of the platform, you can add User, Message, and Session Meta Tags. The following would be the syntax for the necessary payload:
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.sendBotMessage
This function sends the message to the bot.
Usage
Used inside the on_user_message event callback. An on_user_message event is called when the user sends a message to the bot. In the SDK, payload data such as message can be modified and sent to the Bots Platform.
A validation check is performed on the user message – the message cannot have more than 3000 characters and each word cannot have more than 1200 letters.
Syntax:
sdk.sendBotMessage(payload, callback)
Parameters:
payload– A JSON response payload as follows:{ "message":"Message sent by the user", "channel":"Channel name", "context": <context object> }callback– The function to call at event completion used to send the updated message and context back to the Bots Platform.
Examples
The following code snippet send the user response to the bot.
on_user_message: function(requestId, payload, callback) {
sdk.sendBotMessage(payload, callback);
},
In this on_user_message function, the message is returned directly to the user, and if not a transfer to a Live Agent, then is sent to the bot.
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);
}
};
Post the release of ver8.0 of the platform, you can add User, Message, and Session Meta Tags. The following would be the syntax for the necessary payload:
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.AsyncResponse
This function prepares the asynchronous response to send to the Bots Platform.
Usage
If the dialog task execution flow reaches a webhook node, the Bots Platform makes an on_webhook event call to the SDK. The on_webhook event call supports two types of responses:
- Synchronous response – If the business logic execution can be completed within an acceptable time, the SDK can respond synchronously using the
callback(null, payload)function. - Asynchronous response – If the business logic execution needs more time, the SDK can send the asynchronous response to the Bots Platform by calling the
callback(null, new sdk.AsyncResponse())function to send an HTTP code 202 to the Bots Platform. When the response is ready, the SDK can call thesdk.respondToHook(payload)function.
Syntax:
sdk.AsyncResponse() callback(null, new sdk.AsyncResponse())
Parameters:
None.
Examples
This example of an on_webhook function, the Bot waits asynchronously for the booking of the cab selected by the user.
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
This function sends the webhook response to the Bots Platform.
Usage
If the dialog task execution flow reaches a webhook node, the Bots Platform makes an on_webhook event call to the SDK. The on_webhook event call supports two types of responses:
- Synchronous response – If the business logic execution can be completed within an acceptable time, the SDK can respond synchronously using the
callback(null, payload)function. - Asynchronous response – If the business logic execution needs more time, the SDK can send the asynchronous response to the Bots Platform by calling the
callback(null, new sdk.AsyncResponse())function to send an HTTP code 202 to the Bots Platform. When the response is ready, the SDK can call thesdk.respondToHook(payload)function.
Syntax:
sdk.respondToHook(payload)
Parameters:
payload– A JSON response payload as follows:{ "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }
Examples
In the following code snippet, if the booking of the cab fails, the event is handled synchronously. Conversely, the booking of the cab is handled asynchronously via a 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
This function registers the bot and makes callback events available at runtime.
Usage
The BotKit SDK is designed to require you to create one Node.js file for each bot. All callbacks for that bot are maintained in the Node.js file. To register a bot, you must export the following variables and functions as:
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
},
}
Syntax:
To register the bot, call
sdk.registerBot(require('./<Bot Name>.js'));
Parameters:
- Node.js file for the bot to register
Examples
The following code example shows registration of the bot by botId and 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
This function saves the data in the Redis in-memory data structure store.
Usage
When you respond to an on_webhook event call asynchronously, you can store the payload in the Redis store by requestId. After completion of your business logic execution, you can read the data using the sdk.getSavedData(requestId)function while preparing the webhook response.
Syntax:
sdk.saveData(requestId, payload)
Parameters:
requestId– TherequestIdfrom the asynchronouson_webhookevent call.payload– A JSON response payload as follows:{ "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }
Examples
In this on_webhook event, the user request to book a cab is saved in the Redis store and the asynchronous processing of the booking begins.
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
This function reads the data in the Redis in-memory data structure store.
Usage
When you respond to an on_webhook event call asynchronously, you can store the payload in the Redis store by requestId. After completion of your business logic execution, you can read the data using the sdk.getSavedData(requestId)function while preparing the webhook response.
Syntax:
sdk.getSavedData(requestId, payload)
Parameters:
requestId– TherequestIdfrom the asynchronouson_webhookevent call.payload– A JSON response payload as follows:{ "taskId":"Dialog task ID", "nodeId":"Current node ID in the dialog flow", "channel":"Channel name", "context": <context object> }
Examples
In this code example, the sdk.getSavedData function is used to return the selected cab and booking information, or if the asynchronous booking webhook event fails, sends the failure message for the selected booking to the user.
/*/
* 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
This function is used to get the transcript of previous conversations between the Bot and the user. It works similar to the public API Conversation History (see here for Conversation History API)
Usage
Fetches the conversational messages between the bot and user in reverse chronological order. This API supports pagination. You can provide offset/skip and limit to get a certain number of messages at a time.
Syntax:
sdk.getMessages(requestData, callback)
Parameters:
requestData– as follows:requestData.baseUrl + '/getMessages?' + "skip=" + offset + "&limit=" + limit + "&userId=" + userId+"&channelType"=channel-type
where
stream_id– Bot ID accessible from the Config Settings page of the Bot Builderuser_id– The ID of the user whose conversation history to accessskip– The number of messages to be skipped.limit– The number of messages to be shown on each page.channelType– Optional, the channel where the conversation was hosted.
callback– The function to call at event completion used to send the message history back to the Bots Platform.
Examples
//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
This function is used to clear the Agent session and reestablish the conversation with the Bot.
Usage
In an Agent Transfer scenario, when the agent closes the conversation with the user, chat_closed event gets triggered from 3rd party provider. In such situations, this function is invoked to re-establish the conversation with the bot
Syntax:
sdk.clearAgentSession(requestData, callback)
Parameters:
requestData– as follows:requestData.baseUrl+ '/clearAgentSession/' + requestData.requestId
where
requestId– the session id
callback– The function to call at event completion.
Examples
//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);
}
Post the release of ver8.0 of the platform, you can add User, Message, and Session Meta Tags. The following would be the syntax for the necessary payload:
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.startAgentSession
This function is used to notify the platform that an Agent session has started.
Usage
This function is used when an Agent Transfer is initiated and you want to indicate to the Bot that the agent transfer is in progress. Followed by this, the data object received by BotKit at onMessages(), for instance, would have agent session as true. Further, if the sdk.clearAgentSession is called from BotKit, the platform is notified that agent session is completed and the data object received by the BotKit would have the agent session set to false.
Syntax:
sdk.startAgentSession(requestData, callback)
Parameters:
requestData– as follows:requestData.baseUrl + '/startAgentSession/' + requestData.requestId
where
requestId– the session id
callback– The function to call at event completion.
Examples
//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
};
});
}
Post the release of ver8.0 of the platform, you can add User, Message, and Session Meta Tags. The following would be the syntax for the necessary payload:
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.resetBot
This function is used to clear the context and discard the current task silently.
Usage
At run time, during the execution of dialog, if the user input might want to clear the Bot using “reset bot” command. Then the context can be cleared and the task discarded.
Syntax:
sdk.resetBot(requestData, callback)
Parameters:
requestData– as follows:requestData.resetBotUrl
callback– The function to call at event completion.
Examples
on_user_message : function(requestId, data, callback) {
if (data.message==="reset bot"){
sdk.resetBot(data, callback);
}
sdk.extendRequestId
This function is used to extend the time allocated for botKit to send messages to the platform.
Usage
This function is used when an Agent Transfer is initiated and after sometime platform might not be receiving messages. This can be addressed by extending the time allocated for the botKit to send messages to the platform.
Syntax:
sdk.extendRequestId(requestData, callback)
Examples
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);
})
});
Note: Extending the time will not be effective in case of no active conversation for a period of 15 minutes. An inactive session would cause the agent_transfer mode to be reset irrespective.
sdk.skipBotMessage
This function is used to skip a specific message for a specific business use case.
Usage
At run time, during the execution of dialog, instead of waiting for the BotKit to send a message to proceed, the system will proceed to the next step.
Syntax:
sdk.skipBotMessage(requestData, callback)
Parameters:
requestData– datacallback– The function to call at event completion.
Examples
if(data.message === "skipBotMessage"){ // condition for skipping a Bot message
sdk.skipBotMessage(data, cb);
}
Post the release of ver8.0 of the platform, you can add User, Message, and Session Meta Tags. The following would be the syntax for the necessary payload:
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.skipUserMessage
This function is used to skip a specific message for a specific business use case.
Usage
At run time, during the execution of dialog, instead of waiting for the BotKit to send a confirmation message to proceed, the system will proceed with the next step.
Syntax:
sdk.skipUserMessage(requestData, callback)
Parameters:
requestData– datacallback– The function to call at event completion.
Examples
if(data.message === "skipUserMessage"){ // condition for skipping a user message
sdk.skipUserMessage(data, cb);
}
Post the release of ver8.0 of the platform, you can add User, Message, and Session Meta Tags. The following would be the syntax for the necessary payload:
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}
sdk.closeConversationSession
This function is used to close a conversation session.
Usage
Syntax:
sdk.closeConversationSession(requestData, callback)
Parameters:
requestData– datacallback– The function to call at event completion.
Examples
if(data.message === "closeConversationSession"){ // condition for skipping a user message
sdk.closeConversationSession(data, cb);
}
Post the release of ver8.0 of the platform, you can add User, Message, and Session Meta Tags. The following would be the syntax for the necessary payload:
metaTags":{
"userMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"sessionMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
],
"messageMetaTags":[
{
"name":"<string>",
"value":"<string>"
}
]
}