# Javascript API: Listeners/Events

These event will triggers only when Tiledesk Widget fired some event in a specific situation. Once it's up, you'll be able to do something you need in the fanction handler.

```javascript
window.Tiledesk(event_name, handler)
```

Register an event handler to an event type.

## Available events:

| event\_name                        | description                                                                                                     |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **onLoadParams**                   | Fired when the parameters are loaded\*.                                                                         |
| **onInit**                         | Fired when the widget is initialized                                                                            |
| **onAuthStateChanged**             | The event is 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 sending.                                                                               |
| **onAfterMessageSend**             | This event is generated after the message has been sent.                                                        |
| **onOpenEyeCatcher**               | Fired when the callout box is open                                                                              |
| **onClosedEyeCatcher**             | Fired when the callout box is closed                                                                            |
| **onCloseMessagePreview**          | Fired when the user click on close button in message preview while new message is received and widget is closed |
| **onNewConversationComponentInit** | Fired just after a new conversation is initialized                                                              |
| **onBeforeDepartmentsFormRender**  | Fired just before rendering Departments in the Departments view                                                 |
| **onMessageCreated**               | Fired when the widget receive a message                                                                         |
| **onNewConversation**              | Fired when the widget start a new conversation                                                                  |
| **onConversationUpdated**          | Fired when the widget receive a conversation update                                                             |

\*This event will be fired before the tiledesk parameters is loaded. Use this event to change at runtime your Tiledesk settings.

## Initial events lifecycle:

onLoadParams -> onInit -> onAuthStateChanged

The handler will have the signature function(event\_data).

event\_data is a Javascript CustomEvent. More info about CustomEvent [here](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent)

Arguments:

| Parameter   | Type     | Required | Description                                       |
| ----------- | -------- | -------- | ------------------------------------------------- |
| event\_name | String   | YES      | Event name to bind to                             |
| handler     | Function | YES      | Function with the signature function(event\_data) |

## Important payload of event\_data:

| Parameter                | Type   | Description                      |
| ------------------------ | ------ | -------------------------------- |
| detail.default\_settings | Object | the constructor default settings |

**Ex. Logging of 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>
```

**Ex. 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", "andrea.leo@f21.it");

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

**Ex. Widget with welcome message with current date**

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

## onBeforeMessageSend

This event will be fired before the message sending. Use this event to add user information or custom attributes to your chat message.

Important payload of event\_data:

| Parameter      | Type   | Description                    |
| -------------- | ------ | ------------------------------ |
| detail.message | Object | the message that is being sent |

**Ex. Programmatic 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>
```

**Ex. 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

This event is generated after the message has been sent.

Important payload of event\_data:

| Parameter      | Type   | Description               |
| -------------- | ------ | ------------------------- |
| detail.message | Object | the message that was sent |

**Ex:**

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

## onAuthStateChanged

This event is generated when the authentication state changed (Ex: user sign-in, user logout, etc.) Important payload of event\_data:

| Parameter | Type   | Description    |
| --------- | ------ | -------------- |
| detail    | Object | the auth event |

**Auth Event description:**

| Parameter             | Type    | Description                                                                         |
| --------------------- | ------- | ----------------------------------------------------------------------------------- |
| **event**             | string  | Possible values: 'online' when user is logged in, 'offline' when user is logged out |
| **isLogged**          | boolean | Possible values: true if the user is logged, false if not logged                    |
| **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  | The remote widget config parameters obtained from the remote Tiledesk server        |

**Ex. :**

```
<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

This event is generated before rendering the Departments selection View. Use this event if you want to filter the default Departments list based on some conditions.

Important payload of event\_data:

| Parameter          | Type   | Description                          |
| ------------------ | ------ | ------------------------------------ |
| detail.departments | Object | the array of the default Departments |

**Ex. :**

In the following example Departments are filtered based on the current widget language. Actually a Department doesn't provide a specific "language" field. In this example Department language is put in the Department description field. Attention you can modify the departments array only by reference.

```
<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

This event is generated as soon as a new conversation view is rendered. Use this event if you want to execute some actions on a Conversation start.

Important payload of event\_data:

| Parameter        | Type   | Description                                     |
| ---------------- | ------ | ----------------------------------------------- |
| detail.newConvId | Object | the id of the conversation that fired the event |

**Ex. :**

In the following example a hidden message is sent as soon as a conversation starts. Sending a hidden message is useful to fire a bot welcome message, if one is invited in the conversation.

```
<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

This event is generated when the widget receive a message.

Important payload of event\_data:

| Parameter | Type   | Description                   |
| --------- | ------ | ----------------------------- |
| detail    | Object | the message that was received |

**Ex. :**

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

## onConversationUpdated

This event is generated when the widget receive a conversation update.

Important payload of event\_data:

| Parameter | Type   | Description                        |
| --------- | ------ | ---------------------------------- |
| 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>
```