Botfriends-handover-nodejs NPM

BOTfriends Handover Library NodeJs

BOTfriends Handover Library helps you interact with the BOTfriends Handover Tool. It is designed to forward conversation messages to the Interface.

Installation

npm install botfriends-handover-nodejs

Usage

const { HandoverClient } = require('botfriends-handover-nodejs')

// init HandoverClient
const handover = new HandoverClient('some-jwt', 'https://your-api-url/')

handover.sendMessage({
  userId: 'some-user',
  message: 'some-message'
}).then(function () {
    // do something
})

// ...

Methods

Method	Description
sendMessage	to send a text message with optional quickreplies
sendFile	to send an image or file
sendCarousel	to send cards or carousels
sendLocation	to send a location
getOnlineAgents	to get the online status of the agents
getHandoverStatus	to get the handover status of a conversation
startHandover	to request a handover by user

sendMessage

nlpData = {
  userQuery: string,
  detectedIntent: string,
  confidenceScore: number
}

message = {
  role: string,
  text?: string,
  source: string,
  actions?: Array<string>,
  nlpData?: NlpData
}

sendMessage (userId: string, message: Any)

there will be no response. if something is not working, an error will be thrown

sendFile

nlpData = {
  userQuery: string,
  detectedIntent: string,
  confidenceScore: number
}

file = {
  role: string,
  text?: string,
  source?: string,
  mediaUrl: string,
  mediaType?: string,
  nlpData?: NlpData
}

sendFile (userId: string, file: Any, type: string)

there will be no response. if something is not working, an error will be thrown

sendCarousel

nlpData = {
  userQuery: string,
  detectedIntent: string,
  confidenceScore: number
}

carousel = {
  role: string,
  text?: string,
  source: string,
  items: Array<Item>,
  nlpData?: NlpData
}

item = {
  title: string,
  description: string,
  mediaUrl?: string,
  actions: Array<Action>,
  size?: Number
}

action = {
  text: string,
  type: string,
  uri?: string,
  payload?: string
}

sendCarousel (userId: string, carousel: Any)

there will be no response. if something is not working, an error will be thrown

sendLocation

nlpData = {
  userQuery: string,
  detectedIntent: string,
  confidenceScore: number
}

location = {
  role: string,
  source: string,
  coordinates: {
    lat: Number,
    long: Number
  },
  nlpData?: NlpData
}

sendLocation (userId: string, location: Any)

there will be no response. if something is not working, an error will be thrown

getOnlineAgents

getOnlineAgents ()

response = Array<Agent>

agent = {
  email: string
}

getHandoverStatus

getHandoverStatus (userId: string)

response = {
  handover: Boolean
}

startHandover

startHandover (userId: string)

response = {
  success: Boolean
}

Common properties

Message (message, file, carousel, location)

role: string -> "user" or "bot"
source: string -> "messenger", "web" or "whatsapp"

Action

type: string -> "link" or "postback"

Initialize a handover

If you want to initialize a human handover, you just need to send the handover flag with your message like

handover.sendMessage({
  userId: 'some-user',
  message: 'some-message',
}).then(function () {
    // do something
})
// ...

How Can I integrate this into my Chatbot now?

The basic concept of a chatbot architecture consists of any messaging interface which is directing all its conversations through a backend. The backend then handles the natural language processing (NLP) on its own or with some external services like DialogFlow.

So the first step to integrate the BOTfriends Handover Tool is to send all of these conversation data also to your Handover Interface. Therefore you can use this library. In the settings page of any app you created in the Handover Interface you can find the required JWT-Token to authenticate. Summarized:

Go to the Settings Page of an app in the Handover Tool
Copy the JWT-Token, backend api url and save it securely
Install the library in your project
Instanciate the Handover Client with the JWT-Token and the backend url
Use the manual above to send all messages from the user and also from the bot to the handover tool

At this step you already have the control over every message sent to your bot. And here comes the tricky part. To use the handover tool and all its features, it has to be abled to talk to your backend. If you want to engage into a communication, the tools needs to tell your backend to stop its communication with the NPL-Services. So what you need to do now is:

Setup a post endpoint for the webhook (e.g. https://your-nice-bot-backend/api/handover/webhook)
Go to the settings page and enter your webhook url (to secure this you can provide a webhook token - this will be sent in a "webhook_token" header then)
Let the endpoint hear for some events (will be explained in the following section)
Build a logic how to cut of the communication between your NLP and your backend when a handover is initialized

Webhook Events

All Webhook Events trigger a POST-Request to your backend: In the body you can find:

Id of the user
Name of the event
The message to the user if enabled

The response needs to be a 200 Status Code.

Events

Event	Request body
sendMessage	{ userId: 'some-user', name: 'sendMessage', message: 'some-message' }
sendFile	{ userId: 'some-user', name: 'sendFile', file: 'some-file' }
startHandover	{ userId: 'some-user', name: 'startHandover', text: 'some-message' }
cancelHandover	{ userId: 'some-user', name: 'cancelHandover', text: 'some-message' }
sendTypingStart	{ userId: 'some-user', name: 'sendTypingStart' }
sendTypingEnd	{ userId: 'some-user', name: 'sendTypingEnd' }