btnexus-hook
Version:
Baseline libary for blackout nexus hooks.
292 lines (229 loc) • 10.5 kB
Markdown
# btNexus hooks
|||
|---|---|
|Author|Marc Fiedler|
|Author|Adrian Lubitz|
|Email|dev@blackout.ai|
|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](https://www.npmjs.com/get-npm)
* [VS Code installed](https://code.visualstudio.com/docs/setup/setup-overview)
* [btNexus Workbench extension installed](https://code.visualstudio.com/docs/editor/extension-gallery)
* [Owner of a btNexus Instance or a btNexus account](https://www.btnexus.ai/)
# 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](https://marketplace.visualstudio.com/items?itemName=btNexus.btworkbench)
--
Once you are set uo, you can now proceed to:
* Make your first Hook Setup: [First Setup](/doc/firstSetup.md)
### onMessage (*mandatory*)
This callback gets triggered whenever the btNexus forwards a message to the hook
**It needs to call the method [say(peer, message)](#say) otherwise the Hook will not respond.**
In ```onMessage``` the following parameters are available:
```js
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.
```js
onInit(){
// use the time to initialize your own variables
}
```
### onReady (*optional*)
Is called when the connection to btNexus was authenticated successfully.
```js
onReady(){
console.log("Hook ready");
}
```
### onError (*optional*)
Gets called when btNexus encounters an error
```js
@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
```js
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*) <a name="say"></a>
```js
@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](#hyperRef) for more infos.
### save (*optional*)
This function saves a key value pair in the btNexus Data.
```js
@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.
```js
@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.
```js
@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.
```js
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 <a name="hyperRef"></a>
Create your own `hyperReference` when you need it.
```JavaScript
{
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"
}
]
}
```
<!-- There are three ways to use `hyperReferences` in your hook: -->
<!-- 1. Use a pre-defined `hyperReference` from within the nexusUi. The only thing you need is the `name` of the `hyperReference` inside your nexus instance.
```JavaScript
complete({
answer: "The cake is a lie!",
hyperReferences: [
this.getHyperReferenceNamed('Website')
]
})
``` -->
<!-- 2. Create your own `hyperReference` when you need it. This allows for more flexibility since not every nexus instance will share the same `hyperReferences`
```JavaScript
complete({
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"}
]
})
``` -->
<!-- 3. Generate a `hyperReference` from existing resources inside of the hook. Assume you have a file in your `templates/` folder called `home.hbs`
```JavaScript
complete({
answer: "The cake is a lie!",
platform: {
hyperReferences: [
this.generateHyperReferenceFor('home')
]
}
})
``` -->
## Platform Actions(*to come*)
<!--
platform Actions are very specific remote procedure calls from within the nexus. Therefore the only way to gain access to a `platformReaction` is to load one directly from the `Brocas service`.
```JavaScript
complete({
answer: "The cake is a lie!",
platform: {
platformActions: [
this.getPlatformReactionNamed('Wave')
]
}
})
``` -->
## 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
```json
{
"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
```JavaScript
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/)