@vivocha/bot-sdk

v5.0.0

Published

2 months ago

Vivocha Bot SDK: TypeScript / JavaScript SDK to create/integrate chatbots with the Vivocha platform

Downloads

272

Vivocha Bot SDK

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

| Logo | | :----------------------------------------------------------------------------------------------------------------------------: | | |

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

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:

Write a BotAgent for every Bot/NLP platform you need to support, handling / wrapping / transforming messages of BotRequest and BotResponse types;
create a BotAgentManager instance;
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;
run the BotAgentManager service through its listen() method, it exposes a Web API;
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:

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;
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):

| PROPERTY | VALUE | DESCRIPTION | | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | event | string: start or continue or end or a custom string | start event is sent to wake-up the Bot; continue tells the Bot to continue the conversation; end to set the conversation as finished; a custom string can be set for specific custom internal Bot functionalities. NB: a message with event property set to end is sent by Vivocha only, and only if, the canHandleEndEvent property is set to true in bot settings (i.e. checking the related option in the Vivocha Campaign Builder) | | message | (optional) object, see BotMessage below | the message to send to the BotAgent | | language | (optional) string. E.g., en, it, ... | language string, mandatory for some Bot platforms. | | data | (optional) object | an object containing data to send to the Bot. Its properties must be of basic type. E.g., {"firstname":"Antonio", "lastname": "Smith", "code": 12345} | | context | (optional) object | Opaque, Bot specific context data | | tempContext | (optional) object | Temporary context, useful to store volatile data; i.e., in bot filters chains. | | environment | (optional) object, see Environment | Vivocha specific environment data, sent by the platform, like: host, acct, hmac, campaignId, channelId, entrypointId, engagementId, contactId, tags, token, etc... For a bot used in data collections of type Bot, the environment object DOES NOT contain neither the contactId property (because it is a pre-contact task) nor the token property. The token property is sent by Vivocha in all bot requests but ONLY and ONLY IF the configured Bot URL is under HTTPS. | | settings | (optional) BotSettings object (see below) | Bot platform settings. |

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):

| PROPERTY | VALUE | DESCRIPTION | | --------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | string, value is always `message` | Vivocha code type for Bot messages. | | `type` | string, value is `text` | Vivocha Bot message type. | | `body` | string | the message text body. | | `payload` | (optional) string | a custom payload, usually used to send back the payload of a quick reply or of a postback button in a BotRequest, after the user clicks / taps the corresponding UI button. | | `quick_replies_orientation` | (optional) string: `vertical` or `horizontal` | in case of a message with `quick_replies` it indicates the quick replies buttons group orientation to show in the client; default is `horizontal`. Orientation option is supported by the official Vivocha interaction. | | `quick_replies` | (optional) an array of MessageQuickReply objects (see below) | an array of quick replies. | | `template` | (optional) a MessageTemplate object | a template object. |

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):

| PROPERTY | VALUE | DESCRIPTION | | ---------- | --------------------------------- | ------------------------------------------------------------------------------------------- | | `code` | string, value is always `message` | Vivocha code type for Bot messages. | | `type` | string, set to `postback` | Vivocha Bot message type. | | `body` | string | the message text body. | | `payload` | (optional) string | a custom payload, usually used to send back the payload of a postback button of a template. |

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):

| PROPERTY | VALUE | DESCRIPTION | | ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- | | code | string, value is always message | Vivocha code type for Bot messages. | | type | string, value is attachment | Vivocha Bot message type. | | url | string | the URL from which download the attachment. | | meta | an object of Attachment Metadata type | this object contains some metadata about the attachment being sent. |

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):

| PROPERTY | VALUE | DESCRIPTION | | ----------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `mimetype` | string | MIME Type of the attachment | | `originalUrl` | (optional) string | the original URL of the attachment. It could be different than the attachment `url` property value in case the attachment is being served by a CDN or remote storage | | `originalUrlHash` | (optional) string | a hash related to the attachment, it will be automatically "calculated" by Vivocha platform | | `originalId` | (optional) string | unique Id, automatically assigned by Vivocha when uploaded using the `BotAgentManager.uploadAttachment() method` | | `originalName` | (optional) string | the original file name of the attachment | | `desc` | (optional) string | brief description of the attachment | | `size` | (optional) number | attachment size, as in normal HTTP Content-Length header | | `ref` | (optional) string | A reference ID to correlate the attachment message. It can be used by the client to avoid showing the attachment message twice in the user chat widget. If not set, the Bot SDK will add it, generating an UUID as value |

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):

