@vivocha/bot-sdk v5.0.0

Vivocha Bot SDK

JavaScript / TypeScript SDK to create Bot Agents and Filters for the Vivocha platform.

IMPORTANT: this version of the Bot SDK is intended to be used with the Vivocha platform >= v.7.x. For legacy versions of the Bot SDK (Vivocha v.6), please refer to the Legacy documentation.

The Vivocha Bot SDK allows to write Vivocha Bot Agents integrating existing bots, built and trained using your preferred bot / NLP platform. E.g., Dialogflow, IBM Watson Assistant (formerly Conversation), Wit.ai, Microsoft Bot framework, etc... Moreover, the SDK enables writing new bots from scratch or integrating virtually any API-based chatbot platform with Vivocha.

By creating a BotManager it is possible to register multi-platform bot implementations allowing the Vivocha Platform to communicate with them through a well-defined and uniform message-based API, providing a rich set of multi-media chat messages.

Tested with Node.js version 12.x.

To start with this version of the Bot SDK, it is recommended to install it from NPM:

npm i @vivocha/bot-sdk

Table of Contents

• Overview
• Quick Start, by Example
  • BotAgents and Manager
  • BotFilters
• BotAgent
  • BotRequest
    • BotSettings
    • BotEngineSettings
    • BotRequest Example
  • BotResponse
    • BotResponse Examples
  • BotMessage
    • Text Message
    • Postback Message
    • Attachment Message
    • Multi Attachment Message
    • Action Message
    • IsWriting Message
    • Location Message
  • MessageQuickReply
  • MessageTemplate
  • TemplateElement
  • DefaultAction
  • Button
    • PostbackButton
    • WebURLButton
    • CustomEventButton
• Bot Messages Utilities
• BotManager
  • Registering a Bot Agent
  • BotManager Web API
• Bot Filters
  • BotFilter Web API
• About Vivocha Bots and Transfers to Human Agents
• Sending Attachments
• Asynchronous Bot Responses
• Supported Bot and NLP Platforms
  • Dialogflow
    • Dialogflow V2
      • Vivocha Bot Messages and Dialogflow V2
      • Data collection and Dialogflow System Entities
      • Dialogflow Constraints, Hints and Tips
  • IBM Watson Assistant
    • Vivocha Rich Messages and Watson Assistant
    • Watson Assistant Hints and Tips
  • Wit.ai, writing chat bots
    • Wit.ai Bot Configuration
    • Wit.ai with Vivocha Hint and Tips
  • Microsoft Bots
    • Using the Bot Framework version 4
    • Using the Bot Framework version 3
• Running BotManagers and BotFilters as AWS Lambdas
  • Prerequisites
  • Writing a BotManager or a BotFilter as a Lambda Function
• Running Tests

Overview

The Vivocha platform provides out-of-the-box native support for chat bots built using IBM Watson Assistant (formerly Conversation), Dialogflow and Microsoft Bot Framework platforms. This means that it is possible to integrate these particular bot implementations with Vivocha simply using the Vivocha configuration app and specificing few settings, like authentication tokens, and following some, very simple, mandatory guidelines when building the bot, at design time. The first sections of this documentation focus on building custom Bot Agents using the Bot SDK, which allows to integrate them with the Vivocha system with ease and also provides a library to quickly write bots using the Wit.ai NLP platform.

The last sections of this guide are dedicated to the integration guidelines for chatbots built with the four supported platforms: IBM Watson Assistant (formerly Conversation), Dialogflow, Microsoft Bot Framework and Wit.ai and about how to transfer contacts from a bot to another agent.

The following picture shows an high-level overview of the Vivocha Bot SDK and its software components.

FIGURE 1 - Overview of the main modules of the Bot SDK

Quick Start, by Example

The examples folder contains some samples of Bot Managers, a Wit.ai Bot implementation and a Filter, along with some related HTTP requests to show how to call their APIs.

See:

• sample: dead simple bot Agent and Manager plus a Bot Filter, read and use the examples/http-requests/sample.http file to learn more and to run them;
• dummy-bot: a simple bot (Agent and Manager) able to understand some simple "commands" to return several types of messages, including quick replies and templates. You can run it and connect to Vivocha as a custom Bot Agent (read more here), then just send to the bot the fullhelp text message by chat to discover its capabilities.
• sample-wit: a simple bot using the Wit.ai platform.

TIP: For a quick start learning about the format of requests, responses and messages body, including quick replies and templates, see the Dummy Bot code.

IMPORTANT: To learn how to connect a bot to the Vivocha Platform, start from the related Vivocha Documentation.

BotAgents and Manager

TL;DR

A BotAgent represents and communicates with a particular Bot implementation platform. A BotManager exposes a Web API acting as a gateway to registered BotAgents.

