Web SDK v4

Web SDK ver 4.0

This guide shows how to get started quickly with the TileDesk Web SDK. The Web SDK gives businesses and developers the flexibility to build and customize a chat experience to match 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:

<script type="application/javascript">
    window.tiledeskSettings =
        {
            projectid: "YOUR_TILEDESK_PROJECT_ID"
        };
        (function(d, s, id) {
        var js, fjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) return;
        js = d.createElement(s); js.id = id;
        js.src = "https://widget.tiledesk.com/v4/launch.js";
        fjs.parentNode.insertBefore(js, fjs);
        }(document, 'script', 'tiledesk-jssdk'));
</script>

To get your TILEDESK_PROJECT_ID go to the TileDesk Dashboard and click on the Widget item of the menu:

Configuration

Widget version 4.0 supports remote configuration of most parameters directly from the Widget menu of the Dashboard.

You can customize the widget by passing the following parameters to the window.tiledeskSettings object:

• projectid — The TileDesk project id. Find your TileDesk ProjectID in the TileDesk Dashboard under the Widget menu.

• preChatForm — Require customers to enter information (name, email) before sending a chat message. Permitted values: true, false. Default: false.

• align — Position of the chat: 'right' or 'left'. Default: right.

• calloutTimer — Proactively open the chat window. Permitted values: -1 (Disabled), 0 (Immediately) or a positive integer (seconds).

• calloutTitle — The title of the callout window.

• calloutMsg — The message of the callout window.

• userFullname — Visitor fullname.

• userEmail — Visitor email address.

• wellcomeTitle — Welcome title to show on the widget home page.

• wellcomeMsg — Widget welcome message (string).

• widgetTitle — Widget title label shown in the widget header. Default: Tiledesk.

• startFromHome — If false the widget starts directly with a new conversation. If true the widget shows the home component. Default: true.

• logoChat — URL of the logo to show on the widget home page.

• lang — Force the widget language. Widget will try browser lang, otherwise "en".

• hideHeaderCloseButton — Hide the close button in the widget header. Permitted values: true, false. Default: false.

• isOpen — Read-only property. Set true to automatically open the widget when loaded. Permitted values: true, false. Default: false.

• fullscreenMode — Open chat window in fullscreen mode. Permitted values: true, false. Default: false.