| PROPERTY | VALUE | DESCRIPTION | | ---------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- | | code | string, value is always message | Vivocha code type for Bot messages. | | type | string, value is multi-attachment | Vivocha Bot message type. | | attachments | array | An array of Attachments objects, composed by an url which represents the attachment public url and a meta object which contains the Attachment Metadata.

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):

| PROPERTY | VALUE | DESCRIPTION | | ----------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | code | string, value is always message | Vivocha code type for Bot messages | | type | string, value is action | Specific Vivocha Bot message type | | action_code | string | the custom action name (e.g, the remote procedure name) | | args | an array of items of any type. Can be an empty array | the args array eventually contains the arguments required by the specified action_code action (intended as a remote procedure to call). |

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):

| PROPERTY | VALUE | DESCRIPTION | | ---------- | --------------------------------- | ---------------------------------- | | code | string, value is always message | Vivocha code type for Bot messages | | type | string, value is iswriting | Specific Vivocha Bot message type |

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):

| PROPERTY | VALUE | DESCRIPTION | | --------------- | --------------------------------- | ---------------------------------- | | code | string, value is always message | Vivocha code type for Bot messages | | type | string, value is location | Specific Vivocha Bot message type | | longitude | number | longitude value | | latitude | number | latitude value | | countryCode | (Optional) string | code of the country | | countryName | (Optional) string | name of the country | | region | (Optional) string | region name | | city | (Optional) string | name of the city | | accuracy | (Optional) number | position accuracy | | timezone | (Optional) string | timezone code | | speed | (Optional) number | speed value | | altitude | (Optional) number | altitude in meters |

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:

| PROPERTY | VALUE | DESCRIPTION | | -------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `host` | (optional) string | Vivocha server host | | `acct` | (optional) string | Vivocha account Id | | `hmac` | (optional) string | HMAC of the bot message | | `caps` | (optional) a ChannelCapabilities object | Capabilities of the channel through the end user contact has been created | | `campaignId` | (optional) string | Id of the Vivocha Campaign from which the contact has been created | | `channelId` | (optional) string | Id of the Vivocha Channel from which the contact has been created | | `entrypointId` | (optional) string | Id of the Vivocha Campaign's Entrypoint by which the contact has been created | | `engagementId` | (optional) string | Id of the Vivocha Engagement by which the contact has been created | | `contactId` | (optional) string | Id of the contact | | `isVerifiedCustomer` | (optional) boolean | set to `true` if the contact belongs to a verified customer, `false` otherwise | | `token` | (optional) string | JWT required to authenticate Vivocha API calls. The `token` property is sent by Vivocha in bot requests ONLY and ONLY IF the configured Bot URL is under HTTPS. | | `tags` | (optional) an array of strings | Contact tags | | `optionalTags` | (optional) an array of strings | Optional contact tags | | `userAgent` | (optional) string | User Agent info | | `geoIP` | (optional) a GeoIP object | Geo IP information about the contact | | `apiVersion` | (optional) string, like `v2`, `v3`, ... | when set it represents the Vivocha API version to call, if needed |

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:

| PROPERTY | VALUE | DESCRIPTION | | ------------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | (optional) string, possible values are `a`, `b`, `c` or `d` | Vivocha channel type. Briefly: `a` represents a stateless channel; `b` a stateless channel that has also start and end steps; `c` a channel that provides also an handshake step, and `d` is a channel that works in P2P mode (i.e, client-to-client) | | `inbound` | (optional) boolean | if `true`, it is an inbound channel | | `outbound` | (optional) boolean | if `true`, it is an outbound channel | | `media` | (optional) Media object | Specific media capabilities | | `transfer` | (optional) boolean | if `true`, it is possible to transfer the contact | | `ping` | (optional) boolean | if `true`, the channel can ping | | `encryption` | (optional) boolean | if `true`, messages encryption is supported |

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:

| PROPERTY | VALUE | DESCRIPTION | | ------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | isWriting | (optional) a boolean false or a string: in or out or both | capability about IsWriting messages in responses | | acks | (optional) a boolean false or a string: in or out or both | capability about ack messages (delivered messages) | | read | (optional) a boolean false or a string: in or out or both | capability about read messages (final user or bot have read the message) | | markdown | (optional) a boolean false or a string: in or out or both | capability about sending markdown formatted text in message bodies | | link | (optional) a boolean false or a string: in or out or both | capability about sending links in messages | | location | (optional) a boolean false or a string: in or out or both | capability about sending Location Messages | | attachment | (optional) a boolean false or a string: in or out or both | capability about sending Attachment Messages | | quickReply | ((optional) a boolean false or a string: in or out or both | capability about sending Text Messages containing Quick Replies | | genericTemplate | (optional) a boolean false or a string: in or out or both | capability about sending Text Messages containing a standard Generic Message Template | | listTemplate | (optional) a boolean false or a string: in or out or both | capability about sending Text Messages containing a List Template | | customTemplateSchemaIds | (optional) array of strings | if the channel supports specific custom templates, the array contains their specific (schema) Ids/names. The bot must be able to send/receive templates in messages accordingly, that it means that a message template (with template type set generic) can have one template element which property type is set to one of the declared specific (schema) Ids |

GeoIP

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

| PROPERTY | VALUE | DESCRIPTION | | ---------------- | ----------------- | ------------------------ | | country_code | (optional) string | Country code | | country_name | (optional) string | Country name | | latitude | (optional) number | Latitude | | longitude | (optional) number | Longitude | | continent_code | (optional) string | Code of the Continent | | ip | (optional) string | IP Address | | region | (optional) string | Name of the region | | city | (optional) string | City name | | postal_code | (optional) string | Postal Code for the City | | metro_code | (optional) string | Metro Code | | time_zone | (optional) string | Contact's timezone |

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.

| PROPERTY | VALUE | DESCRIPTION | | -------- | ------------------------------------------------------------------------- | ----------------------------------- | | `engine` | (optional) BotEngineSettings object (see below) | Specific Bot/NLP Platform settings. |

BotEngineSettings

Its properties are (required are in bold):

| PROPERTY | VALUE | DESCRIPTION | | ---------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | Unique bot engine identifier, i.e., the platform name, like: `Watson`, `DialogflowV2`, `WitAi`, `Microsoft`, `custom`, `mybot`, ... | | `settings` | (optional) object | Specific settings to send to the BOT/NLP platform. E.g. for Watson Assistant (formerly Conversation) is an object like `{"workspaceId": "<id>" "username": "<usrname>", "password": "<passwd>"}`; for a Wit.ai bot is something like: `{"token": "<wit_token>"}`, and so on... You need to refer to the documentation of the specific Bot Platform used. |

MessageQuickReply

Its properties are (required are in bold):

| PROPERTY | VALUE | DESCRIPTION | | ------------------ | ------------------------------- | --------------------------------------------------------------------------------- | | `content_type` | string, accepted value: `text` | Type of the content of the quick reply | | `title` | string | title of the quick reply (usually is the text shown in the quick reply UI button) | | `payload` | (optional) a string or a number | application specific value, string or number related to the quick reply | | `image_url` | (optional) string | a URL of an image to be shown in the quick reply UI |

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:

| | | :----------------------------------------------------------------------------------------------: | | A BotResponse containing a message with quick replies |

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:

| | | :----------------------------------------------------------------------------------------------: | | A BotResponse containing a message with quick replies with vertical orientation |

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:

| | | :--------------------------------------------------------------------------------------------------: | | A BotResponse containing a message with some quick replies containing an image |

MessageTemplate

Properties are (required are in bold):

| PROPERTY | VALUE | DESCRIPTION | | ---------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `type` | string, accepted values are: `generic` or `list` | Template type, currently only `generic` and `list` types are supported | | `elements` | (optional) an array of generic template Elements | elements defined by TemplateElement object specification | | `buttons` | (optional) only in case of a template where `type` == `list`, an array of Button objects | the buttons to display in the bottom part of the template. |

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.

| PROPERTY | VALUE | DESCRIPTION | | ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ | | `title` | string | the text to display as title in the template rendering | | `subtitle` | (optional) string | an optional subtitle to display in the template | | `image_url` | (optional) string | a valid URL for an image to display in the template | | `default_action` | (optional) DefaultAction object | an object representing the default action to execute when the template is clicked / tapped | | `buttons` | (optional) an array of Button objects | the buttons to display in the template element. |

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:

| | | :-----------------------------------------------------------------------------------------------: | | A BotResponse message containing only one generic template |

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:

| | | :--------------------------------------------------------------------------------------------------------: | | A BotResponse message containing a carousel of generic templates |

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Vivocha Bot SDK

Table of Contents

| PROPERTY | VALUE | DESCRIPTION | | -------- | ------------------------------------------------------------------------- | ----------------------------------- | | engine | (optional) BotEngineSettings object (see below) | Specific Bot/NLP Platform settings. |

| PROPERTY | VALUE | DESCRIPTION | | -------- | ------------------------------------------------------------------------- | ----------------------------------- | | `engine` | (optional) BotEngineSettings object (see below) | Specific Bot/NLP Platform settings. |