Document Title: Orbita Chatbot V3 Solution

Creation date: 01 Oct 2021

Author: ORBITA

With our newest chatbot release, the Orbita platform has an ‘always open’ connection with end clients. This allows for unique customization and interactions with your users including:

Enabling live agent handling (talk real-time with support agents)
Event triggers; watch when users connect or disconnect to handle events
Push messages to individual clients, or multiple (designated using user groups)
Messaging Routing; Push a message to our NLP, or to a secure 3rd party

Features

Real-time Communication - Messages can be pushed from the server to any and all connected clients, allowing requests and responses to be handled asynchronously.
Customize the Chatbot UI - Use or tweak Orbita’s out-of-the-box UI, or completely customize the chatbot to represent unique branding and layout.
Targeted Messaging - Push communication to singular users or multiple personas with the ability to target message pushes to connected clients.

How do you use it?

To use the Chatbot V3’s capabilities with your existing chatbot.

Login to Experience Manager and Select your project.
Open Experience Designer.

Import the below flow to any Experience Designer tab. Refer How do I export and import flows in Experience Designer

[
    {
        "id": "6add8694.8a85b8",
        "type": "orbita-bot-provider-v2",
        "z": "5b628e93.0b248",
        "name": "",
        "botInParser": "var _ = global.get('lodash');\n// msg.payload.originalRequest.data = {\n//      \"surveyID\":\"10000\"\n// }\nif(msg && msg.req && msg.req.query) {\n    \n    msg.payload.originalRequest.data.surveyID=msg.req.query.surveyId;\n}\n\nvar socketIOId = _.get(msg, 'req.socketIOId', null);\n\nif (socketIOId) {\n    _.set(msg, 'payload.originalRequest.data.socketIOId', socketIOId);\n}\n",
        "botOutParser": "msg.payload.micInput=true;\nmsg.payload.startAlignmentTop = true;\nmsg.enableArrayResponse = true\n",
        "transcriptEnabled": false,
        "ttsconfig": "{\n    \"languageCode\": \"en-US\",\n    \"ssmlGender\": \"MALE\",\n    \"audioEncoding\": \"MP3\"\n}",
        "providerType": "Google",
        "skillConfig": "ac17660e.066ee8",
        "token": "",
        "noerr": 0,
        "nlpData": false,
        "x": 280,
        "y": 200,
        "wires": [["ae629d4c.e2f1b"]]
    },
    {
        "id": "d2b0cf85.5158a",
        "type": "bot-in",
        "z": "5b628e93.0b248",
        "skillConfig": "ac17660e.066ee8",
        "name": "",
        "rules": [],
        "x": 90,
        "y": 200,
        "wires": [["6add8694.8a85b8"]]
    },
    {
        "id": "da9afcc6.1538a",
        "type": "bot-out",
        "z": "5b628e93.0b248",
        "skillConfig": "ac17660e.066ee8",
        "name": "",
        "x": 640,
        "y": 200,
        "wires": []
    },
    {
        "id": "ae629d4c.e2f1b",
        "type": "function",
        "z": "5b628e93.0b248",
        "name": "",
        "func": "msg.payload.directive = {\n    \"type\": \"mainmenu\",\n    \"title\":\"Menu options\",\n    \"buttons\": []\n    }\nreturn msg;",
        "outputs": 1,
        "noerr": 0,
        "x": 450,
        "y": 200,
        "wires": [["da9afcc6.1538a"]]
    }, {
        "id": "6952bc3b.ec7d04",
        "type": "template",
        "z": "5b628e93.0b248",
        "name": "",
        "field": "payload",
        "fieldType": "msg",
        "format": "handlebars",
        "syntax": "mustache",
        "template": "<body>\n    <script src=\"/chatbot/v3/chat.js\"></script>\n    <script>\n        OrbitaChatBotV3.init({\n            projectId: '{{projectId}}',\n            serverUrl: '{{req.headers.x-forwarded-proto}}://{{req.headers.host}}',\n            botContainerId: 'chatWindow',\n            botContentId: 'messages',\n            botInputMessageId: 'input',\n            botSendButtonId: 'orbita-send-button',\n            botMicId: 'chatMic',\n            botSpeakerId: 'un-mute',\n            botMenuId: 'chatMenu',\n            botIcon: 'chat-icon',\n            botClose: 'menu',\n            customData: {\n                chooseFlow: \"\"\n            },\n            botSettings: {    \n                elementId: 'orbitabot',\n                template: 'default'  \n            }\n        });\n    </script>\n</body>",
        "output": "str",
        "x": 460,
        "y": 160,
        "wires": [["2d48a5d5.c4859a"]]
    }, {
        "id": "2d48a5d5.c4859a",
        "type": "http response",
        "z": "5b628e93.0b248",
        "name": "",
        "statusCode": "",
        "headers": {},
        "x": 630,
        "y": 160,
        "wires": []
    }, {
        "id": "b2b415ed.a9a7e8",
        "type": "http in",
        "z": "5b628e93.0b248",
        "name": "",
        "url": "/v3Bot",
        "method": "get",
        "upload": false,
        "swaggerDoc": "",
        "x": 120,
        "y": 160,
        "wires": [["6a5a2a23.743f64"]]
    }, {
        "id": "c9814ead.31e13",
        "type": "comment",
        "z": "5b628e93.0b248",
        "name": "v3Bot View",
        "info": "",
        "x": 100,
        "y": 120,
        "wires": []
    }, {
        "id": "6a5a2a23.743f64",
        "type": "function",
        "z": "5b628e93.0b248",
        "name": "",
        "func": "const util = global.get('orbitaUtil');\nmsg.projectId = util.getProjectId(node);\nreturn msg;",
        "outputs": 1,
        "noerr": 0,
        "x": 310,
        "y": 160,
        "wires": [["6952bc3b.ec7d04"]]
    }, {
        "id": "ac17660e.066ee8",
        "type": "alexa-skill-config",
        "skillname": "Demo Project",
        "projectId": "6185191debfd8c0075d6c880",
        "intents": "[]",
        "skillstate": "fromsession"    }, {
        "id": "slots",
        "type": "slots",
        "z": "",
        "slots": []
    }
]

