Javascript API: Listeners/Events

These events are triggered when the Tiledesk Widget fires a specific event. Register an event handler with:

window.Tiledesk(event_name, handler)

Register an event handler to an event type. The handler signature is function(event_data), where event_data is a JavaScript CustomEvent. More info about CustomEvent: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent

Arguments

• event_name (String, required): Event name to bind to

• handler (Function, required): Function with the signature function(event_data)

Available events

• onLoadParams — Fired when the parameters are loaded*. Use this event to change at runtime your Tiledesk settings.

• onInit — Fired when the widget is initialized

• onAuthStateChanged — Generated when the user logs in or logs out

• onOpen — Fired when the widget is open

• onClose — Fired when the widget is closed

• onBeforeMessageSend — Fired before the message is sent. Use to add user information or custom attributes to the chat message.

• onAfterMessageSend — Generated after the message has been sent.

• onOpenEyeCatcher — Fired when the callout box is opened

• onClosedEyeCatcher — Fired when the callout box is closed

• onCloseMessagePreview — Fired when the user clicks the close button in message preview while a new message is received and the widget is closed

• onNewConversationComponentInit — Fired just after a new conversation is initialized

• onBeforeDepartmentsFormRender — Fired just before rendering Departments in the Departments view (useful to filter the default Departments list)

• onMessageCreated — Fired when the widget receives a message

• onNewConversation — Fired when the widget starts a new conversation

• onConversationUpdated — Fired when the widget receives a conversation update

*This event (onLoadParams) will be fired before the tiledesk parameters are loaded. Use this event to change at runtime your Tiledesk settings.

Initial events lifecycle

1

onLoadParams -> onInit -> onAuthStateChanged

The initial event lifecycle follows this sequence:

1. onLoadParams

2. onInit

3. onAuthStateChanged

Each event handler receives a single argument: event_data (a JavaScript CustomEvent).

Important payload of event_data

Common important payload values

• detail.default_settings (Object): the constructor default settings (window.tiledeskSettings)

Examples

Logging widget events

<script type="application/javascript">
    window.Tiledesk('onBeforeMessageSend', function(event_data) {
      var message =  event_data.detail.message;
      console.log("onBeforeMessageSend called ", message);
    });
    window.Tiledesk('onAfterMessageSend', function(event_data) {
      var message =  event_data.detail.message;
      console.log("onAfterMessageSend called ", message);
    });
</script>

Widget with visitor fullname and email from localStorage

<script type="application/javascript">
    // set fullname to localstorage
    localStorage.setItem("user_fullname", "Andrea from localStorage");
    localStorage.setItem("user_email", "[email protected]");

    window.Tiledesk('onLoadParams', function(event_data) {
        window.tiledeskSettings.userFullname = localStorage.getItem("user_fullname");
        window.tiledeskSettings.userEmail = localStorage.getItem("user_email");
    });
</script>

Widget with welcome message containing current date

<script type="application/javascript">
    window.Tiledesk('onLoadParams', function(event_data) {
        window.tiledeskSettings.welcomeMsg = " Hello at: " + new Date().toLocaleString();
    });
</script>

Event details and examples by event

onBeforeMessageSend

• Description: Fired before a message is sent. Use to add user information or custom attributes to the chat message.

• Important payload:

  • detail.message (Object): the message that is being sent

Example — programmatically setting custom user metadata:

<script type="application/javascript">
    window.Tiledesk('onBeforeMessageSend', function(event_data) {
        var message =  event_data.detail.message;
        message.attributes.userCompany = "Frontiere21";
    });
</script>

Example — add a custom attribute (page title) to the message:

<script type="application/javascript">
    window.Tiledesk('onBeforeMessageSend', function(event_data) {
        var message = event_data.detail.message;
        message.attributes.pagetitle = document.title;
    });
</script>

onAfterMessageSend

• Description: Generated after the message has been sent.

• Important payload:

  • detail.message (Object): the message that was sent

Example:

<script type="application/javascript">
    window.Tiledesk('onAfterMessageSend', function(event_data) {
        var message =  event_data.detail.message;
        console.log("onAfterMessageSend called ", message);
    });
