btNexus hooks

||| |---|---| |Author|Marc Fiedler| |Author|Adrian Lubitz| |Email|[email protected]| |Latest stable library version | 2.3.0 | |Required btNexus versions| >= 2.2.4926 |

License

|Copyright|License |---|---| |(c)2018 Blackout Technologies, Bremen |GPLv3|

Hooks are custom scripts that can be integrated into any point within a dialog to access external or living data. Any information and data that is not part of the original A.I. training falls under the category living data that can be integrated in a flow of a dialog with the help of btNexus Hooks

Introduction

The btNexus by Blackout Technologies is a platform to create Digital Assistants and to connect them via the internet to multiple platforms. Those platforms can be websites, apps or even robots. The btNexus consists of two major parts, the first is a network that can connect multiple micro service and the second is a sophisticated UI, that enables the user to train A.I.-based Digital Assistants. Those Digital Assistants can be anything, support chatbots or even robot personalities. Every user has one or multiple btNexus Instances, which means, it's their workspace. One btNexus Instance can host multiple personalities.

Prerequisites

What you need to get started with Hook development

• Node.JS / NPM installed on your PC
• VS Code installed
• btNexus Workbench extension installed
• Owner of a btNexus Instance or a btNexus account

Getting started

set up workspace

After installing the btNexus Workbench extension into your Visual Studio Code IDE press Ctrl+Shift+P or F1 to show all commands. Type in btNexus to see all commands asociated with the btNexus Workbench. Choose NEW and following the instructions. You should end up with an example project.

You can find the btNexus Workbench here: VSC btNexus Workbench

--

Once you are set uo, you can now proceed to:

• Make your first Hook Setup: First Setup

onMessage (mandatory)

This callback gets triggered whenever the btNexus forwards a message to the hook It needs to call the method say(peer, message) otherwise the Hook will not respond. In onMessage the following parameters are available:

onMessage(text, intent, language, entities, slots, branch, peer)

• text String with the original user phrasing
• intent String with the name of the classified intent
• language String Language tag of the language that the end-user is currently speaking in
• entities Array of Objects that contain the name and the Value of each extracted entity: {name: "EntityName", value: "EntityValue"}
• slots Array of Strings that contain all extracted slots
• branch String, name of dialog branch that triggered the Hook
• peer Object: btNexus Peer, used for responding to messages

onInit (optional)

This function is called when the Hook was Initialized. After onInit, the Hook will connect to btNexus.

    onInit(){
        // use the time to initialize your own variables
    }

onReady (optional)

Is called when the connection to btNexus was authenticated successfully.

    onReady(){
        console.log("Hook ready");
    }

onError (optional)

Gets called when btNexus encounters an error

    @param error, String, contains the error message
    @param code, Integer that contains the error code
    onError(error, code){ 
        console.dir(error);
        console.log("Error: "+error+" code: "+code); 
    }

onDisconnected (optional)

Gets called when ever the Hook disconnects from the btNexus network

    onDisconnect(){ 
        console.log("Disconnected from btNexus"); 
        console.log("Trying to reconnect..."); 
        // it tries to reconnect every second 
        setTimeout(() => { 
                this.connectToBtNexus(); 
        }, 5000); 
    }

API

You can use the following functions to exploit the full potential of your hook.

say (mandatory)

    @param peer, Object, the peer object from the onMessage callback
    @param message, Object, contains the message, which should be send as response
    say(peer, message)

The message Object needs to have at least the field answer. To include hyperreferences you need to use the hyperReferences field. See hyperReferences for more infos.

save (optional)

This function saves a key value pair in the btNexus Data.

    @param key, String, the key in the btNexus Data
    @param value, Object, an Object which should be saved
    @param callback, function pointer, a callback which should be triggered on the response
    save(key, value, callback)

put (optional)

This function adds a value to an array of data for a specific key in the btNexus Data. If there is no value to the specific key or it is not an array it will be overwritten.

    @param key, String, the key in the btNexus Data
    @param value, Object, an Object which should be saved
    @param callback, function pointer, a callback which should be triggered on the response
    put(key, value, callback)

load

This function loads a value from the btNexus Data.

@param key, String, the key in the btNexus Data
@param callback, function pointer, a callback which should be triggered on the response
load(key, callback)

connectToBtNexus

This function can be used for reconnecting the hook.

    connectToBtNexus()

btNexus Tools

In the btNexus world, there are some specific standards you need to follow in order to leverage the maximum use of it's power. One of those are called hyperReferences. What that means is that you can utilise hyperReference objects to reference elements from outside of the scope of your hook. Links, Buttons, Carousels, MailTos and Dialog Buttons are part of the current array of possible object types for a hyperReference.

Another tool that you can utilize is platformActions. These objects are designed for the platform interface that you are using, your personality communicates with humans: The HMI (Human Machine Interface) if you will. platformActions are much more complex as they transport not only context information for the HMI but can also contain telemetry, geometry, or odometry data for more complex interfaces.

Hyper References

Create your own hyperReference when you need it.

    {
        answer: "The cake is a lie!",
        hyperReferences: [
            {
                type: "link", 
                blank: true, 
                target: 'http://www.vanschneider.com/wp-content/uploads/2017/01/cake_1200w.jpg', 
                caption: "Get the cake"
            }
        ]
    }

Platform Actions(to come)

btNexus Data

With the btNexus Data, key-value pairs can be saved in btNexus. This data is accessible over the lifetime of a hook.

Handling Languages

If you want to provide multilingual support to your Hook you can do that with the languageDict implementation that comes with the btnexus-hook library.

Each Hook has a member variable called captions. You can access it via this.captions. You can get a language specific phrasing with the []-operator of the captions object.

In order to have a working language dictionary, you need to create a file called captions.json in the root folder of your hook.

Example

    {
        "de-DE": {
            "greeting": [
                "Hi",
                "Hallo",
                "Moin"
            ],
            "whoAreYou": [
                "Wer bist du?",
                "Kennen wir uns?"
            ]
        },
        "en-US": {
            "greeting": [
                "Hi",
                "Hello",
                "Sup"
            ],
            "whoAreYou": [
                "Who are you?",
                "Do we know eachother?"
            ]
        }
    }

If the setup of the captions.json was done correctly, you will be able to access any caption with the []-operator passing the name of the language as a string.

Example Usage

this.captions[language].fallback; // in the above example will return:  "Sorry, I can't find anything." if the language from onMessage is English

Additional Information

Hooks are Node.Js packages and therefore need to fulfil the package requirements of the NPM standart. https://docs.npmjs.com/files/package.json

btNexus is a product of Blackout Technologies, all rights reserved (https://blackout.ai/)