Web client
This guide describes how to attach the Promethist JS client to your web application.
Please check out also this article to better understand how the communication between client and server works.
There are two ways to link the library to your application. For simpler apps, add this line to the head of your
index.html file:<script type="text/javascript" src=https://bot.flowstorm.ai/service.js></script>
Alternatively, you can use a package manager such as Yarn or NPM. Create a file named
.npmrc containing this (or add to your existing one):@flowstorm:registry=https://gitlab.com/api/v4/projects/23512224/packages/npm/
Then, add the dependency:
yarn add @flowstorm/bot-service
# or
npm install @flowstorm/bot-service
If you linked the package, in your HTML, add this to your JavaScript code:
const Bot = window.botService.default
or if you used NPM/Yarn, add this:
import Bot from '@flowstorm/bot-service';
Then, instantiate the bot object:
const bot = Bot(
'https://core.flowstorm.ai',
'sender',
true, // autostart
clientCallback,
false, // called from Kotlin
undefined // JWT token
);
Arguments:
- Core URL (String) - URL of the back-end system
- Device ID (String)- Identifier of the client
- Autostart (Boolean) - Whether the bot should start the conversation immediately after opening the socket. If
false, the conversation must be started manually by callingbot.handleOnTextInput('#intro', false)(see the "Controlling the bot" section). - Callback provider (object) - contains functions which the bot executes in certain situations. See the "Implementing callbacks" section for complete specification.
- Kotlin (Boolean) - whether the bot is linked from Kotlin code
- Token (String) - JWT token identifying the user. If
undefined, the conversation will start in anonymous mode
There are certain functions which are called in the bot code, but are not implemented there. They serve for allowing the front-end to react to certain events during the conversation. For the client to work correctly, they must be implemented in your web application code and passed to the bot object on creation. Attaching the functions to the object is done by calling e.g.
const clientCallback = {};
// With arguments
clientCallback.setStatus = newState => {
setState(newState); // Your method
};
// Without arguments
clientCallback.getVoice = this.getVoice; // this.getVoice = your method
The functions in your applications can have arbitrary name and, with the exception of the three
get methods, may even be empty, but all the properties listed below must be defined and callable.Below is the list of needed functions:
Name | Parameters | Called when | What is handled |
setStatus | newState - object with String field status | Whenever the bot changes status | Whenever the bot changes status, this method is called so that the front end can reflect this. Inspect newState.statusto see the current bot status. Note that you should keep track of the status on your app's level to use it in certain functions. |
addMessage | type - String, “sent“ or “received”
text - String, content of the message
image - optional String, URL of image
background - optional String, URL of image signal - String, user signal starting with # | Whenever a message comes (multiple times a turn from bot, once a turn from the user) | In this callback, handle displaying the message and image if it is included. |
addLogs | logs - array of Strings | Once a turn | Print technical logs from the backend |
addVideo | video - String, URL of the video callback - function to execute once the video finishes | If the turn contains a video | Display a video in the UI |
onError | error - object | If an error occurs on the backend | Handle the error |
onEnd | | When the conversation ends | Reflect the end on the GUI |
getAttributes | | In the beginning of the conversation | Return object with client attributes such as location or whether the client has a screen |
getUUID | | In the beginning of the conversation | Return session ID (String in UUID format) |
getVoice | | In the beginning of the conversation | Return voice name (String) which should be used for the conversation ( undefined to use dialogue default) |
focusOnNode | node - Int, ID of node | Once per bot message | Used in editor to track the conversation progress in the dialogue tree |
handleCommand | command - String, command name code - String, command payload | Whenever there is a command in the dialogue | Respond with the client to the command |
play | sound - String | On bot ready (if autostart is false) | Play "bot ready" sound |
Start the conversation by calling
bot.init(
'xxxxxxxxxxxxxxxxxxxxxxx',
'xy', // language
true, // input audio
true, // output audio
'#intro', // starting message
true, // mask signals
['error'], // allowed sounds
false, // save session
)
Arguments:
- Application key (String) - Identifier of the dialogue which the client should conduct
- Language (String) - Two-letter code for the language for the conversation
- Default input audio (Boolean) - Whether the bot should listen to audio input. If
false, the user will be able to communicate with the bot only by text. - Default output audio (Boolean) - Whether the bot should play its utterances as audio. If
false, no audio will be played, including the status sounds. - Starting message (String) - Initializing signal for the conversation
- Mask signals (Boolean) - Whether the signals from user (such as
#introor#silence) should be displayed in the conversation log. - Allowed sounds (Array of Strings) - List of status sounds which are allowed to play during the conversation. The available sounds are
intro,error,listening,recognizedandsleep. - Save session (Boolean) - If the recording fails, the client might (based on this setting) save the session by turning off the input audio. The conversation then continues in text-only mode.
After calling this, the bot will open a socket to the server. If
autoStart was set to true, the conversation will begin. After its first utterance, the browser will ask for microphone permission and if it is granted, it will listen for audio input. If the callbacks are empty, the communication will be only through audio.The bot can also be controlled by calling certain methods
// With parameters
bot.click('LISTENING');
// Without parameters
bot.pause();
Method name | Arguments | Purpose |
onStopClick | | Ends the conversation |
pause | | Pauses current bot utterance (if playing) |
resume | | Resumes current bot utterance (if paused) |
inAudio | state - current bot state (String) | Turns audio input on and off |
outAudio | state - current bot state (String) | Turns audio output on and off |
handleOnTextInput | text - text to send (String) audioOn - true (boolean) | Sends text input to the bot instead of audio |
click | state - current bot state (String) | Simulates button click, acts differretly based on state. RESPONDING - skips the current utterances |