</script>

onAuthStateChanged

• Description: Generated when the authentication state changes (e.g., user sign-in, sign-out).

• Important payload: detail (Object) — the auth event.

Auth Event description (expandable)

Auth event structure

• event (string) — Possible values: 'online' (user is logged in), 'offline' (user is logged out)

• isLogged (boolean) — true if the user is logged in, false otherwise

• user_id (string) — The current user identifier

• global (object) — An object with all the widget global parameters

• default_settings (object) — The initial widget config parameters (window.tiledeskSettings)

• appConfigs (object) — Remote widget config parameters obtained from the remote Tiledesk server

Example:

<script type="application/javascript">
    window.Tiledesk('onAuthStateChanged', function (event_data) {
        console.log("onAuthStateChanged ----> ", event_data.detail.event);
        if (!event_data.detail.isLogged) {
            console.log("NOT logged");
            window.tiledesk.signInWithCustomToken("JWT CHANGE IT");
        } else {
            console.log("logged in");
        }
    });
</script>

onBeforeDepartmentsFormRender

• Description: Generated before rendering the Departments selection view. Use to filter the default Departments list based on conditions.

• Important payload:

  • detail.departments (Array): the array of the default Departments (modify this array by reference)

Example — filter departments based on widget language (uses department.description to store language in this example):

<script type="application/javascript">
    window.Tiledesk('onBeforeDepartmentsFormRender', function(event_data) {
        var departments = event_data.detail.departments;
        var lang = window.tiledesk.angularcomponent.component.g.lang;
        if (lang && lang === 'en') {
            var new_deps = departments.filter(function(dep) {
                if (dep.description && dep.description.includes('English')) {
                     return dep;
                }
            });
        } else {
            var new_deps = departments.filter(function(dep) {
                if (dep.description && dep.description.includes('French')){
                    return dep;
                }
            });
        }

        // modify the department array by reference
        departments.length = 0;  // empty the array
        console.log("new_deps", new_deps);
        new_deps.forEach(function(d) { // populate the department array
            departments.push(d);
        });
    });
</script>

onNewConversationComponentInit

• Description: Generated as soon as a new conversation view is rendered. Use to execute actions on conversation start.

• Important payload:

  • detail.newConvId (Object): the id of the conversation that fired the event

Example — send a hidden message when a conversation starts (useful to fire a bot welcome message):

<script type="application/javascript">
    window.Tiledesk('onNewConversationComponentInit', function(event_data) {
        const message = 'hello';
        const recipientId = event_data.detail.newConvId;
        const recipientFullname = 'Owner';
        const type = 'text';
        const metadata = {};
        const attributes = {test:'test attributes', subtype: 'info'};
        window.tiledesk.sendSupportMessage(
            message,
            recipientId,
            recipientFullname,
            type,
            metadata,
            attributes
        );
    });
</script>

onMessageCreated

• Description: Generated when the widget receives a message.

• Important payload:

  • detail (Object): the message that was received

Example:

<script type="application/javascript">
    window.Tiledesk('onMessageCreated', function(event_data) {
        var message = event_data.detail;
        console.log("TRIGGER onMessageCreated -> ", message);
    });
</script>

onConversationUpdated

• Description: Generated when the widget receives a conversation update.

• Important payload:

  • detail (Object): the conversation that was received

Example:

<script type="application/javascript">
    var now = Date.now();
    window.Tiledesk('onConversationUpdated', function(event_data) {
        var dateConvUpdate = event_data.detail.conversation.timestamp;
        console.log("TRIGGER onConversationUpdated -> ", event_data.detail.conversation);
        console.log("now-> ", now);
        console.log("dateConvUpdate-> ", dateConvUpdate);
        if (now < dateConvUpdate) {
            console.log("New conversation!!!");
        }
    });
</script>

Related

• Previous: Javascript API: Attributes — https://developer.tiledesk.com/widget/attributes

• Next: Widget Authentication — https://developer.tiledesk.com/widget/auth

Last updated 2 years ago