Tiledesk Docs
Search…
Web SDK

Web SDK ver 5.0

Are you interested in the v4 version? Click here.
This guide will show you how to get started as quickly as possible with the Web SDK from Tiledesk. The Web SDK will give businesses and developers the flexibility to build and customize a chat experience that meet their specific design/brand requirements.

Install the Web HTML Widget

To chat with your visitors embed the widget on your site. Copy the following script and insert it in the HTML source between the HEAD tags:
1
<script type="application/javascript">
2
window.tiledeskSettings=
3
{
4
projectid: "6048e8b09818900019fc6141"
5
};
6
(function(d, s, id) {
7
var w=window; var d=document; var i=function(){i.c(arguments);};
8
i.q=[]; i.c=function(args){i.q.push(args);}; w.Tiledesk=i;
9
var js, fjs=d.getElementsByTagName(s)[0];
10
if (d.getElementById(id)) return;
11
js=d.createElement(s);
12
js.id=id; js.async=true; js.src="https://widget.tiledesk.com/v5/launch.js";
13
fjs.parentNode.insertBefore(js, fjs);
14
}(document,'script','tiledesk-jssdk'));
15
</script>
Copied!
To get your TILEDESK_PROJECT_ID go to the Tiledesk Dashboard and click on the Widget item of the menu:

Configuration