Usually, the steps to use agents and managers are:

1. Write a BotAgent for every Bot/NLP platform you need to support, handling / wrapping / transforming messages of BotRequest and BotResponse types;
2. create a BotAgentManager instance;
3. register the BotAgents defined in step 1) to the BotAgentManager, through the registerAgent(key, botAgent) method, where key (string) is the choosen bot engine (e.g, DialogflowV2, Watson, etc...) and agent is a BotAgent instance;
4. run the BotAgentManager service through its listen() method, it exposes a Web API;
5. call the Web API endpoints to send messages to the bot agents in a uniform way. The manager forwards the message to the right registered BotAgent thanks to the engine.type message property, used as key in step 3). The API is fully described by its OpenAPI 3.0 specification, available at http://<BotAgentManager-Host>:<port>/openapi.json.

BotFilters

TL;DR

A BotFilter is a micro (web) service to filter/manipulate/enrich/transform BotRequests and/or BotResponses. For example, a BotFilter can enrich a request calling an external API to get additional data before sending it to a BotAgent, or it can filter a response coming from a BotAgent to transform data before forwarding it to the user chat.

Basically, to write a filter you have to:

1. Instantiate a BotFilter specifying a BotRequestFilter or a BotResponseFilter. These are the functions containing your logic to manipulate/filter/enrich requests to bots and responses from them. Inside them you can call, for example, external web services, access to DBs, transform data and do whatever you need to do to achieve your application-specific goal. A BotFilter can provide a filter only for requests, only for responses or both;
2. run the BotFilter service through its listen() method, it exposes a Web API; the API is fully described by its OpenAPI specification, available at http://<BotFilter-Host>:<port>/openapi.json.

BotAgent

A BotAgent represents an abstract Bot implementation and it directly communicates with a particular Bot / NLP platform (like Dialogflow, IBM Watson Assistant, Microsoft Bots, and so on...). In the Vivocha model, a Bot is represented by a function with the following signature:

In Typescript:

(request: BotRequest): Promise<BotResponse>

In JavaScript:

let botAgent = async (request) => {
    // the logic to interact with the particular bot implementation
    // goes here, then produce a BotResponse message...
    ...
    return response;
}

BotRequest

Requests are sent to BotAgents, BotManagers and BotFilters. A BotRequest is a JSON with the following properties (in bold the required properties):

BotMessage

Some contents and definitions of the Vivocha Bot Messages are inspired by the Facebook Messenger messages specification, but adapted and extended as needed by the Vivocha Platform. Currently, messages' quick_replies and template properties are supported ONLY in BotResponses. Also messages of type IsWriting and Action are supported in BotResponses ONLY.

Notes: Generally speaking, while messages containing quick replies or templates have no particular constraints about the number of elements (and buttons, etc...), please take into consideration that Facebook Messenger have some contraints about them, i.e., in the number of quick replies or buttons per message; therefore, if you're supporting chats also through the Facebook Messenger channel, then you need to be compliant to its specification (more details about Messenger messages constraints can be found here). Anyway, in case of an exceeding number of elements, the Vivocha platform will trim them before sending to Messenger clients.

A BotMessage can be of five different types: Text Message, Postback Message, Attachment Message, Action Message and IsWriting Message.

Text Message

A Text BotMessage can be used by a bot to send from simple, text-based messages to more complex messages containing quick replies and templates.

A Text Message has the following properties (required are in bold):

Postback Message

A Postback Message can be sent to a bot to convey a simple text content and, optionally, a custom payload. Its properties are (required are in bold):

Attachment Message

A message containing an attachment that can be sent/received to/from a bot to send files. See Sending Attachments section in this document for more details about sending attachments to/from a bot.

Its properties are (required are in bold):

When the bot receives an Attachment message from Vivocha, it can download it doing a HTTP GET reqiest to the URL specified by the message url property.

Attachment Metadata

Attachment metadata object.

Properties are (required are in bold):

Multi Attachment Message

A message containing one or more attachment that can be received from a bot to send files.

Its properties are (required are in bold):

When the bot receives a Multi Attachment message from Vivocha, it can download its assets doing a HTTP GET request to the URL specified in each attachment url property.

Action Message

An Action Message contains a custom action name with optional parameters that can be sent to a client (i.e. the Vivocha Interaction App or a mobile app) to mimic a Remote Procedure Call (RPC).

The Action Message has the following specific properties (required ones are in bold):

IsWriting Message

An IsWriting Message can be sent by a Bot in a BotResponse to tell/show in the user's chat that the bot is writing/preparing a response.

The IsWriting Message specific properties are the following (required are in bold):

Location Message