• themeColor — Main widget color (header, launcher button, etc.). Permitted values: Hex (e.g. #87BC65) or RGB (e.g. rgb(135,188,101)).

• themeForegroundColor — Text and icons color. Permitted values: Hex or RGB.

• departmentID — To skip department selection, set the department ID to start the conversation on. See the tutorial: https://developer.tiledesk.com/widget/advanced/preset-department

• isShown — Read-only. Returns visibility of the whole widget including launcher. Use window.tiledesk.show() and window.tiledesk.hide() to change visibility.

• allowTranscriptDownload — Allow the user to download the chat transcript (appears when chat closed by operator). Permitted values: true, false. Default: false.

• marginX — Side margin (left or right depending on align). Type: string. Default: "20px".

• marginY — Distance from page bottom. Type: string. Default: "20px".

• autoStart — Whether the widget performs automatic anonymous authentication at startup. Default: true.

• startHidden — Whether the widget starts hidden. Default: false.

• persistence — Authentication persistence: local or session. Default: local. local persists across browser restarts; session clears when tab/window is closed.

• showWaitTime — Show expected response time from agents in the home widget. Type: boolean. Default: true.

• showAvailableAgents — Show available agents with avatar in the home widget. Type: boolean. Default: true.

• showLogoutOption — Show logout option in home widget. Type: boolean. Default: true.

• isLogEnabled — Enable the widget log. Type: boolean. Default: false.

Examples

1

Widget with user fullname and email

<script type="application/javascript">
  window.tiledeskSettings =
      {
          projectid: "5b55e806c93dde00143163dd",
          userFullname: "Andrea Leo",
          userEmail: "[email protected]"
      };

  (function(d, s, id) {
    var js, fjs = d.getElementsByTagName(s)[0];
    if (d.getElementById(id)) return;
    js = d.createElement(s); js.id = id; //js.async=!0;
    js.src = "https://widget.tiledesk.com/v4/launch.js";
    fjs.parentNode.insertBefore(js, fjs);
  }(document, 'script', 'tiledesk-jssdk'));
</script>

2

Widget with PreChatForm and left alignment

<script type="application/javascript">
  window.tiledeskSettings =
    {
      projectid: "5b55e806c93dde00143163dd",
      preChatForm: true,
      align: 'left'
    };
    (function(d, s, id) {
      var js, fjs = d.getElementsByTagName(s)[0];
      if (d.getElementById(id)) return;
      js = d.createElement(s); js.id = id;
      js.src = "https://widget.tiledesk.com/v4/launch.js";
      fjs.parentNode.insertBefore(js, fjs);
    }(document, 'script', 'tiledesk-jssdk'));
</script>

3

Logging of widget events

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

Full example: https://github.com/chat21/chat21-web-widget/blob/master/src/test.html

4

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.tileDeskAsyncInit = function() {
   window.tiledesk.on('onLoadParams', function(event_data) {
      window.tiledeskSettings.userFullname = localStorage.getItem("user_fullname");
      window.tiledeskSettings.userEmail = localStorage.getItem("user_email");
   });
  }
</script>

Full example: https://github.com/chat21/chat21-web-widget/blob/master/src/test.html

5

Widget with welcome message showing current date

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

Configuration using URL parameters

You can also pass the above configurations as URL parameters using the tiledesk_ prefix. For example:

https://widget.tiledesk.com/v4/index.html?tiledesk_isOpen=true&tiledesk_align=right

Methods

Open the widget

window.tiledesk.open();

Minimize the widget

window.tiledesk.close();

Hide the widget

window.tiledesk.hide();

Show the widget

window.tiledesk.show();

Reinitialize the widget

If your app performs few page refreshes (single-page apps: Angular, React, etc.) and user data changes dynamically, call reInit to simulate a page refresh and reload the widget and configurations.

window.tiledesk.reInit();

Signin with JWT Custom Token

Signin using a JWT custom token as described here: https://developer.tiledesk.com/widget/auth

window.tiledesk.signInWithCustomToken(customJwt);

Logout

window.tiledesk.logout();

Show or hide the PreChatForm

window.tiledesk.setPreChatForm(true|false);

Send a message to a support conversation

const recipientId = window.tiledesk.angularcomponent.component.g.activeConversation
const message = 'hello';
const type = 'text';
const metadata = {};
const attributes = {};
window.tiledesk.sendSupportMessage(
    message,
    recipientId,
    type,
    metadata,
    attributes
)

Events

tileDeskAsyncInit

tileDeskAsyncInit is called when the basic APIs of the widget are loaded. Inside tileDeskAsyncInit the object window.tiledesk is defined and can be used.

window.tiledesk.on(event_name, handler)

Register an event handler for an event type. Handler signature: function(event_data). event_data is a JavaScript CustomEvent (see: https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent/CustomEvent).

Available events

• onLoadParams — Fired when the parameters are loaded.

• onInit — Fired when the widget is initialized.

• onAuthStateChanged — Fired 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 message sending.

• onAfterMessageSend — Fired after a message has been sent.

• onOpenEyeCatcher — Fired when the callout box is open.

• onClosedEyeCatcher — Fired when the callout box 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 receives a message.

• onConversationUpdated — Fired when the widget receives a conversation update.

Initial events lifecycle: onLoadParams -> onInit -> onAuthStateChanged

Examples for events

Before sending message

This event fires before a message is sent. Use it to add user information or custom attributes to the chat message. event_data.detail is the message being sent.

Example — add custom user metadata:

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

Example — add page title as a custom attribute:

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

After message sent

This event is generated after the message has been sent. event_data.detail is the message that was sent.

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

onAuthStateChanged

Fired when authentication state changes (sign-in, logout, etc.). event_data.detail contains:

• event (number) — Possible values: 0 (wasn't logged, with autoStart false), 200 (already logged), 201 (new login), 400 (error), -2 (from reinit), -1 (from logout).

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

• user_id (string) — Current user identifier.

• global (object) — Widget global parameters.

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

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

Example:

<script type="application/javascript">
  window.tileDeskAsyncInit = function() {
    window.tiledesk.on('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

Fired before rendering the Departments selection view. Use it to filter the default Departments list based on conditions. event_data.detail.departments contains the array of default Departments.

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

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

onNewConversationComponentInit

Fired when a new conversation view is rendered. Use it to execute actions on conversation start. event_data.detail.newConvId is the conversation id.

Example — send a hidden message when a conversation starts:

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

onMessageCreated

Fired when the widget receives a message. event_data.detail is the message received.

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

onConversationUpdated

Fired when the widget receives a conversation update. event_data.detail.conversation contains the conversation.

<script type="application/javascript">
  window.tileDeskAsyncInit = function() {
   var now = Date.now();
   window.tiledesk.on('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>

Load Parameters event

Fired before the tiledesk parameters are loaded. Use this event to change TileDesk settings at runtime.

Important payload: event_data.detail.default_settings — the constructor default settings.

Enabling authenticated visitors in the Chat widget

You can configure your widget to authenticate visitors using the JavaScript API and JWT token. More info: https://developer.tiledesk.com/widget/auth

Related

• Previous: https://developer.tiledesk.com/widget/advanced/old-versions

• Next: https://developer.tiledesk.com/apis/rest-api

Last updated 2 years ago

Privacy This page links to the TileDesk privacy policy: https://tiledesk.com/privacy.html