Widget version 5.0 supports remote configuration of most parameters directly from the Widget menu of the Dashboard.
You can customize the widget passing the following parameters to window.tiledeskSettings object.
  • projectid. The Tiledesk project id. Find your Tiledesk ProjectID in the Tiledesk Dashboard under the Widget menu.
  • preChatForm: You can require customers to enter information like name and email before sending a chat message by enabling the Pre-Chat form. Permitted values: true, false. The default value is false.
  • align: Make the chat available on the Right or on the Left of the screen. Permitted values: 'right', 'left'. Default value is right.
  • calloutTimer: Proactively open the chat windows to increase the customer engagement. Permitted values: -1 (Disabled), 0 (Immediatly) or a positive integer value. For exmaple: 5 (After 5 seconds), 10 (After 10 seconds).
  • calloutTitle : The title of the callout window.
  • calloutMsg : The message of the callout window.
  • userFullname: Current user fullname. Set this parameter to specify the visitor fullname.
  • userEmail: Current user email address. Set this parameter to specify the visitor email address.
  • welcomeTitle: The welcome title to show on the widget home page.
  • welcomeMsg: Set the widget welcome message. Value type : string
  • widgetTitle: Set the widget title label shown in the widget header. Value type : string. The default value is Tiledesk.
  • startFromHome: If false when loaded the widget starts directly with a new conversation. If true the widget shows the home component. The default value is true.
  • logoChat: The url of the logo to show on the widget home page.
  • lang : With this configuration it is possible to force the widget lang. The widget will try to get the browser lang, if it is not possible it will use the default "en" lang
  • hideHeaderCloseButton: Hide the close button in the widget header. Permitted values: true, false. The default value is false.
  • hideHeaderConversationOptionsMenu: Enable you to show/hide options menu in a conversation header. Permitted values: true, false. Default value: true
  • isOpen: Read-only property. Set this property true in the script to automatically open the widget as soon as it is loaded. Permitted values: true, false. Default value : false.
  • fullscreenMode: if it is true, the chat window is open in fullscreen mode. Permitted values: true, false. Default value : false
  • themeColor: allows you to change the main widget's color (color of the header, color of the launcher button, other minor elements). Permitted values: Hex color codes, e.g. #87BC65 and RGB color codes, e.g. rgb(135, 188, 101)
  • themeForegroundColor: allows you to change text and icons' color. Permitted values: Hex color codes, e.g. #425635 and RGB color codes, e.g. rgb(66, 86, 53)
  • bubbleSentBackground: allow you to change the bubble sent message background color. Permitted values: Hex color codes, e.g. #2a6ac1 and RGB color codes, e.g. rgb(42, 106, 193)
  • bubbleSentTextColor: allow you to change the bubble sent message text color. Permitted values: Hex color codes, e.g. #ffffff and RGB color codes, e.g. rgb(255, 255, 255)
  • bubbleReceivedBackground: allow you to change the bubble received message background color. Permitted values: Hex color codes, e.g. #f7f7f7 and RGB color codes, e.g. rgb(247, 247, 247)
  • bubbleReceivedTextColor: allow you to change the bubble received message text color. Permitted values: Hex color codes, e.g. #1a1a1a and RGB color codes, e.g. rgb(26, 26, 26)
  • fontSize: allow you to change the font size of bubble messages. Value type: string. Default value : "1.4em"
  • buttonFontSize: allow you to change the font size of all the attachment buttons of a message. Value type: string. Default value : "15px"
  • departmentID: to skip departments selection, you can set the department ID upon which the widget must start the new conversation. See the turorial here.
  • isShown: Read only property. This property returns the visibility of the whole widget including the widget ballon. If true the widget is visible otherwise (false) the widget is hidden. Use window.tiledesk.show() and window.tiledesk.hide() methods to change the widget visibility.
  • allowTranscriptDownload: allows the user to download the chat transcript. The download button appears when the chat is closed by the operator. Permitted values: true, false. Default value: false
  • marginX: Set the side margin, left or right depending on the align property. Value type: string. Default value : "20px"
  • marginY: Set the distance from the page bottom margin. Value type: string. Default value : "20px"
  • launcherWidth: Allow you to change launcher width dimension. Value type: string. Default value : "60px"
  • launcherHeight: Allows you to change launcher height dimension. Value type: string. Default value : "60px"
  • baloonImage: Allows you to change baloon image with custom image URL. Value type: string. Minimun size: 60x60px. Allowed image format: *.jpg, *.jpeg, *.jfif, *.JPG, *.JPE.
  • baloonShape: Allows you to change baloon shape with custom dimension . Value type: string. Permitted values: string as top-bottom-right-left dimension, percentage dimension . Default value : "50%"
  • autoStart: Set if the widget performs an automatic anonymous authentication at the startup. Default value : true
  • startHidden: Set if the widget starts in hidden mode. Default value : false
  • persistence: You can specify how the Authentication state persists when using the Tiledesk JS SDK. This includes the ability to specify whether a signed in user should be indefinitely persisted until explicit sign out or cleared when the window is closed. Permitted values: local, session. Default value : local. Local value indicates that the state will be persisted even when the browser window is closed. An explicit sign out is needed to clear that state. Session value indicates that the state will only persist in the current session or tab, and will be cleared when the tab or window in which the user authenticated is closed.
  • showWaitTime: Show the expected response time from your agents in the home widget window. Value type : boolean. The default value is true.
  • showAvailableAgents: Show the available agents with avatar in the home widget window. Value type : boolean. The default value is true.
  • showLogoutOption: Show the logout options in the home widget window. Value type : boolean. The default value is true.
    • showAttachmentButton: Enable you to show/hide attachment button in the footer of a conversation. Permitted values: true, false. Default value: true
  • showAllConversations: Enable you to show/hide the list of all conversations. Permitted values: true, false. Default value: true
  • recipientId: Enable the widget to open a specific conversation. Value type: string
  • poweredBy: Allow you to change home footer description with custom HTML code. Value type: string
  • dynamicWaitTimeReply: Enable you to decide whether or not to share the average response time of his team. Permitted values: true, false. Default value: true
  • openExternalLinkButton: Enable you to open or not a link in an action button externally. Permitted values: true, false. Default value: true
  • soundEnabled: Enable you to allow or not sound when new message arrived. Permitted values: true, false. Default value: true
  • isLogEnabled: Enable the widget log. Value type: boolean. The default value is false.
  • logLevel: Allows you to change the level of the log. Value type: string. Permitted values: ‘ERR’ < ‘WARN’ < ‘INFO’ < ‘DEBUG’. Default value: ‘INFO’

Example 1. Widget with user fullname and email

1
<script type="application/javascript">
2
window.tiledeskSettings =
3
{
4
projectid: "6048e8b09818900019fc6141",
5
userFullname: "Andrea Leo",
6
userEmail: "[email protected]"
7
};
8
(function(d, s, id) {
9
var w=window; var d=document; var i=function(){i.c(arguments);};
10
i.q=[]; i.c=function(args){i.q.push(args);}; w.Tiledesk=i;
11
var js, fjs=d.getElementsByTagName(s)[0];
12
if (d.getElementById(id)) return;
13
js=d.createElement(s);
14
js.id=id; js.async=true; js.src="https://widget.tiledesk.com/v5/launch.js";
15
fjs.parentNode.insertBefore(js, fjs);
16
}(document,'script','tiledesk-jssdk'));
17
</script>
Copied!

Example 2. Widget with preChatForm and left alignment:

1
<script type="application/javascript">
2
window.tiledeskSettings =
3
{
4
projectid: "6048e8b09818900019fc6141",
5
preChatForm: true,
6
align: 'left'
7
};
8
(function(d, s, id) {
9
var w=window; var d=document; var i=function(){i.c(arguments);};
10
i.q=[]; i.c=function(args){i.q.push(args);}; w.Tiledesk=i;
11
var js, fjs=d.getElementsByTagName(s)[0];
12
if (d.getElementById(id)) return;
13
js=d.createElement(s);
14
js.id=id; js.async=true; js.src="https://widget.tiledesk.com/v5/launch.js";
15
fjs.parentNode.insertBefore(js, fjs);
16
}(document,'script','tiledesk-jssdk'));
17
</script>
Copied!

Configuration using URL parameters

You can also pass the above configurations as a Url parameter with the tiledesk_ prefix. For example:
1
https://widget.tiledesk.com/v5/assets/twp/index.html?tiledesk_projectid=<YOUR_PROJECT_ID>&tiledesk_isOpen=true&tiledesk_align=right&project_name=Assistente%20Virtuale&isOpen=true
Copied!

Methods

Open the widget

This will open the widget:
1
window.Tiledesk('open');
Copied!

Minimize the widget

This will minimize the widget:
1
window.Tiledesk('close');
Copied!

Hide the widget

This will hide the widget:
1
window.Tiledesk('hide');
Copied!

Show the widget

This will show the widget:
1
window.Tiledesk('show');
Copied!

Reinitialize the widget

If your app is characterized by very few page refreshes (ie., content is swapped out on the client side but no page refresh happens, Angular, React, jQuery, etc..) and lots of asynchronous JS, you'll need to update Tiledesk when your user's data changes. A reInit call simulates a page refresh, causing Tiledesk to reload the widget and all the configurations.
1
window.Tiledesk('reInit');
Copied!

Restart the widget

This method allow you to restart widget with the same user's data without make a new authentication. This also mantein all the configurations.
1
window.Tiledesk('restart');
Copied!

Signin with anonymously

This method make a signin anonymously
1
window.Tiledesk('signInAnonymous');
Copied!

Signin with JWT Custom Token

This method make a signin using a JWT Custom Token as described here.
1
window.Tiledesk('signInWithCustomToken', customJwt);
Copied!

Make a logout

This will logout the widget:
1
window.Tiledesk('logout');
Copied!

Show callout

This will show the widget callout if it is not open:
1
window.Tiledesk('showCallout');
Copied!

Show or hide the PreChatForm

This parameter configures the PreChatForm visibility:
1
window.Tiledesk('setPreChatForm', true|false);
Copied!

Send a message to a support conversation

This method sends a message to the current support conversation:
1
const recipientId = window.tiledesk.angularcomponent.component.g.recipientId;
2
const recipientFullname = 'Owner';
3
const message = 'hello';
4
const type = 'text';
5
const metadata = {};
6
const attributes = {};
7
window.tiledesk.sendSupportMessage(
8
message,
9
recipientId,
10
recipientFullname,
11
type,
12
metadata,
13
attributes
14
)
Copied!

Send a message to a conversation

This method sends a message to the current conversation:
1
const recipientId = window.tiledesk.angularcomponent.component.g.recipientId;
2
const message = 'hello';
3
const type = 'text';
4
const metadata = {};
5
const attributes = {};
6
const tenant = window.tiledesk.angularcomponent.component.g.tenant;
7
const senderId = window.tiledesk.angularcomponent.component.g.senderId;
8
const senderFullname = 'Guest';
9
const recipientFullname = 'Owner';
10
const additional_attributes = {};
11
const projectid = window.tiledesk.angularcomponent.component.g.projectid
12
const channel_type = "group"
13
window.tiledesk.sendMessage(
14
tenant,
15
senderId,
16
senderFullname,
17
message,
18
type,
19
metadata,
20
recipientId,
21
recipientFullname,
22
additional_attributes,
23
projectid,
24
channel_type
25
)
Copied!

Events

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
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
Arguments:
Parameter
Type
Required
Description
event_name
String
YES
Event name to bind to
handler
Function
YES
Function with the signature function(event_data)

Example 3. Logging of widget events

1
<script type="application/javascript">
2
window.Tiledesk('onBeforeMessageSend', function(event_data) {
3
var message = event_data.detail.message;
4
console.log("onBeforeMessageSend called ", message);
5
});
6
window.Tiledesk('onAfterMessageSend', function(event_data) {
7
var message = event_data.detail.message;
8
console.log("onAfterMessageSend called ", message);
9
});
10
</script>
Copied!

Load Parameters event