Following the above steps will create a new flow in the Experience Designer as shown below.

Add cdnjs.cloudflare.com to the whitelist. 3.2.26 Whitelisting

Coming from version 2 of the bot

Bot In Node

The Bot In node listens to any pushes from the connected clients. Technically, receives socket events from the webpage.

Bot Out Node

Emits a message to the specified client connected (SocketID). Technically, sends socket events to the webpage.

Connected Bots

The Connected Bots node will return an array of all connected clients (socket IDs) at the project level.

No iframes

The Chatbot V3 is not dependent on an iframe to integrate the chatbot into a webpage.

Template node

The required fields in this node are projectId, serverUrl.
The botSettings property helps in selecting the v3 chatbot setting.

botSettings: { elementId: 'orbitabot', template: 'default' }

The property template inside the botSettings object will determine which Bot setting the user wants to connect for the Bot (from the Experience manager Develop > Chatbot Settings). If this property is not populated, the Default bot setting will be used.
The elementId by default is 'orbitabot'. This determines where to inject the template created in the Bot settings. If the elementId is not mentioned, the default values will be injected.

For users who do not use the botSettings functionalities,

Add botSettings: false in the template node code
Set botContainerId: 'bot-v3' in the template node code

If the user wants to use the botSettings functionality

they must change the below properties to these values,

botContainerId: 'chatWindow'
botSettings: {elementId: 'orbitabot',template: 'default'} //optional

Comment out the below function in the old code, (this is deprecated)

OrbitaBotPlugins.BotPlugin.init({
            botId:'bot-v3',
            width: '300px',
            height: '600px',
        });

isCustomUi property is removed. All the element Id properties are made optional. If not specified, default values will be set.

Sample template:

<html>
<head>
    <title>Orbita Bot Test</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" integrity="sha512-1ycn6IcaQQ40/MKBW2W4Rhis/DbILU74C1vSrLJxCq57o941Ym01SwNsOMqvEBFlcgUa6xLiPY/NS5R+E6ztJQ==" crossorigin="anonymous" referrerpolicy="no-referrer" />
</head>
<body>
    <script src="/chatbot/v3/chat.js"></script>
    <script>
        OrbitaChatBotV3.init({
            projectId: '{{projectId}}',
            serverUrl: '{{req.headers.x-forwarded-proto}}://{{req.headers.host}}',
            botContainerId: 'chatWindow',
            botContentId: 'messages',
            botInputMessageId: 'input',
            botSendButtonId: 'orbita-send-button',
            botMicId: 'chatMic',
            botSpeakerId: 'un-mute',
            botMenuId: 'menu-icon',
            botIcon: 'chat-icon',
            botClose: 'menu',
            customData: {
                chooseFlow: ""
            },
            botSettings: {    
                elementId: 'orbitabot',
                template: 'default'
            }
        });
    </script>
</body>
</html>