An Location Message contains a geo data with optional parameters that can be sent to a client (i.e. the Vivocha Interaction App or a mobile app) or to a Bot.

The Location Message has the following specific properties (required ones are in bold):

Environment

Environment property contains Vivocha specific environment data, sent by the platform. See the table below for details about conveyed data.

NB:

• for a bot used in data collections of type Bot (dialog-based data collectors), the environment object DOES NOT contain neighter the contactId property (because it is a pre-contact task) nor the token property.
• The token property is sent by Vivocha only ONLY and ONLY IF the configured Bot URL is under HTTPS.

The environment object has the following properties, ALL OPTIONAL:

Channel Capabilities

When set, the environment caps property is an object representing the capabilities of the particular communication channel that the final user is using to interact with the bot. Consequently, by reading these channel capabilities, the bot can compose a more adequate response type to send back to the user; for example it can decide to not send a message containing a template if the channel doesn't support it; or, it can decide to not send an attachment; or, it can decide to send a totally custom template, if the channel declares its name in its capabilities.

The Channel Capabilities object can have the following OPTIONAL properties:

Media

Media object has media specific capabilities represented by property name; for example: chat, voice or video. For chatbots, usually we are interested in the media named chat.

Then, this section describes the media.chat property.

media.chat can be a boolean (false to specify that the channel doesn't support chatting) or an object, which can have the OPTIONAL properties reported in the table below in this section.

In general, when not explicitely documented, a specific capability property (like: isWriting or acks) can be set to a value taken from a well-defined enumeration of possible values, that are:

• false: the capability is not supported. Messages of this specific type CAN NOT be sent or received to/from the external service that the channel represents;
• in: Messages of this specific capability type CAN BE sent by the channel/external service TO (and only in this direction) the Vivocha Bot;
• out: Messages of this specific capability type CAN BE sent by the Vivocha Bot service TO (and only in this direction) the external service that the channel represents;
• both: a Message related to the capability CAN BE sent in both the directions between the Vivocha Bot and the external service that the channel represents (in other words it means "in and out").

Allowed media.chat properties are:

GeoIP

GeoIP information about the contact. The GeoIP object has the following (ALL OPTIONAL) properties:

BotSettings

Bot platform settings object. Along with the engine property (see the table below), it is possible to set an arbitrarily number of properties. In case, it is responsability of the specific Bot implementation / platform to handle them.

BotEngineSettings

Its properties are (required are in bold):

MessageQuickReply

Its properties are (required are in bold):

Example 1: A BotResponse message containing three simple quick replies

{
    ...
    "messages": [
        {
            "code": "message",
            "type": "text",
            "body": "Just an example of quick replies... which color?",
            "quick_replies": [
                {
                    "content_type": "text",
                    "title": "Red",
                    "payload": "red 1"
                },
                {
                    "content_type": "text",
                    "title": "Blue",
                    "payload": "blue 2"
                },
                {
                    "content_type": "text",
                    "title": "White",
                    "payload": "white 3"
                }
            ]
        }
    ],
    "event": "continue",
    "data": {}
}

Which is rendered by the Vivocha interaction app like in the following screenshot:

Example 2: A BotResponse message containing three quick replies with vertical orientation

{
    ...
    "messages": [
        {
            "code": "message",
            "type": "text",
            "body": "Just an example of quick replies... which color?",
            "quick_replies": [
                {
                    "content_type": "text",
                    "title": "Red",
                    "payload": "red 1"
                },
                {
                    "content_type": "text",
                    "title": "Blue",
                    "payload": "blue 2"
                },
                {
                    "content_type": "text",
                    "title": "White",
                    "payload": "white 3"
                }
            ],
            "quick_replies_orientation": "vertical"
        }
    ],
    "event": "continue",
    "data": {}
}

Which is rendered by the Vivocha interaction app like in the following screenshot:

Example 3: A BotResponse message containing some quick replies with images

{
    ...
    "messages": [
        {
            "code": "message",
            "type": "text",
            "body": "Choose a team member",
            "quick_replies": [
                {
                    "content_type": "text",
                    "title": "Federico",
                    "payload": "federico 1",
                    "image_url": "https://www.vivocha.com/wp-content/uploads/2017/03/team_federico.png"
                },
                {
                    "content_type": "text",
                    "title": "Andrea",
                    "payload": "andrea 2",
                    "image_url": "https://www.vivocha.com/wp-content/uploads/2017/03/team_andrea.png"
                },
                {
                    "content_type": "text",
                    "title": "Antonio",
                    "payload": "antonio 3",
                    "image_url": "https://www.vivocha.com/wp-content/uploads/2017/05/team-antonio.png"
                },
                {
                    "content_type": "text",
                    "title": "Marco",
                    "payload": "marco 4",
                    "image_url": "https://www.vivocha.com/wp-content/uploads/2017/03/Marco_Amadori.png"
                }
            ]
        }
    ],
    "event": "continue",
    "data": {}
}

Which is rendered by the Vivocha interaction app like in the following screenshot:

MessageTemplate

Properties are (required are in bold):

TemplateElement

Generally, a Template Element can be an object of any type, BUT if you want to use the out-of-the box templates rendering provided by the Vivocha interaction app, or the automatic template conversion implemented for some channels, you need to strictly follow the following specs:

in a Template Element only the property title is mandatory, but at least one optional property among the following must be set in addition to it.

Example 4: A BotResponse message containing a generic template

{
    ...
    "messages": [
        {
            "code": "message",
            "type": "text",
            "body": "Just an example of generic template:",
            "template": {
                "type": "generic",
                "elements": [
                    {
                        "title": "Meow!",
                        "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/5d/Adult_Scottish_Fold.jpg/1920px-Adult_Scottish_Fold.jpg",
                        "subtitle": "We have the right cat for everyone.",
                        "default_action": {
                            "type": "web_url",
                            "url": "https://en.wikipedia.org/wiki/Cat"
                        },
                        "buttons": [
                            {
                                "type": "web_url",
                                "url": "https://en.wikipedia.org/wiki/Cat",
                                "title": "View Website"
                            },
                            {
                                "type": "postback",
                                "title": "OK",
                                "payload": "ok abcd 123"
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "event": "continue",
    "data": {}
}

which is rendered by the Vivocha interaction app like in the following screenshot:

Example 5: A BotResponse message containing a carousel of generic templates

{
    ...
    "messages": [
        {
            "code": "message",
            "type": "text",
            "body": "Just an example of generic template:",
            "template": {
                "type": "generic",
                "elements": [
                    {
                        "title": "Meow!",
                        "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/5/5d/Adult_Scottish_Fold.jpg/1920px-Adult_Scottish_Fold.jpg",
                        "subtitle": "Scottish fold",
                        "default_action": {
                            "type": "web_url",
                            "url": "https://en.wikipedia.org/wiki/Cat"
                        },
                        "buttons": [
                            {
                                "type": "web_url",
                                "url": "https://en.wikipedia.org/wiki/Cat",
                                "title": "View Website"
                            },
                            {
                                "type": "postback",
                                "title": "OK",
                                "payload": "ok abcd 123"
                            }
                        ]
                    },
                    {
                        "title": "Meow!",
                        "image_url": "https://upload.wikimedia.org/wikipedia/commons/thumb/c/c0/Tajeschidolls_Beren_of_LoveLorien_Ragdoll_Seal_Mink_Lynx_Bicolor.jpg/1024px-Tajeschidolls_Beren_of_LoveLorien_Ragdoll_Seal_Mink_Lynx_Bicolor.jpg",
                        "subtitle": "Ragdoll",
                        "default_action": {
                            "type": "web_url",
                            "url": "https://en.wikipedia.org/wiki/Cat"
                        },
                        "buttons": [
                            {
                                "type": "web_url",
                                "url": "https://en.wikipedia.org/wiki/Cat",
                                "title": "View Website"
                            },
                            {
                                "type": "postback",
                                "title": "OK",
                                "payload": "ok abcd 123"
                            }
                        ]
                    }
                ]
            }
        }
    ],
    "event": "continue",
    "data": {}
}

Which is shown in the Vivocha web interaction app as in the following screenshot:

Example 6: A BotResponse message containing a list template

{
    ...
    "messages": [
        {
            "code": "message",
            "type": "text",
            "body": "List template",
            "template": {
                "type": "list",
                "elements": [
                    {
                        "title": "Documentation part 1 - 2018",
                        "subtitle": "All documents about our products available in 2018. Advertisement, User's guides, technical info...",
                        "default_action": {
                            "type": "web_url",
                            "url": "https://www.vivocha.com"
                        }
                    },
                    {
                        "title": "Documentation part 2 - 2017",
                        "subtitle": "All documents about our products available in 2017. Advertisement, User's guides, technical info...",
                        "default_action": {
                            "type": "web_url",
                            "url": "https://www.vivocha.com"
                        }
                    },
                    {
                        "title": "Documentation part 3 - 2011-2016",
                        "subtitle": "All deprecated documents about old products no more available...",
                        "default_action": {
                            "type": "web_url",
                            "url": "https://www.vivocha.com"
                        }
                    }
                ],
                "buttons": [
                    {
                        "type": "postback",
                        "title": "More",
                        "payload": "view_more"
                    }
                ]
            }
        }
    ],
    "event": "continue",
    "data": {}
}

Which