Skip to content

Bot.md

Latest commit

 

History

History
195 lines (133 loc) · 6.1 KB

Bot.md

File metadata and controls

195 lines (133 loc) · 6.1 KB

Ninchat bot framework for Node.js

Connect

const ninchatbot = require('ninchat-nodejs/ninchat/bot')

Module ninchat-nodejs/ninchat/bot contains a simple framework for implementing chat bots for Ninchat. The Bot class is used to connect to Ninchat, listen to events and send messages.

const identity = {type, name, auth}
const messageTypes = ['ninchat.com/text']
const verboseLogging = false

const bot = new ninchatbot.Bot({identity, messageTypes, verboseLogging})

A bot is instantiated with an identity object. It contains authentication credentials (email and password) of the bot user.

It needs a normal Ninchat user account. It will automatically serve customers in the audience queues it belongs to.

The messageTypes option lists Ninchat message types which the bot implementation wants to use. If the bot sends and receives only text messages, it can be omitted. (Specifying an empty array disables all message types.)

Chat

bot.on('begin', (channelId, queueId, info) => {})
bot.on('messages', (channelId, textMessages) => {})
bot.on('receive', (channelId, typedMessages) => {})
bot.on('writing', (channelId, writing) => {})
bot.on('end', channelId => {})

The begin event is emitted whenever a new customer has been accepted. Channel id is a unique identifier (string) for the chat. The end event is emitted when the chat ends. Between them, messages and receive events are emitted whenever the customer sends something.

A messages callback receives text messages as an array of objects. (Normally the array contains just one message.) A text message object contains the text property.

A receive callback can be used to receive any supported message type (including the text messages). It receives an array of objects which contain the messageType and content properties. Content format depends on the message type.

The writing event is emitted when a customer starts to write or stops writing. Redundant events may also be emitted. (Note that the writing status is not tied to any particular message; messages may be received without the writing status ever being active, and writing status may or may not be turned off after a message is received.)

Messages may be sent one at a time:

bot.sendMessage(channelId, {text: 'Hello!'}) // Defaults to text message type.
bot.sendMessage(channelId, {text: 'Hello!'}, 'ninchat.com/text')
bot.sendMessage(channelId, {data: {Key: 42}}, 'ninchat.com/metadata', []) // Send invisible metadata.
bot.sendMessage(channelId, {data: {tag_ids: ['abc123']}}, 'ninchat.com/metadata', null, true) // Send privileged metadata.

The writing indicator may be set or unset explicitly (it is not unset automatically):

bot.setWriting(channelId, true)
// ...
bot.setWriting(channelId, false)
bot.sendMessage(channelId, {text: 'Phew! This message took a long time to write...'}, 'ninchat.com/text')

Info

The third argument passed to the begin callback is an object containing optional information. The following property might be available:

  • audienceMetadata is an object containing metadata that was provided via Ninchat embed API before the chat started. It includes the secure property if one was provided; its value has been decrypted.

Metadata messages

In addition to audience metadata that is received at the start of the chat, metadata messages may be received during the chat. In order to do that, the ninchat.com/metadata message type must be specified when instantiating Bot, and the receive event must be handled.

The content of a metadata message is an object with the data property. See Ninchat API reference for details.

UI messages

A bot may display widgets which trigger actions when the customer interacts with them. The bot sends ninchat.com/ui/compose messages and receives corrseponding ninchat.com/ui/action messages.

Composition example:

const content = [
	{element: 'button', id: 'foo-1', label: 'Yes'},
	{element: 'button', id: 'foo-2', label: 'No'},
]

bot.sendMessage(id, content, 'ninchat.com/ui/compose')

Remember to specify both message types when instantiating Bot. See Ninchat API reference for details.

Restart

If the bot program is restarted and there are existing, ongoing chats with customers, the resume event is emitted for each one:

bot.on('resume', (channelId, queueId) => {})

If the customer had written something while the bot was not running, a messages event will follow the resume event. The messages array might contain more than one message (in chronological order).

Transfer

The bot may decide to transfer a customer to a human agent:

bot.transferAudience(channelId, queueId)

The current chat will end automatically (the end event is emitted), and the customer will be placed in the specified queue. The queue must have been whitelisted as a possible transfer target via Ninchat queue settings UI.

The bot can make its transfer decision based on the state of the target queue (or queues):

bot.on('queue:closed', (queueId, closed) => {})

The queue:closed event is emitted whenever a queue is opened or closed. Events are emitted for queues which the bot uses to serve customers, and queues which are possible transfer targets. The closed argument is a boolean.

Fatal errors

The error event is emitted when an exceptional event prevents the bot from proceeding:

bot.on('error', eventDetails => {})

Closing session

bot.on('closed', () => {})
bot.close()

The closed event is emitted after the session has been closed as a result of calling the close method. Other events will no longer be emitted after that.

If the close method is called after an error event has been emitted, the closed event is not emitted.

Example

See hello-bot for an example implementation.