Sample with attributes:

<html>
    <head>
    <title>Bot Plugin test</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" integrity="sha512-1ycn6IcaQQ40/MKBW2W4Rhis/DbILU74C1vSrLJxCq57o941Ym01SwNsOMqvEBFlcgUa6xLiPY/NS5R+E6ztJQ==" crossorigin="anonymous" referrerpolicy="no-referrer" />
    </head>
    <body>
        <div
        data-orbita-init='chatbot'
        data-orbita-project-id='{{projectId}}'
        data-orbita-server-url='{{req.headers.x-forwarded-proto}}://{{req.headers.host}}'
        data-orbita-bot-container-id='chatWindow'
        data-orbita-bot-content-id='messages'
        data-orbita-bot-input-message-id = 'input'
        data-orbita-bot-send-button-id = 'orbita-send-button'
        data-orbita-bot-mic-id = 'chatMic'
        data-orbita-bot-speaker-id = 'un-mute'
        data-orbita-bot-menu-id = 'menu-icon'
        data-orbita-bot-icon = 'chat-icon'
        data-orbita-bot-close = 'menu'
        data-orbita-custom-data = '{"chooseFlow": ""}'
        data-orbita-bot-Settings='{"elementId": "orbitabot", "template": "default"}'></div>
        <script src="/chatbot/v3/chat.js"></script>
    </body>
</html>

Whitelisting

To successfully launch Chatbot V3 from your environment, you have to whitelist the below domains. 3.2.26 Whitelisting

https://cdn.jsdelivr.net
https://cdnjs.cloudflare.com
https://code.jquery.com
https://cdn.jsdelivr.net
https://cdn.socket.io

Monitoring conversations using Chatbot V3

Using Chatbot V3, you can have a Chatbot Admin to monitor the chatbot users' conversations.

Sending messages to all connected clients (all SocketIDs)

As a Chatbot Admin, you can send notifications or messages to all the connected clients.

To send out a custom message;

Import the below code.

[
    {
        "id": "cbd070ff.8e9ba",
        "type": "function",
        "z": "e14ca34d.06aff",
        "name": "Send Message to All",
        "func": "msg.payload = {\n    \"text\" : \"Hello you are recieving a push message from server!\"\n}\nmsg.socketIOEmit = \"emit\";\nreturn msg;",
        "outputs": 1,
        "noerr": 0,
        "x": 320,
        "y": 340,
        "wires": [
            [
                "4a5617b7.34e358"
            ]
        ]
    },
    {
        "id": "1b78332e.89e5ed",
        "type": "inject",
        "z": "e14ca34d.06aff",
        "name": "",
        "topic": "",
        "payload": "{}",
        "payloadType": "json",
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "x": 110,
        "y": 340,
        "wires": [
            [
                "cbd070ff.8e9ba"
            ]
        ]
    },
    {
        "id": "4a5617b7.34e358",
        "type": "bot-out",
        "z": "e14ca34d.06aff",
        "skillConfig": "496cb5db.ebb6fc",
        "name": "",
        "x": 620,
        "y": 340,
        "wires": []
    },
    {
        "id": "496cb5db.ebb6fc",
        "type": "alexa-skill-config",
        "skillname": "Documentation Flows",
        "projectId": "5cf9249637e124a03087780b",
        "intents": "[]",
        "skillstate": "",
        "disableLogging": false
    },
    {
        "id": "slots",
        "type": "slots",
        "z": "",
        "slots": []
    }
]

Change the content within the text property in the function node.
Trigger the Inject node to send your custom message to all the connected SocketIDs.

Sending messages to one connected client (one SocketID)

As a Chatbot Admin, you can send notifications or messages to all the connected clients.

To send out a custom message to a particular user;

Import the below code.

[
    {
        "id": "db801cd4.83c7c",
        "type": "function",
        "z": "e14ca34d.06aff",
        "name": "Send Message to specific socket id",
        "func": "msg.payload = {\n    \"text\":\"Hello you are lucky today!\"\n}\nmsg.socketIOId = \"KGJsMLK_PwM55QfYAAC_\";\nreturn msg;",
        "outputs": 1,
        "noerr": 0,
        "x": 360,
        "y": 400,
        "wires": [
            [
                "949a42a7.df33"
            ]
        ]
    },
    {
        "id": "949a42a7.df33",
        "type": "bot-out",
        "z": "e14ca34d.06aff",
        "skillConfig": "496cb5db.ebb6fc",
        "name": "",
        "x": 620,
        "y": 400,
        "wires": []
    },
    {
        "id": "8b452e8e.ff63f",
        "type": "inject",
        "z": "e14ca34d.06aff",
        "name": "",
        "topic": "",
        "payload": "{}",
        "payloadType": "json",
        "repeat": "",
        "crontab": "",
        "once": false,
        "onceDelay": 0.1,
        "x": 110,
        "y": 400,
        "wires": [
            [
                "db801cd4.83c7c"
            ]
        ]
    },
    {
        "id": "496cb5db.ebb6fc",
        "type": "alexa-skill-config",
        "skillname": "Documentation Flows",
        "projectId": "5cf9249637e124a03087780b",
        "intents": "[]",
        "skillstate": "",
        "disableLogging": false
    },
    {
        "id": "slots",
        "type": "slots",
        "z": "",
        "slots": []
    }
]