This event will be fired before the tiledesk parameters is loaded. Use this event to change at runtime your Tiledesk settings.
Important payload of event_data:
Parameter
Type
Description
detail.default_settings
Object
the constructor default settings
Example 4. Widget with visitor fullname and email from localStorage
1
<script type="application/javascript">
2
//set fullname to localstorage
3
localStorage.setItem("user_fullname", "Andrea from localStorage");
4
localStorage.setItem("user_email", "[email protected]");
5
6
window.Tiledesk('onLoadParams', function(event_data) {
7
window.tiledeskSettings.userFullname = localStorage.getItem("user_fullname");
8
window.tiledeskSettings.userEmail = localStorage.getItem("user_email");
9
});
10
</script>
Copied!
Example 5. Widget with welcome message with current date
1
<script type="application/javascript">
2
window.Tiledesk('onLoadParams', function(event_data) {
3
window.tiledeskSettings.welcomeMsg = " Hello at: " + new Date().toLocaleString();
4
});
5
</script>
Copied!

Before sending messsage

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
Example 6. Programmatic setting custom user metadata
1
<script type="application/javascript">
2
window.Tiledesk('onBeforeMessageSend', function(event_data) {
3
var message = event_data.detail.message;
4
message.attributes.userCompany = "Frontiere21";
5
});
6
</script>
Copied!
Example 7. Add a custom attribute (page title) to the message.
1
<script type="application/javascript">
2
window.Tiledesk('onBeforeMessageSend', function(event_data) {
3
var message = event_data.detail.message;
4
message.attributes.pagetitle = document.title;
5
});
6
</script>
Copied!

After messsage sent

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
Example 8:
1
<script type="application/javascript">
2
window.Tiledesk('onAfterMessageSend', function(event_data) {
3
var message = event_data.detail.message;
4
console.log("onAfterMessageSend called ", message);
5
});
6
</script>
Copied!

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
Example 9:
1
<script type="application/javascript">
2
window.Tiledesk('onAuthStateChanged', function (event_data) {
3
console.log("onAuthStateChanged ----> ", event_data.detail.event);
4
if (!event_data.detail.isLogged) {
5
console.log("NOT logged");
6
window.tiledesk.signInWithCustomToken("JWT CHANGE IT");
7
} else {
8
console.log("logged in");
9
}
10
});
11
</script>
Copied!

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
Example 10:
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.
1
<script type="application/javascript">
2
window.Tiledesk('onBeforeDepartmentsFormRender', function(event_data) {
3
var departments = event_data.detail.departments;
4
var lang = window.tiledesk.angularcomponent.component.g.lang;
5
if (lang && lang === 'en') {
6
var new_deps = departments.filter(function(dep) {
7
if (dep.description && dep.description.includes('English')) {
8
return dep;
9
}
10
});
11
} else {
12
var new_deps = departments.filter(function(dep) {
13
if (dep.description && dep.description.includes('French')){
14
return dep;
15
}
16
});
17
}
18
19
//modify the department array by reference
20
21
departments.length=0; //empty the array
22
console.log("new_deps",new_deps);
23
new_deps.forEach(function(d) { //populate the department array
24
departments.push(d);
25
});
26
27
});
28
</script>
Copied!

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
Example 11:
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.
1
<script type="application/javascript">
2
window.Tiledesk('onNewConversationComponentInit', function(event_data) {
3
const message = 'hello';
4
const recipientId = event_data.detail.newConvId;
5
const recipientFullname = 'Owner';
6
const type = 'text';
7
const metadata = {};
8
const attributes = {test:'test attributes', subtype: 'info'};
9
window.tiledesk.sendSupportMessage(
10
message,
11
recipientId,
12
recipientFullname,
13
type,
14
metadata,
15
attributes
16
)
17
});
18
}
19
</script>
Copied!

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
Example 12:
1
<script type="application/javascript">
2
window.Tiledesk('onMessageCreated', function(event_data) {
3
var message = event_data.detail;
4
console.log("TRIGGER onMessageCreated -> ", message);
5
});
6
</script>
Copied!

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:
1
<script type="application/javascript">
2
var now = Date.now();
3
window.Tiledesk('onConversationUpdated', function(event_data) {
4
var dateConvUpdate = event_data.detail.conversation.timestamp
5
console.log(" TRIGGER onConversationUpdated -> ", event_data.detail.conversation);
6
console.log("now-> ", now);
7
console.log("dateConvUpdate-> ", dateConvUpdate);
8
if(now < dateConvUpdate){
9
console.log(" New conversation!!!");
10
}
11
});
12
</script>
Copied!

Enabling authenticated visitors in the Chat widget

You can configure your widget to authenticate visitors using the Javascript API and JWT token. More info Widget Authentication
Last modified 28d ago