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.

Linking the script

Add this line to the head of your index.html file:

<script type="text/javascript" src=https://repository.promethist.ai/dist/bot-service.js></script>

Instancing the bot

In your JavaScript code, add this:

const Bot = window.botService.default
const bot = Bot(
true, // autostart
false, // called from Kotlin
undefined // JWT token


  • Port URL (Boolean) - 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 by dispatching SLEEPINGClickEvent on the document (see the "Controlling the bot" section).

  • 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

Implementing callbacks

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 attached to the bot object before starting the conversation. The function attaching is done by calling e.g.

// With arguments
bot.setStatus = newState => {
setState(newState); // Your method
// Without arguments
bot.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 bot.x properties listed below must be defined and callable.

Below is the list of needed functions:



Called when

What is handled


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.status

to see the current bot status


type - String, “sent“ or “received” text - String, content of the message image - optional String, URL of image background - optional String, URL of image

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.


logs - array of Strings

Once a turn

Print technical logs

from the backend


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


error - object

If an error occurs on the backend

Handle the error


When the

conversation ends

Reflect the end on the GUI


In the beginning of the conversation

Return object with

client attributes such as

location or whether

the client has a screen


In the beginning of the conversation

Return session ID

(String in UUID format)


In the beginning of the conversation

Return voice name (String)

which should be used for the conversation (undefined

to use dialogue default)


node - Int, ID of node

Once per bot message

Used in editor to track the conversation progress in the dialogue tree


sound - String

On bot ready (if autostart is false)

Play "bot ready" sound

Launching the bot

Start the conversation by calling

'xy', // language
true, // input audio
true, // output audio
'#intro', // starting message
true, // mask signals
['error'], // allowed sounds
false, // save session


  • 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 #intro or #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, recognized and sleep.

  • 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 attempt to start the dialogue. 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.

Controlling the bot

The bot can also be controlled by calling certain methods

// With parameters
// Without parameters

Method name




Ends the conversation


Pauses current bot

utterance (if playing)


Resumes current bot

utterance (if paused)


state - current bot state (String)

Turns audio input on and off


state - current bot state (String)

Turns audio output on and off


text - text to send (String)

audioOn - true (boolean)

Sends text input to the bot

instead of audio


state - current bot state (String)

Simulates button click, acts differretly based on state