Change the socketID and the message property in the function node.
Trigger the Inject node to send your custom message to that specific SocketIDs.

You can display these custom messages either on the chatbot or as a notification pop up.

Customizations

You can customize the chatbot using the Project side menu > Develop > Chatbot settings > Custom CSS and Custom JS.

Adding Custom JS
- You can inject the JS code via the Custom JS tab as per your use case.

Adding Custom CSS

Embed the Bot in a section

Import the below flow to the Experience designer to have a chatbot in the center of the page.

[
    {
        "id": "b7cf53f8.4464",
        "type": "template",
        "z": "cd6c5936.243d78",
        "name": "",
        "field": "payload",
        "fieldType": "msg",
        "format": "handlebars",
        "syntax": "mustache",
        "template": "<!doctype html>\n<html lang=\"en\">\n<head>\n    <title>Orbita v3 Demo</title>\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n    <style>\n        body #bot-v3.chat-container{\n            display:block;\n        }\n        #bot-v3,\n        #bot-v3 .chatbox{\n            position: fixed;\n            display:block;\n            right: 10px;\n            bottom: 50px;\n            height: 550px;\n            width: 345px;\n            border-radius: 10px;\n            box-shadow: 5px 5px 15px rgb(119 119 119 / 50%);\n            overflow: hidden;\n            z-index: 999;\n            left: calc(50% - 175px);\n            top: 150px;\n        }\n        #bot-v3 #chatLiveChatTrigger {\n            position: absolute;\n            right: 20px;\n            top: 100px;\n            z-index: 999;\n            cursor:pointer;\n        }\n        \n        #bot-v3 #waitingAgent {\n            clear:both;\n            text-align: center;\n        }\n        .chat-icon{\n            display:none !important;\n        }\n\n        body{\n            font-family: sans-serif;\n            background-color:#eee !important;\n        }\n    </style>\n</head>\n<body>\n    <link rel=\"preload\" href=\"https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/all.min.css\" as=\"style\" onload=\"this.onload=null;this.rel='stylesheet'\">\n    <script src=\"/chatbot/v2/adaptive-lib/adaptivecards-templating.min.js\"></script>\n    <script src=\"/chatbot/v2/adaptive-lib/adaptivecards.js\"></script>\n    <script type=\"text/javascript\" src=\"https://unpkg.com/markdown-it/dist/markdown-it.js\"></script>\n    <script src=\"https://cdn.socket.io/3.1.3/socket.io.min.js\" integrity=\"sha384-cPwlPLvBTa3sKAgddT6krw0cJat7egBga3DJepJyrLl4Q9/5WLra3rrnMcyTyOnh\" crossorigin=\"anonymous\"></script>\n    <script src=\"https://cdnjs.cloudflare.com/ajax/libs/jquery/3.6.0/jquery.min.js\" integrity=\"sha512-894YE6QWD5I59HgZOGReFYm4dnWc1Qt5NtvYSaNcOP+u1T9qYdvdihz0PPSiiqn/+/3e7Jo4EaG7TubfWGUrMQ==\" crossorigin=\"anonymous\" referrerpolicy=\"no-referrer\"></script>\n    <script src=\"/chatbot/v3/chat-plugins.js\"></script>\n    <script src=\"/chatbot/v3/chat.js\"></script>\n    <link rel=\"stylesheet\" href=\"/chatbot/v3/style.css\" />\n    <link rel=\"stylesheet\" type=\"text/css\" href=\"https://cdn.jsdelivr.net/npm/daterangepicker/daterangepicker.css\" />\n    <link href=\"https://cdn.jsdelivr.net/npm/bootstrap@5.0.1/dist/css/bootstrap.min.css\" rel=\"stylesheet\">\n    <script>\n        var clickTag = \"https://www.orbita.ai\";\n        var latestResponse = {};\n        function adClick(){\n            window.open(clickTag, `_blank`);\n        }\n        OrbitaBotPlugins.BotPlugin.init({\n            botId:'bot-v3',\n            width: '300px',\n            height: '600px',\n        });\n        OrbitaChatBotV3.init({\n            projectId: \" {{projectId}}\",\n            serverUrl: \" {{req.headers.x-forwarded-proto}}\"+\"://\"+\" {{req.headers.host}}\",\n            isCustomUi: true,\n            botContainerId: 'bot-v3',\n            botContentId: 'messages',\n            botInputMessageId: 'input',\n            botSendButtonId: 'orbita-send',\n            botMicId: 'chatMic',\n            botSpeakerId: 'un-mute',\n            botMenuId: 'menu-icon',\n            botIcon: 'chat-icon',\n            botClose: 'menu',\n            botBannerIcon: 'banner-title'\n        });\n        function afterResponse(responseData) { \n            const myData = {...responseData};\n            latestResponse = myData;\n\n            if (myData.directive && myData.directive.buttons){\n                let buttons = myData.directive.buttons;\n                $('.menu-slider ul').empty();\n                $.each(buttons, function( key, button ){\n                    $('.menu-slider ul').append('<li onClick=\"OrbitaChatBotV3.hook(\\'send_message\\',\\''+button.value+'\\');$(\\'.menu-icon\\').trigger(\\'click\\');\">'+button.text+'</li>');    \n                });\n            }\n\n            if (myData.session && myData.session.chatMode && myData.session.chatMode !== null){\n                $('.chatbox').prepend(`<i id=\"chatLiveChatTrigger\" title=\"End session with agent\" onClick=\"OrbitaChatBotV3.hook('send_message', 'Please end my session');$(this).remove();\" class=\"fas fa-life-ring fa-times-circle lc_enabled\"/>`);\n            }\n        }\n        OrbitaChatBotV3.registerEvent({eventName: \"afterResponse\", callbackFunction: afterResponse});\n        \n        $('.chat input').on('keypress', function (e) {\n          if (e.which == 13) {\n            if (latestResponse.session && latestResponse.session.chatMode && latestResponse.session.chatMode !== null){\n                $('.chat input, .chat button').css('display', 'block');\n            }\n            return false;\n          }\n        });\n\n        OrbitaChatBotV3.hook('connect');\n    </script>\n</body>\n</html>",
        "output": "str",
        "x": 440,
        "y": 160,
        "wires": [["ca48379c.d812b8"]]
    },
    {
        "id": "ca48379c.d812b8",
        "type": "http response",
        "z": "cd6c5936.243d78",
        "name": "",
        "statusCode": "",
        "headers": {},
        "x": 570,
        "y": 160,
        "wires": []
    },
    {
        "id": "6d574e22.32d22",
        "type": "http in",
        "z": "cd6c5936.243d78",
        "name": "",
        "url": "/centerView",
        "method": "get",
        "upload": false,
        "swaggerDoc": "",
        "x": 140,
        "y": 160,
        "wires": [["b186eca9.c0b9e"]]
    },
    {
        "id": "b186eca9.c0b9e",
        "type": "function",
        "z": "cd6c5936.243d78",
        "name": "",
        "func": "const util = global.get('orbitaUtil');\nmsg.projectId = util.getProjectId(node);\nreturn msg;",
        "outputs": 1,
        "noerr": 0,
        "x": 310,
        "y": 160,
        "wires": [["b7cf53f8.4464"]]
    }, {
        "id": "slots",
        "type": "slots",
        "z": "",
        "slots": []
    }
]

Supported Directives on Chatbot V3

Flow Studio Control’s Directives	Experience Designer’s Directives
Choose many option	Autocomplete -- client side
Choose many option with none of the above	Autocomplete -- server side
Choose one option	Bootstrap carousel
Yes/No options	Bootstrap carousel with filter options
Single input control with texbox input type - hidden	Cardlist
Single input control with texbox input type -- single line	Cardlist with filter options
Single input control with texbox input type -- multi line	Html5 - Added properties (id, html, element)
Single input control with input type Date	Adaptive card
Single input control with input type DateTime
Single input control with input type time
Single input control with input type email
Single input control with input type phone number
Rating control

Hierarchy of settings followed on Chatbot V2 holds good for Chatbot V3:
The Bot provider V2 node (Experience Designer) > Flow studio control directive > Chatbot settings (Project Side navigation menu in Experience Manager).