Public JS API

This document describes the public JavaScript API available to clients for controlling the behavior of the Teletype widget.

Custom JavaScript Events teletype.*

To track information, clients have access to a number of JavaScript events they can subscribe to:

Widget loaded and ready

document.addEventListener('teletype.ready', function() {
    // Widget is ready, and the global object window._teletypeWidget is available for interaction 
});

Widget open and close

Example:

document.addEventListener('teletype.opened', function() {
    // Handler for widget open event
});

document.addEventListener('teletype.closed', function() {
    // Handler for widget close event
});

Person started a new dialog

Important! This refers specifically to a new dialog, meaning the very first interaction. If the current interaction is closed and the person starts a new one, this event will not be triggered.

document.addEventListener('teletype.dialogStarted', function(e) {
    // New dialog started. The event contains information about the message
});

Person sent a new message

document.addEventListener('teletype.messageSent', function(e) {
    // New message sent. The event contains information about the message
});

Message received from operator in the widget

document.addEventListener('teletype.messageReceived', function(e) {
    // Message received from operator. The event contains information about the message
});

Operator closed the dialog

document.addEventListener('teletype.dialogClosed', function() {
    // Handler for dialog closure
});

Person rated the dialog

document.addEventListener('teletype.dialogRated', function(e) {
    // Handler for dialog rating. The event contains information about the rating
});

Person clicked on a channel button

document.addEventListener('teletype.channelClicked', function(e) {
    // Handler for channel click. The event contains information about the channel
});

Global Teletype Widget Object

All interaction with the Teletype widget is done through the global object _teletypeWidget. It is created when the widget loads.
After the widget loads on the client’s web page, it dispatches a custom event named teletype.ready, which notifies all callbacks that it is time to interact with the Teletype widget to pass data to it.

Sending person data

To send user personal data, the client needs to use the setPersonData method of the global object _teletypeWidget.
Here is the interface of the object that should be passed to this method:

interface AdditionalPersonInfo {
    name?: string;
    email?: string;
    avatar?: string;
    phone?: string;
    payload?: { [key: string]: string; };
}

Example:

window.addEventListener('teletype.ready', function() {
    _teletypeWidget.setPersonData({
        email: 'hello@mail.ru',
        name: 'John Doe',
        phone: '+7111111111',
        avatar: 'https://www.gravatar.com/avatar/123',
        payload: {
            foo:  'bar'
        }
    });
});

Setting greeting messages

Sometimes it is necessary to set greeting messages in addition to invitations. For this, the client can use the greetingMessages method of the global object _teletypeWidget, which accepts an array of strings:

_teletypeWidget.greetingMessages(['Hello', 'My name is Ivan', 'I will help you with your question']);

This code example will generate three separate messages from the bot operator.

Programmatic opening and closing of the widget

To manipulate the widget’s state, the client can use the show and hide methods of the global object _teletypeWidget.

Example:

$(document).on("click", "#custom_widget_opener_button", function() {
    window._teletypeWidget.show();
});

Additionally, the Teletype Widget generates custom events for opening or closing the widget.

Example:

window.addEventListener('teletype.opened', function() {
    // Handler for widget open event
});

window.addEventListener('teletype.closed', function() {
    // Handler for widget close event
});

Setting a predefined message in the message input field

If clients want to pre-fill the widget’s message input, they can use the setMessage method of the global object _teletypeWidget, which accepts a string as the message:

Example:

$(document).on("click", "#need_help", function() {
    window._teletypeWidget.setMessage('Need help!');
    window._teletypeWidget.show();
});

Hide the Teletype widget call button

If clients do not want to show the default Teletype widget button, they can hide it by defining a global variable on the window object named teletypeButton set to ‘invisible’ to hide the Teletype widget button.

Example:

    window.teletypeButton = 'invisible';

Force online chat language regardless of browser settings

For an online chat in Russian, add to the chat setup code

window.teletypeLanguageForced = 'ru';

For an online chat in English, add to the chat setup code

window.teletypeLanguageForced = 'en';

Customizing the icon for the Teletype widget call button

To change the default Teletype widget button, you need to override it by defining a global variable on the window object named teletypeButtonUrl, which should be set to the relative path to the icon located on the same host, for example, ‘/assets/icons/cu_teletype.svg’.
You can also set the top margin for this icon via a window property named teletypeButtonMarginTop. This value overrides the default margin, which is 11px. Example: ‘20px’.

Example:

window.teletypeButtonUrl = '/assets/icons/cu_teletype.svg';
window.teletypeButtonMarginTop = '20px';