# Introduction ## Tiledesk Developers Hub Welcome to the Tiledesk Documentation, where you'll find guides and community support to help you start working as quickly as possible! ## Widget JS API Use our powerful Tiledesk Widget JavaScript library for client side to automate some of your Tiledesk activities and create custom integrations with your own systems. These JS APIs allow you to interact with the widget UI. ## Chatbot API You can use Tiledesk as platform, by creating your own Bot with API endpoint that describe within this document. These are few examples that show how Tiledesk platform will accept the request and give response, from API Endpoint for Bot uses. ## API Reference Tiledesk is a headless support API that enables rapid experience-first all business development. ### REST API An Tiledesk RESTful API is an application program interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. You can use it to retrieve and update information from your own Tiledesk account, or to integrate Tiledesk into your own product. It's completely up to you and your custom use case. ### Webhook API This Webhooks API allows you to subscribe to changes happening in the accounts of any Tiledesk. Webhooks are a powerful API resource that you can use to automate much of your use cases and improve your productivity. Unlike the API resources, which represent static data that you can create, update and retrieve as needed, webhooks represent dynamic resources. You can configure them to automatically notify you when a customer has taken a particular action, such as making a purchase or replying to a conversation. ## Mobile SDKs ### Android Bring real customer service to your mobile apps with ready-to-use chat widgets. In this documentation will cover embedding a mobile chat window in an Android application using the Android SDK. ### IOS Get started on integrating the Tiledesk iOS SDK into your native iOS app using all functionality. ## Architecture Tiledesk is the first open source live chat platform. Understand the Tiledesk architecture and all the components. ## Installation and configuration Install Tiledesk on your server using Docker, Kubernetes or from source code and configure it (email, channel, etc.) # Community Join the Tiledesk community. * Star on GitHub. Star [Tiledesk repositories](https://github.com/tiledesk) on GitHub and help others discover the platform. * Share your Feedback. Discuss new ideas, suggestions by creating a post in our [Feedback Board](https://feedback.tiledesk.com/). * Explore our Public Roadmap. Stay updated on our latest developments and contribute your thoughts about our [Public Roadmap](https://feedback.tiledesk.com/roadmap). * Share your Projects. Publish your work on our [Chatbots and Conversational Apps Community](https://tiledesk.com/community/) and get recognized for it. * Join our Affiliate Program. Start earninig rewards for your referrals by participating in our [Affiliate Program](https://tiledesk.com/affiliate/). * Participate on the Forums. To discuss Tiledesk development with Tiledesk team and community join our [Discourse forum](https://tiledesk.discourse.group). * Squash Bugs. Join Tiledesk’s passionate community to help us manage issues and squash bugs for Tiledesk Design Studio, Server, Widget, Web Chat and iOS and Android clients. * Write Documentation. You don’t have to be a developer to contribute to Tiledesk. You can create new or update old Tiledesk Docs articles or tutorials directly through GitHub. * Suggest a Blog Post. Write or suggest a blog post on your Tiledesk story, tell us about how it improved your team’s communication and we’ll share it with the community. * Create Tutorial Videos. Tiledesk has a passionate community of content creators on [YouTube](https://www.youtube.com/@tiledesk) sharing tutorials on configuring, installing, customizing and developing for Tiledesk. * Come Meet Us. Come say hi at a local meetup or conference, tell us how you customized it to suit your needs and improved your team’s communication. * Start using Tiledesk. You can sign-up to our Free Forever [Cloud](https://panel.tiledesk.com/v3/dashboard/#/signup?su=37) version or install [On-Premise](https://tiledesk.com/install). * Check our Website. Visit [Tiledesk.com](https://tiledesk.com) and our [Blog](https://tiledesk.com/blog/) for the latest news. # Ask for Support Please refer to this document to understand how the Tiledesk team and the Tiledesk Community provides support for the free plans and the open source edition of Tiledesk software. ## Urgent issues? Paid subscriptions If you think your issue is urgent, then you have two choices: * Subscribe for a paid plan on the [Cloud edition](https://tiledesk.com/pricing-live-chat/) * Get a support package for the [Enterprise Edition](https://tiledesk.com/tiledesk-live-chat-on-premise/) ## I need Help but it's not so urgent Use [our forum](https://tiledesk.discourse.group/) Patiently wait for an engineer to consider helping you. If you opt for community's help instead of paid support, please notice that: 1. When opening an issue, create a small, isolated, simple, reproduction of the issue using an online code editor (like replit, codepen, codesandbox etc.) if possible and a GitHub repository if not. The process may help you discover the underlying issue (or realize that it’s not an issue with the project). It will also make it easier for maintainers to help you resolve the problem. 2. Your question must be well-documented and you should provide the minimum code required to reproduce the problem. When possible always provide a running example to that gives evidence of the issue. 3. We do this in our spare time. Please respect our team. 4. Just because it is urgent for you does mean that it is urgent for the whole Tiledesk product or community 5. Please answer their questions patiently and help them try and understand your problem 6. Being rude to them will not help you at all 7. Please note that posting the same question in several channels will not help you 8. Don't open a bug yet. When you ask in the channels or forums then devs or other community helpers will tell you if you really need to open an issue. Frequently if there really is a problem you won't be the first one to experience it, so always check the forum carefully for duplicates. Use lots of different search terms and make sure you check closed Issues as well (see below). # Public Roadmap and Changelog The [Tiledesk Roadmap](https://feedback.tiledesk.com/roadmap) is publicly accessible, allowing our community to stay informed about upcoming features that will enhance Tiledesk as a product. ## Tiledesk Changelog The [Tiledesk Changelog](https://feedback.tiledesk.com/changelog) provides an overview of the most recent key features that have been released. ### Detailed Changelogs for Main Components * [Tiledesk Design Studio Full Changelog](https://github.com/Tiledesk/design-studio/blob/master/CHANGELOG.md) * [Tiledesk Server Full Changelog](https://github.com/Tiledesk/tiledesk-server/blob/master/CHANGELOG.md) * [Tiledesk Dashboard Full Changelog](https://github.com/Tiledesk/tiledesk-dashboard/blob/master/CHANGELOG.md) * [Chat21 Ionic Full Changelog](https://github.com/Tiledesk/chat21-ionic/blob/master/CHANGELOG.md) * [Chat21 Web Widget Full Changelog](https://github.com/Tiledesk/chat21-web-widget/blob/master/CHANGELOG.md) # Tutorials In this section we list all developer tutorials available for the Tiledesk platform. Having all the tutorials listed in a single page is a good way to get a global vision of all the amazing things that you can do with Tiledesk. ## Connect Telegram Channel Tutorial ![Telegram integration](https://user-images.githubusercontent.com/45603238/175036688-f26d0efe-3150-425b-bab2-6ca07b63adf6.png) This integration allows you to connect your company's Telegram bot to your Tiledesk account, thus creating a tunnel between the two platforms. Therefore customers can reach your support simply by writing to your Telegram bot and these messages will be delivered to the Tiledesk webchat, along with messages from other channels. [Telegram integration Tutorial](/apps/telegram-integration) ## Custom Authentication Tutorial ![](https://user-images.githubusercontent.com/32564846/171562770-2c161497-ad36-4490-87d8-4e1fcdd203b7.png) This tutorial will guide you to a deep look of Tiledesk custom (and secure) [JWT authentication](https://developer.tiledesk.com/apis/authentication) for your end-users. This tutorial is a fully-functional, full-stack application (backend+frontend) deployed on replit with nodeJS (backend) and HTML+Javascript (frontend). [Custom authentication Tuturial](/apis/authentication/jwt-auth-tutorial) To get a taste of the final result you can find the live web application up and running at this url: ## Hide Widget tutorial A very simple tutorial to hide the widget when no agent is available. Good to learn the basics of Widget SDK (and some Tiledesk APIs too). [Widget - Hide widget](/widget/tutorials/hide-widget) ## Conversation-embedded apps, Quick start A quick start, introductory tutorial to *conversation-embedded* apps. You will learn how to implement a basic conversation-embedded application. It's a skeleton App that will show you the basic principles, architecture and APIs involved in the development of a simple conversation-embedded application. [Widget - Payment App Tutorial](/widget/widget-app-introduction/widget-app-payment) ![Conversation-embedded apps - Quick start](https://user-images.githubusercontent.com/32564846/165598879-26373df7-d254-4174-bf2a-73638999de15.png) ## Conversation-embedded apps, *prechat form* during chat Do you want a more customizable *prechat form*? Do you want the user to play with your chatbot and ask his personal data only when needed (i.e. during human handoff)? With this tutorial you'll learn how to setup a minimum and fully functional prechat form that appears in the conversation only when the user is bored with your chatbot and would like to chat with a human! [Prechat form App Tutorial](/widget/widget-app-introduction/widget-app-prechat-form) ![In-conversation Prechat form](https://user-images.githubusercontent.com/32564846/165599748-fbc56e72-de48-4347-9a17-0712a2d29d89.png) ## External Chatbots Tutorials * [External Chatbot - Hello World tutorial](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/connect-your-own-chatbot.md) * [External Chatbot - Chatbot to Human handoff](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/agent-handoff.md) * [External Chatbot - Send Text Buttons](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/buttons-media-actions-more.md) * [External Chatbot - Advanced Tutorials](https://github.com/Tiledesk/tiledesk-docs/blob/master/external-chatbot/external-chatbot-tutorials/README.md) * [External Chatbot - Introduction](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/dialogflow/introduction-dialgoflow-external.md) * [External Chatbot - Tutorial 1 - Dialogflow as external chatbot](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/dialogflow/dialogflow-as-external-chatbot-integration.md) * [External Chatbot - Tutorial 2 - Buttons and images](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/dialogflow/dialogflow-tutorial-2-micro-language-integration.md) * [External Chatbot - Tutorial 3 - Automatic human handoff with fallback intent](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/dialogflow/dialogflow-tutorial-3-automatic-human-handoff.md) * [External Chatbot - Tutorial 4 - Explicit Human handoff with user intent](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/dialogflow/dialogflow-tutorial-4-explicit-human-handoff.md) * [External Chatbot - Tutorial 5 - Gracefully handling operating hours during handoff](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/dialogflow/dialogflow-tutorial-5-graceful-human-handoff.md) * [External Chatbot - Generate Dialogflow Google Credentials file](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/dialogflow/generate-dialgoflow-google-credentials-file.md) * [External Chatbot - Rasa Tutorial 1 - Rasa as external chatbot](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/tutorials/chatbot/rasa/rasa-as-external-chatbot-integration.md) ## Resolution Bot Tutorials * [Resolution bot - Quickstart](https://github.com/Tiledesk/tiledesk-docs/blob/master/native-chatbot/quickstart.md) * [Resolution bot - Rich messages](https://github.com/Tiledesk/tiledesk-docs/blob/master/native-chatbot/rich-messages.md) * [Resolution bot - Chatbot chooser (multilanguage)](https://github.com/Tiledesk/tiledesk-docs/blob/master/native-chatbot/lang-chooser-chatbot.md) * [Resolution bot - Department chooser](https://github.com/Tiledesk/tiledesk-docs/blob/master/native-chatbot/department-chooser-chatbot.md) * [Resolution bot - Fallback to Knowledge-Base](https://github.com/Tiledesk/tiledesk-docs/blob/master/native-chatbot/fallback-to-knowledge-base.md) ## REST APIs Tutorials * [REST API](/apis/tutorials/rest-api) * [REST API - Sending and receiving messages with Tiledesk APIs](/apis/tutorials/rest-api/sending-and-receiving-messages) ## Webhooks Tutorials This section proposes a set of tutorial to show some common tasks you can address using this feature. The main purpose of webhooks is call a user-defined action (in the form of an HTTP endpoint) when specific Tiledesk events occur. The first tutorial [Custom Request assignment](https://developer.tiledesk.com/apis/tutorials/webhooks/custom-assignment-pooled) addresses an custom assignment every time a new request is moved to a Department's pooled routing schema. The second tutorial [Request transcript on close](https://developer.tiledesk.com/apis/tutorials/webhooks/get-transcript-on-close) shows how you can get your chat transcript on each closing operation (i.e. for the purpose of sending it to your remote CRM to synchronize conversations) * [Webhooks - Custom Request assignment](/apis/tutorials/webhooks/custom-assignment-pooled) * [Webhooks - Request transcript on close](/apis/tutorials/webhooks/get-transcript-on-close) # Widget SDK ## Tiledesk Widget **Widget SDK ver 6.0** ![](https://user-images.githubusercontent.com/47848430/151355859-f94be6a7-3098-43a2-924c-d411e10d5815.png) Are you interested in the v4 version? [Click here](/widget/advanced/old-versions/web-sdk-v4). This guide will show you how to get started as quickly as possible with the Widget SDK from Tiledesk. The Widget SDK will give businesses and developers the flexibility to build and customize a chat experience that meet their specific design/brand requirements. ## How to install 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: ```html ``` To get your TILEDESK\_PROJECT\_ID go to the Tiledesk Dashboard and click on the Widget item of the menu: ![Tiledesk Dashboard](https://user-images.githubusercontent.com/47848430/150099187-a7697396-bc63-44d1-bcfc-d375da7a1b4b.png) ### Install with visitor basic information Website visitors are generally leads (visitors if they have not communicated via the Messenger) whereas logged in users are Tiledesk users already logged in onces. The main difference is the amount of information you know about them. You can pass basic information throught tiledeskSettings object. An example is provided below. ```html ``` ### Install with custom position Sometimes you may want to show Tiledesk Widget on left or right side of your website. Moreover, you may also want to get more/less distance between widget and website margin. The following example shows a widget aligned on left side and with custom margin from X and Y axis. ```html ``` ![Custom position of the widget: property explanation](https://user-images.githubusercontent.com/47848430/151353935-8ee4711d-0bc3-4044-ba67-039adfb0a4b2.png) ## 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](/widget/auth) # Javascript API: Methods Tiledesk provides a Tiledesk JavaScript object that responds to a few methods. These allow you to update widget without a page refresh and interact with the messenger window. ## Open the widget This will open the widget: ```javascript window.Tiledesk('open'); ``` ## Minimize the widget This will minimize the widget: ```javascript window.Tiledesk('close'); ``` ## Hide the widget This will hide the widget: ```javascript window.Tiledesk('hide'); ``` ## Show the widget This will show the widget: ```javascript window.Tiledesk('show'); ``` ## Dispose the widget This will clear the widget html elements from the DOM: ```javascript window.Tiledesk('dispose'); ``` ## 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. ```javascript window.Tiledesk('reInit'); ``` ## 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. ```javascript window.Tiledesk('restart'); ``` ## Signin with anonymously This method make a signin anonymously ```javascript window.Tiledesk('signInAnonymous'); ``` ## Signin with JWT Custom Token This method make a signin using a JWT Custom Token as described [here](/widget/auth). ```javascript window.Tiledesk('signInWithCustomToken', customJwt); ``` ## Make a logout This will logout the widget: ```javascript window.Tiledesk('logout'); ``` ## Show callout This will show the widget callout if it is not open: ```javascript window.Tiledesk('showCallout'); ``` ## Show or hide the PreChatForm This parameter configures the PreChatForm visibility: ```javascript window.Tiledesk('setPreChatForm', true|false); ``` ## Set custom PreChatForm Json This method allow you to customize preChatFormJson property, and change preChatForm structure if preChatForm is still active (ensure preChatForm value is set to true, otherwize use window\.Tiledesk('setPreChatForm', true) method before call setPreChatFormJson ). This method accept an Array (see [docs](https://developer.tiledesk.com/widget/advanced/prechat-form-json) for more detail about customize it): ```javascript window.Tiledesk('setPreChatFormJson', customFormArray); ``` ## Get custom PreChatForm Json This method allow you to get current preChatForm Json array used in the preChatForm component when is active (check preChatForm value is set to true): ```javascript window.Tiledesk('setPreChatFormJson', customFormArray); ``` ## Set new value to Widget parameter You can change a value to the Tiledesk Widget parameter. Pass an object in the form of key/value, where key represent che name of the property you want to modify, and value is the new value you want to set: ```javascript window.Tiledesk('setParameter', {key: string, value: string}); ``` ## Set new value to Widget attribute parameter You can change a value to the Tiledesk Widget attribute parameter. Pass an object in the form of key/value, where key represent che name of the property you want to modify, and value is the new value you want to set: ```javascript window.Tiledesk('setAttributeParameter', {key: string, value: string}); ``` ## Start a new conversation You can programatically start a new conversation: ```javascript window.Tiledesk('startConversation'); ``` ## Open a conversation from a specif ID You can programatically open an already existing conversation by id in the form of *'support-group-'+\+'-'+uuid* ```javascript window.Tiledesk('openConversationById', conversation_id); ``` ## Clear site data You can programatically clear saved session data : ```javascript window.Tiledesk('clearStorage'); ``` # Javascript API: Attributes ## Configuration with tiledeskSettings You can customize the widget passing the following parameters to **window\.tiledeskSettings** object. **Javascript API:** ### Visual Attributes These set of attributes modify the general widget behaviour | Attributes | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **projectid** | string | The Tiledesk project id. Find your Tiledesk ProjectID in the Tiledesk Dashboard under the Widget menu | | **departmentID** | string | To skip departments selection, you can set the department ID upon which the widget must start the new conversation (See the turorial [here](https://developer.tiledesk.com/widget/advanced/preset-department)) | | **welcomeTitle** | string | The welcome title to show on the widget home page | | **welcomeMsg** | string | Set the widget welcome message | | **widgetTitle** | string | Set the widget title label shown in the widget header. . The default value is '*Tiledesk*' | | **calloutTitle** | string | The title of the callout window | | **calloutMsg** | string | The message of the callout window | | **calloutTimer** | integer | Proactively open the chat windows to increase the customer engagement. Permitted values: -1 (Disabled), 0 (Immediatly) or a positive integer value (e.g. 5 (After 5 seconds), 10 (After 10 seconds)) | | **logoChat** | string | The url of the logo to show on the widget home page | | **lang** | string | An ISO 639-two-letter-code. 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 | | **recipientId** | string | Enable the widget to open a specific conversation | | **userFullname** | string | Current user fullname. Set this parameter to specify the visitor fullname | | **userEmail** | string | Current user email address. Set this parameter to specify the visitor email address | | **persistence** | string | 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 | | **singleConversation** | boolean | This property if true, allow you to transform widget from multi conversation channel to a single conversation channel (See more [here](https://developer.tiledesk.com/widget/advanced/singleConversation-mode)) | | **typingLocation** | string | Set the location of the typing indicator between 'header' or 'content' locations. Default alue:'content'. Permitted values: 'content', 'header' |
### Style Attributes These set of attributes modify the Widget style (i.e theme color, page position, etc.) | Attributes | Type | Description | | ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **align** | string | Make the chat available on the Right or on the Left of the screen. Permitted values: 'right', 'left'. Default value is right. | | **marginX** | string | Set the side margin, left or right depending on the align property. Default value : "20px" | | **marginY** | string | Set the distance from the page bottom margin. Default value : "20px" | | **mobileMarginX** | string | Set the side margin, left or right depending on the align property on mobile. Default value : "0px". (See example [here](https://developer.tiledesk.com/widget/tutorials/widget-mobile)) | | **mobileMarginY** | string | Set the distance from the page bottom margin on mobile. Default value : "0px". (See example [here](https://developer.tiledesk.com/widget/tutorials/widget-mobile)) | | **size** | string | Set the size of the widget to 'min, 'max', 'top' dimension. Default value : "min". | | **themeColor** | string | 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)) | | **themeColorOpacity** | number \[0..100] | Allows you to change opacity of the theme color in the widget's backgrounds (color of the header, color of the home). Permitted values: numbers from 0 to 100. Default value: 50 | | **themeForegroundColor** | string | 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)) | | **launcherWidth** | string | Allow you to change launcher width dimension. Default value: "60px" | | **launcherHeight** | string | Allows you to change launcher height dimension. Default value: "60px" | | **baloonImage** | string | Allows you to change baloon image with custom image URL. Minimun size: 60x60px. Allowed image format: \*.jpg, \*.jpeg, \*.jfif, \*.JPG, \*.JPE. | | **baloonShape** | string | Allows you to change baloon shape with custom dimension. Permitted values: string with **four values** (e.g. '10px 10px 10px 10px'), **three values** (e.g. '15px 50px 30px'), **two values** (e.g. '15px 50px'), **one values** (e.g. '15px'), **percentage dimension** (e.g. '10%'). Default value: "50%". | | **fullscreenMode** | boolean | If it is true, the chat window is open in fullscreen mode. Default value: false |
### General settings attributes General settings for the widget | Attributes | Type | Description | | -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **allowTranscriptDownload** | boolean | Allows the user to download the chat transcript. The download button appears when the chat is closed by the operator. Default value: false | | **allowReopen** | boolean | Allows you to continue writing in a conversation even if it was archived by an agent or the user himself. Default value: false | | **hideHeaderCloseButton** | boolean | Hide the close button in the widget header. The default value is false. | | **hideHeaderConversationOptionsMenu** | boolean | Enable you to show/hide options menu in a conversation header. Default value: false | | **hideCloseConversationOptionMenu** | boolean | Enable you to show/hide 'Close chat' menu option in converation header top-right menu. Default value: false | | **hideRestartConversationOptionsMenu** | boolean | Enable you to show/hide 'Restart chat' menu option in converation header top-right menu. Default value: false | | **hideSettings** | boolean | Enable you to show/hide options menu in home component. Default value: false | | **openExternalLinkButton** | boolean | Enable you to open or not a link in an action button externally. Default value: true | | **showWaitTime** | boolean | Show the expected response time from your agents in the home widget window. Default value: true. | | **dynamicWaitTimeReply** | boolean | Enable you to decide whether or not to share the average response time of his team. Default value: true | | **showAvailableAgents** | boolean | Show the available agents with avatar in the home widget window. Default value: true. | | **showLogoutOption** | boolean | Show the logout options in the home widget window. Default value: false. | | **showAttachmentButton** | boolean | Enable you to show/hide attachment button in the footer of a conversation. Default value: true | | **showAllConversations** | boolean | Enable you to show/hide the list of all conversations. Default value: true | | **soundEnabled** | boolean | Enable you to allow or not sound when new message arrived. Default value: true | | **open** | boolean | Set the status of the widget: true(open) or false (close). If it is \**true* the Widget suddenly opens right after loading. Default value: false | | **isLogEnabled** | boolean | Enable the widget log. The default value is false. | | **logLevel** | string | Allows you to change the level of the log. Value type: string. Permitted values: ‘ERR’ < ‘WARN’ < ‘INFO’ < ‘DEBUG’. Default value: ‘ERROR’ | | **startFromHome** | boolean | If false when loaded the widget starts directly with a new conversation. If true the widget shows the home component. Default value: true | | **autoStart** | | boolean | | **startHidden** | boolean | Set if the widget starts in hidden mode. Default value : false | | **preChatForm** | boolean | You can require customers to enter information like name and email before sending a chat message by enabling the Pre-Chat form. Default value: false. | | **preChatFormJson** | Array | You can customize the information you request from customers in the pre-chat form before start a new conversation. ([See docs](https://developer.tiledesk.com/widget/advanced/prechat-form-json)) | | **customAttributes** | Object | You can add customAttributes to widget as a key-value object. It is required to use *" "* for each key-value parameter. *'userFullname'* and *'userEmail'* special key allow you to set user info from external. See example above [here](https://developer.tiledesk.com/widget/attributes#example-3.-widget-with-custom-attributes) for more detail | | **nativeRating** | boolean | Allow you to show or not widget rating page. Default value: true | | **showInfoMessage** | string | You can show/hide an info message in a conversion by specifying a comma separated list of keys. The keys in question are: **'MEMBER\_JOINED\_GROUP'** to manage the information of when an agent is added to your conversion; **'MEMBER\_LEFT\_GROUP'** to manage the information of when an agent left the conversation; **'CHAT\_CLOSED'** to manage the information of when a chat is closed; **'CHAT\_REOPENED'** to manage the information of when a chat already archived is subsequently reopened; **'TOUCHING\_OPERATOR'** to manage the information of when a conversation is assigned to an agent; **'LEAD\_UPDATED'** to manage an update of the widget user's name and email . Ex: *'MEMBER\_JOINED\_GROUP,CHAT\_CLOSED'*: allows you to see information about the joining of an agent within a conversation and when the current chat is archived. Default value: *'MEMBER\_JOINED\_GROUP'* | | **restartConversation** | boolean | This property if true, only when singleConversation is enabled, allow you to start always a new conversation at each page refresh or widget restart.Default value: false | | **participants** | boolean | This property if true allow you to talk only with specif user passed as a comma separated list of ids. Ex: 'ID\_user1,ID\_user2' | | **fileUploadAccept** | string | This define which file types is allowed to be upload by the user as an attachment. It takes as its value a comma-separated list of one or more file types. See more [here](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers). Default value: 'image/\*,.pdf,.txt' |
### Message Style Attributes These set of attributes modify the Widget style for messages (i.e. message background color, text color, buttons color etc.) | Attributes | Type | Description | | -------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **bubbleSentBackground**\* | string | 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**\* | string | 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** | string | 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** | string | 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** | string | allow you to change the font size of bubble messages. Permitted values: medium \|xx-small\| x-small \| small \| large \| x-large \| xx-large \| smaller \| larger \| *length* \|%. Default value : "1.4em" | | **buttonFontSize** | string | Allow you to change the font size of all the attachment buttons of a message. Permitted values: medium \|xx-small\| x-small \| small \| large \| x-large \| xx-large \| smaller \| larger \| *length* \|%. Value type: string. Default value: "15px" | | **buttonBackgroundColor** | string | Allow you to change the background color of all the attachment buttons of a message. Permitted values: Hex color codes (e.g. #1a1a1a) and RGB color codes (e.g. rgb(26, 26, 26)) | | **buttonTextColor**\* | string | Allow you to change the text color of all the attachment buttons of a message. Permitted values: Hex color codes (e.g. #1a1a1a) and RGB color codes (e.g. rgb(26, 26, 26)) | | **buttonHoverBackgroundColor**\* | string | Allow you to change the background color of all the attachment buttons of a message when when you mouse over them. Permitted values: Hex color codes (e.g. #1a1a1a) and RGB color codes (e.g. rgb(26, 26, 26)) | | **buttonHoverTextColor** | string | Allow you to change the text color of all the attachment buttons of a message when when you mouse over them. Permitted values: Hex color codes (e.g. #1a1a1a) and RGB color codes (e.g. rgb(26, 26, 26)) | \*These properties if not provided will automatically be calculate starting from **themeColor** value
### Widget visibility These set of attributes can manage the visibility of the widget on mobile and desktop platforms | Attributes | Type | Description | | ----------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **displayOnDesktop**\* | boolean | Allow you to display/hide widget on desktop. Default value: true | | **onPageChangeVisibilityDesktop**\* | string | Allow to decide the widget status (opened or closed) when the page is loaded or changed on web browser. You can always open the widget, always close the widget or restore the last status of it (if closed, stay close; if opened, open it).Permitted values: 'open' , 'close', 'last'. Default value: 'close' | | **displayOnMobile** | boolean | Allow you to display/hide widget on mobile. Default value: true | | **onPageChangeVisibilityMobile** | string | Allow to decide the widget status (opened or closed) when the page is loaded or changed on web browser. You can always open the widget, always close the widget or restore the last status of it (if closed, stay close; if opened, open it).Permitted values: 'open' , 'close', 'last'. Default value: 'close' |
![Message style attributes helper schema](https://user-images.githubusercontent.com/47848430/151520122-bc7cec71-6724-4ad3-8282-9425198be816.png) ### Social channels Attributes #### *(available only in **window\.tiledeskSettings** object)* These set of attributes allow the owner to be reachable in their own social media channels (whatsapp businness, facebook messanger page, telegram). Buttons, when available, will be shown at the bottom of the home page, as displayed below. ![Social channels position](https://user-images.githubusercontent.com/47848430/208400033-6b3bf329-0864-4cbc-b217-116e8adeb208.png) | Attributes | Type | Description | | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- | | **whatsappNumber** | boolean | This property allows the user of the widget to start a conversation on your official whatsapp business account | | **messangerPageTitle** | boolean | This property allows the user of the widget to start a conversation on your official Facebook Page with Messanger | | **telegramUsername** | boolean | This property allows the user of the widget to start a conversation on your official Telegram account | ### Ready-only properties | Attributes | Type | Description | | ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **isShown** | string | 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 |
## Configuration using URL parameters You can also pass the above configurations as a Url parameter with the **tiledesk\_** prefix. For example: ``` https://widget.tiledesk.com/v6/assets/twp/index.html?tiledesk_projectid=&tiledesk_isOpen=true&tiledesk_align=right&project_name=Assistente%20Virtuale ``` ## Examples ### Example 1. Widget with user fullname and email ```html ``` ### Example 2. Widget with preChatForm and left alignment: ```html ``` ### Example 3. Widget with custom attributes: Widget allow you to pass some custom attributes as key-value object in window\.tiledeksSettings object or as a Url parameter with the **tiledesk\_customAttributes** prefix. ```html ``` **customAttributes** is shown in conversation detail as payload key under attributes accordion as shown above ![customAttributes location](https://user-images.githubusercontent.com/47848430/166652826-a37e1d97-1e92-43bf-8f9a-6d7cd06b5e30.png) Set *'userFullname'* or *'userEmail'* special key to manage user information from external (e.g. from your mobile app after an internal login). Above example of how to set it: ```html ``` # 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** ``` ``` **Ex. Widget with visitor fullname and email from localStorage** ``` ``` **Ex. Widget with welcome message with current date** ``` ``` ## 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** ``` ``` **Ex. Add a custom attribute (page title) to the message.** ``` ``` ## 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:** ``` ``` ## 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. :** ``` ``` ## 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. ``` ``` ## 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. ``` ``` ## 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. :** ``` ``` ## 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: ``` ``` # Widget Authentication ## Enabling authenticated visitors Require Widget Javascript API v4 ### Overview You can configure your widget to authenticate visitors using the Javascript API and JWT token. When you configure the Chat widget to use authenticated visitors, you get the following benefits: * Ability to have higher confidence and security that the visitor/customer you or your agents are talking to is the real deal * Support for cross device/browser identification. The visitor can be viewed as the same person if or when they choose to use a different device or browser when the custom ID is specified in the authentication call. To configure your widget for visitor authentication, you need to [Generate a Project Shared Secret](/apis/authentication#generating-a-project-shared-secret). Only Chat administrators can configure visitor authentication settings. Once you have generated the shared secret, use it to create a JWT token that you'll add to your Web Widget snippet. ### Creating a JWT token To create a JWT token: 1\) Construct a server-side payload of data for the JWT token. Your token needs to be dynamically generated from the server-side on page load. Please follow this guide to [Create a JWT Token](/apis/authentication). 2\) Set the Tiledesk widget property **autoStart** to **false**. 3\) Use the **window\.Tiledesk('signInWithCustomToken', JWT)** Javascript API to provide a function which supplies a fresh JWT every time it is invoked. Below is a code example: ``` window.Tiledesk("signInWithCustomToken", ""); ``` ATTENTION: the token passed with signInWithCustomToken must starts with the string "JWT ". Example: ``` window.Tiledesk("signInWithCustomToken","JWT 12345678..."); ``` 4\) Use the **onAuthStateChanged** event to check if user is logged in and then show widget ``` window.Tiledesk('onAuthStateChanged', function(event_data) { console.log("onAuthStateChanged FIRED-->", event_data); if(event_data.detail.isLogged){ window.Tiledesk('show') } }); ``` See a complete example [here](https://www.w3schools.com/code/tryit.asp?filename=GU3DPFHYTP8E). ## About the agent experience with authenticated visitors A few things are updated in the Chat dashboard when an agent starts chatting with an authenticated visitor. First, the agent will be able to tell the visitor is authenticated by the authenticated checkmark overlay on the visitor's avatar. ![image](https://user-images.githubusercontent.com/9378770/150633296-5bb21335-2b5d-4be9-a5d2-d62b0f488e7e.png) # Widget for Android with WebView This example shows how to integrate the Tiledesk Widget via a WebView for Android. Attention the Tiledesk Widget is compatible with Android 13+ ## Integrate Widget for Android with WebView ### Permissions Don't forget to give permission in your manifest.xml adding the following: ``` ``` ## **Method 1:** load Tiledesk widget from embedding url ### Activity ``` package com.tiledesk.tiledeskwidgetintegrationexample; import androidx.annotation.RequiresApi; import androidx.appcompat.app.AppCompatActivity; import android.os.Bundle; import android.app.Activity; import android.content.ActivityNotFoundException; import android.content.Intent; import android.net.Uri; import android.os.Build; import android.util.Log; import android.webkit.ConsoleMessage; import android.webkit.ValueCallback; import android.webkit.WebChromeClient; import android.webkit.WebSettings; import android.webkit.WebView; import android.widget.Toast; public class TiledeskActivity extends AppCompatActivity { public static final int REQUEST_SELECT_FILE = 100; public ValueCallback uploadMessage; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_tiledesk); WebView myWebView = (WebView) findViewById(R.id.tiledesk); myWebView.setWebChromeClient(new FileChooserWebChromeClient(this) { @Override public boolean onConsoleMessage(ConsoleMessage consoleMessage) { Log.d("TiledeskActivity", consoleMessage.message() + " -- From line " + consoleMessage.lineNumber() + " of " + consoleMessage.sourceId()); return super.onConsoleMessage(consoleMessage); } }); // Enable JavaScript WebSettings webSettings = myWebView.getSettings(); webSettings.setJavaScriptEnabled(true); // Enable DOM storage API (localStorage/sessionStorage) webSettings.setDomStorageEnabled(true); //allow to snap photos webSettings.setAllowFileAccess(true); webSettings.setJavaScriptCanOpenWindowsAutomatically(true); //Inject widget load URL myWebView.loadUrl("https://widget.tiledesk.com/v6/assets/twp/index.html?tiledesk_projectid=&tiledesk_fullscreenMode=true&tiledesk_hideHeaderCloseButton=true&tiledesk_open=true"); } @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode == REQUEST_SELECT_FILE) { if (uploadMessage == null) return; uploadMessage.onReceiveValue(WebChromeClient.FileChooserParams.parseResult(resultCode, data)); uploadMessage = null; } } public class FileChooserWebChromeClient extends WebChromeClient { private Activity myActivity; public FileChooserWebChromeClient(TiledeskActivity myActivity) { this.myActivity = myActivity; } @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) public boolean onShowFileChooser(WebView webView, ValueCallback filePathCallback, FileChooserParams fileChooserParams) { uploadMessage = filePathCallback; Intent intent = fileChooserParams.createIntent(); try { myActivity.startActivityForResult(intent, REQUEST_SELECT_FILE); } catch (ActivityNotFoundException e) { Toast.makeText(myActivity, "Cannot open file chooser", Toast.LENGTH_LONG).show(); return false; } return true; } } } ``` ### Layout ``` ``` ## **Method 2:** load Tiledesk widget from custom html file that integrate tiledesk script ### HTML code Consider an \*.html file into assets that contains basic html code with script tag able to integrate tilesk widget inside your webview ```html ``` ### Activity ``` package com.tiledesk.tiledeskwidgetintegrationexample; import androidx.annotation.RequiresApi; import androidx.appcompat.app.AppCompatActivity; import android.os.Bundle; import android.app.Activity; import android.content.ActivityNotFoundException; import android.content.Intent; import android.net.Uri; import android.os.Build; import android.util.Log; import android.webkit.ConsoleMessage; import android.webkit.ValueCallback; import android.webkit.WebChromeClient; import android.webkit.WebSettings; import android.webkit.WebView; import android.widget.Toast; public class TiledeskInjectActivity extends AppCompatActivity { public static final int REQUEST_SELECT_FILE = 100; public ValueCallback uploadMessage; @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); setContentView(R.layout.activity_tiledesk); WebView myWebView = (WebView) findViewById(R.id.tiledesk); myWebView.setWebChromeClient(new FileChooserWebChromeClient(this) { @Override public boolean onConsoleMessage(ConsoleMessage consoleMessage) { Log.d("TiledeskInjectActivity", consoleMessage.message() + " -- From line " + consoleMessage.lineNumber() + " of " + consoleMessage.sourceId()); return super.onConsoleMessage(consoleMessage); } }); // Enable JavaScript WebSettings webSettings = myWebView.getSettings(); webSettings.setJavaScriptEnabled(true); // Enable DOM storage API (localStorage/sessionStorage) webSettings.setDomStorageEnabled(true); //allow to snap photos webSettings.setAllowFileAccess(true); webSettings.setJavaScriptCanOpenWindowsAutomatically(true); //Inject widget load URL myWebView.loadUrl("file:///android_asset/index.html"); } @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) protected void onActivityResult(int requestCode, int resultCode, Intent data) { super.onActivityResult(requestCode, resultCode, data); if (requestCode == REQUEST_SELECT_FILE) { if (uploadMessage == null) return; uploadMessage.onReceiveValue(WebChromeClient.FileChooserParams.parseResult(resultCode, data)); uploadMessage = null; } } public class FileChooserWebChromeClient extends WebChromeClient { private Activity myActivity; public FileChooserWebChromeClient(TiledeskInjectActivity myActivity) { this.myActivity = myActivity; } @RequiresApi(api = Build.VERSION_CODES.LOLLIPOP) public boolean onShowFileChooser(WebView webView, ValueCallback filePathCallback, FileChooserParams fileChooserParams) { uploadMessage = filePathCallback; Intent intent = fileChooserParams.createIntent(); try { myActivity.startActivityForResult(intent, REQUEST_SELECT_FILE); } catch (ActivityNotFoundException e) { Toast.makeText(myActivity, "Cannot open file chooser", Toast.LENGTH_LONG).show(); return false; } return true; } } } ``` Find [here](/widget/web-sdk) other widget parameters to customize your experience. ### Layout ``` ``` ## Example You can find here a complete [Tiledesk Widget example for Android](https://github.com/Tiledesk/tiledesk-android-widget-example). # Widget for iOS with WKWebView This example shows how to integrate the Tiledesk Widget for iOS ## Controller ``` // // WebViewViewController.swift // Tiledesk // import UIKit import WebKit class WebViewViewController: UIViewController, WKUIDelegate { @IBOutlet weak var webView: WKWebView! @IBAction func actionClosing(_ sender: UIBarButtonItem) { dismiss(animated: true, completion: nil) } override func loadView() { let image = UIImage(named: "ic_navigation_bar")! let nav = self.navigationController?.navigationBar let tintColor = UIColor(red: 51, green: 71, blue: 94, alpha: 1) nav?.setupNavigationBar(barStyleBlack: true, tintColor: tintColor, image: image) let webConfiguration = WKWebViewConfiguration() webView = WKWebView(frame: .zero, configuration: webConfiguration) webView.uiDelegate = self view = webView } override func viewDidLoad() { super.viewDidLoad() let url = "https://widget.tiledesk.com/v6/assets/twp/blank.html?tiledesk_projectid=&tiledesk_fullscreenMode=true&tiledesk_hideHeaderCloseButton=true&tiledesk_open=true" let myURL = URL(string:url) let myRequest = URLRequest(url: myURL!) webView.load(myRequest) } /* // MARK: - Navigation // In a storyboard-based application, you will often want to do a little preparation before navigation override func prepare(for segue: UIStoryboardSegue, sender: Any?) { // Get the new view controller using segue.destination. // Pass the selected object to the new view controller. } */ } ``` Find [here](/widget/web-sdk) other widget parameters to customize your experience. ## Web View Controller Create a Web View Controller in your Story Board and add a WebView as below: ![](/files/-LkZT1Acumur8-pemJUB) # Widget for Flutter with WebView This example shows how to integrate the Tiledesk Widget via a WebView for Flutter. ## Integrate Widget for Flutter with WebView This guide will use the package [webview\_flutter](https://pub.dev/packages/webview_flutter) to implement a Webview, but other similar packages should work with minimal changes to the code. ## Implementation ```dart import 'dart:async'; import 'package:flutter/material.dart'; import 'package:webview_flutter/webview_flutter.dart'; import 'package:webview_flutter_android/webview_flutter_android.dart'; import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart'; class Webview extends StatefulWidget { const WebView(); @override ConsumerState createState() => _WebViewState(); } class _WebViewState extends State { late final _controller = WebViewController(); @override void initState() { super.initState(); unawaited(_initializeController()); } @override Widget build(BuildContext context) { return ColoredBox( color: Colors.white, child: WebViewWidget(controller: _controller), ); } Future _initializeController() async { // disable javascript dialog await _controller.setOnJavaScriptAlertDialog((request) async { return; }); switch (_controller.platform) { case final AndroidWebViewController controller: await controller.setOnShowFileSelector((params) { // implement your logic to show a file picker // attachment upload will not work on android unless this is setup }); case final WebKitWebViewController _: break; } await _controller.setJavaScriptMode(JavaScriptMode.unrestricted); return _loadRequest(); } Future _loadRequest() async { final navigationDelegate = NavigationDelegate( onPageFinished: (url) { // this is necessary to trigger the widget to show without the need for //the user to interact with the webview _controller.runJavaScript(''' document.dispatchEvent(new Event('mousemove')); '''); } onNavigationRequest: (request) { // intercept url navigation // this may be useful to display attachments like PDFs in a custom widget // if(request.url.endsWith('.pdf')) { // Navigator.of(context).push(MyPdfViewer()); // return NavigationDecision.prevent; // } return NavigationDecision.navigate; }, ); await _controller.setNavigationDelegate(navigationDelegate); return _controller.loadHtmlString( ''' ''', baseUrl: 'https://widget.tiledesk.com', ); } } ``` Find [here](https://developer.tiledesk.com/widget/web-sdk) other widget parameters to customize your experience. # Widget for React with WebView This example shows how to integrate the Tiledesk Widget via a WebView for React Native Expo or React Native CLI project ## Integrate Widget for React Native Expo project with WebView ### Prerequisites Make sure you have installed react-native-webview via Expo command: ```shell npx expo install react-native-webview ``` ### **Method 1:** load Tiledesk widget from embedding url Consider an \*.html file into assets that contains basic html code with script tag able to integrate tilesk widget insede your webview ```html ``` Add a webview to the file and set the source as the url of the local html file ```dart import React from 'react'; import { StyleSheet, View } from 'react-native'; import { WebView } from 'react-native-webview'; const WebViewScreen = () => { return ( ); }; const styles = StyleSheet.create({ container: { flex: 1, }, }); export default WebViewScreen; ``` ### **Method 2:** load Tiledesk widget from embedding script Add a webview to the file and set the source as html code ```dart import React from 'react'; import { StyleSheet, View } from 'react-native'; import { WebView } from 'react-native-webview'; const WebViewScreen = () => { const htmlContent = ` `; return ( ); }; const styles = StyleSheet.create({ container: { flex: 1, }, }); export default WebViewScreen; ``` ## Integrate Widget for React Native CLI project with WebView ### Prerequisites Make sure you have installed react-native-webview via Expo command: ```shell npx expo install react-native-webview ``` ### Implementation Consider an \*.html file into assets that contains basic html code with script tag able to integrate tiledesk widget inside your webview ex. *“widget.html”* ```html ``` Add the **widget.html** file to the correct project directory. **For Android**: Place the file in android/app/src/main/assets/.\ **For iOS**: Place the file in ios/\/widget.html. If the assets folder does not exist (on Android), you can create it manually. Add webview to App.tsx ```dart import React from 'react'; import { SafeAreaView, StyleSheet } from 'react-native'; import { WebView } from 'react-native-webview'; import { Platform } from 'react-native'; const App = () => { const localFile = Platform.OS === 'ios' ? require('./widget.html') : 'file:///android_asset/widget.html'; return ( ); }; const styles = StyleSheet.create({ container: { flex: 1, }, webview: { flex: 1, }, }); export default App; ``` ## Example You can find here a complete [Tiledesk Widget example for React Native EXPO project example](https://github.com/Tiledesk/tiledesk-widget-react-native-expo) or [Tiledesk Widget example for React Native CLI project example](https://github.com/Tiledesk/tiledesk-widget-react-native-cli) # Widget for Wix Website platform This example shows how to integrate the Tiledesk Widget via a custom HTML code using [Wix website platform](https://manage.wix.com/) ### Prerequisites Due to [security update](https://support.wix.com/en/article/updates-to-iframes-and-custom-elements) in wix, some elements in widget installation snippet code could be blocked. But, no warries. We already found a smart solution with some additional work. What you have to do, before adding custom code to your website with wix, is to create an html page that can host the Tiledesk Widget installation snippet code like the one below: ```html ``` Now take notes of this url (for this tutorial we'll named it as **https\://\** ). We have to use it soon. ### Installation From your wix website panel, follow this steps: 1. After completing the basic configuration of your site, navidate to "Settings." You can usually find this option in the top menu or sidebar. 2. Scroll down and click on *Custom code* setting option in **Developer and integrations** section. 3. Add your custom code by click on *+Add custom code* ![](https://a.storyblok.com/f/156985/975x505/2a40158e0d/wix-custom-code.png/m/) 4. From the modal window that appears, place an iframe HTML element in the text box. The iframe src property has to link to a public https page hosted on your server. Code example could be: ```html ``` Set a name, the pages where the code has to be active and set the embedded code to 'pin to screen' (to make it stick in the right bottom corner) 5. Apply the changes and the Tiledesk live chat widget on your Wix website should works fine. That's it! Your Wix website is now equipped with the Tiledesk live chat widget, allowing you to engage with visitors in real-time and provide excellent customer support. Many thanks to Frank Huisman from Duo Criativo agency for the collaboration on writing this tutorial # Tutorials # Hide widget In this tutorial we will show to you a simple tutorial of how to hide widget if no agent is still available. Steps to make them is very easy: 1. Start widget in hidden mode setting startHidden boolean property to true 2. Get widget settings using Tiledesk APIs 3. Use the function window\.Tiledesk(‘show’) to show the widget ONLY if some agent is available. Here is the full code example ```html This Tiledesk example will hide the widget if no agent is available
Agents available: loading availability...
``` View result [here](https://andreasponziello.w3spaces.com/tiledesk-widget-hidden-on-unavailability-example.html) # Show/Hide widget programmatically In this tutorial we will show to you how to manage visualization of widget programmatically using *hide/show* parameters and *open/close* method. Furthermore, we add a subscription to **onClose** tiledesk event to manage close button and hide it on click. First of all you have to set **startHidden** property to true in window\.tiledeskSettings to not show widget when it starts. ```java window.tiledeskSettings= { projectid: "<>", startHidden: true }; ``` Then you have to handle click event of the openWidget and closeWidget buttons in order to programmatically show and hide widget. ```java // programmatically open the widget function openWidget() { window.Tiledesk('show'); window.Tiledesk('open'); } // programmatically close the widget function closeWidget() { window.Tiledesk('close'); window.Tiledesk('hide'); } ``` Finally, to complete, you can optionally subscribe to 'onClose' tiledesk event and use hide method to hide widget when user click on close up right corner icon. ```java //subscribe to onClose Tiledesk event and then hide widget window.Tiledesk('onClose', function(event_data) { window.Tiledesk('hide') }); ``` The entire sample code is presented below. ```html ``` On this page [here](https://replit.com/@tiledesk/Tiledesk-HTML-Site#index.html) you can view the entire code and run it to better understand the results # Force widget loading without user interaction In this tutorial we will show to you how to force the loading of Tiledesk Widget on your website.\ By default widget is not loaded. It will always appear after 5 seconds unless one of the below listed event triggers an earlier start. This prevent your website to load tiledesk resources and improve the entire performance loading. Only once your website is loaded and user move/scroll mouse, tiledesk starts load widget source. Steps to make them is very easy: 1. Copy and paste the basic widget script code 2. Use the window event listener to hook 'load' event 3. Manually fire one of the following event listed: * scroll * mousedown * mousemove * touchstart * keydown Here is the full code example ```html This Tiledesk example will force the loading of the widget ``` ## Force the loading only on mobile platform If you only want to force the loading of the widget on mobile you can add a funtion to detect the platform where the widget is currently running on. ```html This Tiledesk example will force the loading of the widget only on MOBILE PLATFORM ``` # Mobile positioning In this tutorial we will show to you how to better and simply position Tiledesk Widget on your website when in served on mobile browser Steps to make them is very easy: 1. Copy and paste the basic widget script code 2. Set **mobileMarginX** and **mobileMarginY** property inside window\.tiledeskSettings 3. Use the function window\.Tiledesk(‘show’) to show the widget ONLY if some agent is available. Here is the full code example ```html This Tiledesk example will hide the widget if no agent is available
Agents available: loading availability...
``` Here is in detail what exactly **mobileMarginX** and **mobileMarginY** do ![Mobile positioning](https://user-images.githubusercontent.com/47848430/226629891-bf97c1f5-dd3b-48be-ba70-07a2e5bcdbbf.png) # Custom size (width/height) In this tutorial we will show to you how to better and simply change the Tiledesk Widget size on your website Steps to make them is very easy: 1. Copy and paste the basic widget script code 2. Subscribe to **onInit** Tiledesk event 3. Add custom stylesheet to override the default values Here is the full code example ```html This Tiledesk example will change the widget size in height and width as you want
Agents available: loading availability...
``` View result [here](https://tiledesk-html-site-tiledesk.replit.app/widget/customDimension.html) # Installing widget on selected pages This tutorial guides you through setting up the Tiledesk live chat widget to display only on selected pages of your website. By leveraging a custom script, you can include or exclude the widget based on the page's URL. The script checks the current URL and decides whether to load the Tiledesk widget based on defined conditions, and it includes functions for login, logout, and custom authentication. ## Step 1: Define Included/Excluded Pages The script checks the current URL to decide if the widget should be loaded. Here’s how you can set up exclusions: ```javascript const projectId = "63b711fa2ef2e4001a5e4977"; let attributes = {}; if ( (window.location.href.indexOf('/cds') >= 0) || (window.location.href.indexOf('%2Fcds') >= 0) || (window.location.href.indexOf('/dashboard') >= 0) || (window.location.href.indexOf('%2Fdashboard') >= 0) ) { // Pages to exclude: do not start the widget } else if ( ((window.location.href.indexOf('/login') >= 0) || (window.location.href.indexOf('%2Flogin') >= 0) || (window.location.href.indexOf('/signup') >= 0) || (window.location.href.indexOf('%signup') >= 0) ) && screen.width < 800 ) { // Also exclude these pages on mobile devices } else { // startWidget() } ``` In this code, replace /cds, /dashboard, /login, etc., with the specific paths on your domain where you want to exclude or include the widget. ## Step 2: Define the startWidget Function The startWidget function loads the Tiledesk widget with the desired configuration, setting up the project ID and auto-start behavior. ```javascript function startWidget(){ window.tiledeskSettings = { projectid: projectId, autoStart: true }; (function (d, s, id) { var w = window; var d = document; var i = function () { i.c(arguments); }; i.q = []; i.c = function (args) { i.q.push(args); }; w.Tiledesk = i; var js, fjs = d.getElementsByTagName(s)[0]; if (d.getElementById(id)) return; js = d.createElement(s); js.id = id; js.async = true; js.src = "https://widget.tiledesk.com/v6/launch.js"; fjs.parentNode.insertBefore(js, fjs); }(document, 'script', 'tiledesk-jssdk')); } ``` ## Step 3: Additional Control Functions The following functions provide additional control over the widget’s behavior: * tiledesk\_widget\_hide(): Hides the widget. * tiledesk\_widget\_show(): Shows the widget. * tiledesk\_widget\_login(attribute): Logs in the user with a custom attribute. * tiledesk\_widget\_logout(): Logs out the user and signs in anonymously. These functions help manage the widget's state on different pages. ## Step 4: Custom Authentication The customAuth function sends user data to a custom authentication URL, receiving a JWT token that is used to sign in the user with Tiledesk. ```javascript function customAuth(callback) { const storedUser = localStorage.getItem('user'); let user = storedUser ? JSON.parse(storedUser) : null; if (!user) { callback(null); return; } const remote_support_project_userId = projectId + "_" + user._id; var xmlhttp = new XMLHttpRequest(); xmlhttp.open("POST", "https://tiledesk-custom-jwt-authentication.replit.app/tiledeskauth", true); xmlhttp.setRequestHeader("Content-Type", "application/x-www-form-urlencoded"); xmlhttp.onreadystatechange = function () { if (callback && xmlhttp.readyState == 4 && xmlhttp.status == 200 && xmlhttp.responseText) { callback(xmlhttp.responseText); } }; xmlhttp.send("id=" + remote_support_project_userId + "&firstname=" + user.firstname + "&lastname=" + user.lastname + "&email=" + user.email); } ``` ## Step 5: Testing and Verification 1. Verify Included/Excluded Pages: Visit the included pages to confirm the widget appears, and the excluded pages to ensure it remains hidden. 2. Test Login/Logout: Confirm that login and logout behaviors are working as expected, especially for the custom authentication flow. This script provides granular control over where the Tiledesk widget appears, enhancing the user experience by excluding it from specific pages and enabling custom authentication. # Custom widget style In this tutorial we will show to you a simple tutorial of how to override the default style of the widget icon, and how to add a simple animation on hover event on the same element You can use this example to override and change every element of the widget and customize it as you want. Simply remember to subsribe to 'onInit' navite Tiledesk event and append style to the and of the already loaded files Here is a preview of the custom launcher icon override ![Custom launcher icon](https://raw.githubusercontent.com/gab-95/images-host/refs/heads/main/453939446-a14920a4-1c51-4b40-ba5e-a456aa740abd.png) Here is the full code example ```html This Tiledesk example will change the default style of widget launcher icon and add a simple animation hovering it ``` # Custom attributes In this tutorial we will show you how to easily initialize custom attributes in the Tiledesk Widget and use them inside your chatbot flow. We will explain how to define these attributes so they appear in the “System defined” → payload section of your chatbot blocks, how to trigger their initialization when needed, and finally how to dynamically update their values when a specific event occurs (in our example, a button click). The steps to achieve this are very simple: 1. Copy and paste the basic Tiledesk Widget script. 2. Define your initial custom attributes inside the customAttributes field of window\.tiledeskSettings. 3. Listen for the event you want to use as a trigger (in this example, a button click). 4. Update the custom attributes by using the setAttributeParameter method. Here is the full code example ```html replit Hello Tiledesk Widget example page. Tutorial available in Tiledesk developer zone

Here an example to update custom attributes.

Steps:
  1. Open the widget
  2. Start a new conversation (the printed custom attributes should be the initial ones)
  3. Click the "Update attributes" button"
  4. Start again a new conversation (the new printed custom attributes should be the updated ones)


Click the button to update the custom attributes

``` The screen below highlights how to read your defined or updated customAttributes inside the chatbot flow. As shown, the customAttributes JSON data is stored in the **payload** variable under System Defined section. ![Custom Attributes chatbot flow](https://github.com/gab-95/images-host/blob/74c4e40d286f068d5ecb8d309a23555b8bd548c6/custom-attributes-bot.png?raw=true) View result [here](https://tiledesk-html-site-tiledesk.replit.app/widget/custom-attributes_dynamic.html) # Conversation Embedded Apps ## Embedding Apps ![Embedded App example](https://user-images.githubusercontent.com/32564846/161718340-b89817b5-a3d3-45f2-a55e-a0d6b3fc99d5.png) Applications (aka Apps) displayed in the conversation flow are a very useful tool. They allow to achieve two main objectives: 1. Enhancement of the UI. They enhance the interactive and functional power of a conversation 2. Data isolation. They totally isolate the data flow from the conversation **Enhancement of the UI** is obviuous. You can, for example, play an entire video game in the conversation flow, without ever leaving the conversation in the chat. You can also complete a complex input form, that through a chatbot is difficult to fill. There are many use cases where an app running in the conversation increases the end-user perceived interactive power. **Data isolation** is less obvious but probably more important. In Tilesk, the conversational app is an entire web application running on his own web server on the HTTPS protocol. This means that data exchanged with the app is unkonwn by Tiledesk and is exchanged directly between the app and his own backend. This pertains to **privacy** and **security**. Imagine for example that a user should pay for a cart. The chatbot can provide to the user a payment-app where the user is asked about his credit card and these data are directly exchanged with the payment backend, never with Tiledesk. No info about the transaction is stored into the conversation. Through an app only the actors interested in the interaction are involved. ## Conversation-embedded app anatomy An App is just a message of type *frame*. See the [Widget JSON protocol](https://developer.tiledesk.com/widget/advanced/widget-json-protocol#message-with-content-in-iframe) to see the details. !['frame' type message](https://user-images.githubusercontent.com/32564846/161697596-3567a083-7ec7-47f1-bde0-933c7bec6e1b.png) ### Embed App with microlanguage In addition to using the widget JSON protocol, you can better use the [microlanguage](https://docs.tiledesk.com/knowledge-base/response-bot-images-buttons-videos-and-more/) to render the App in the chatbot's reply without knowing weird JSON specifications. ``` tdFrame:APPLICATION_ENDPOINT ``` For example: ``` tdFrame:https://tiledesk-conversational-app.tiledesk.repl.co/chatbot ``` ### App height You can also specify the App height in the conversation, using the followinf format: ``` tdFrame,hHEIGHT:APPLICATION_ENDPOINT ``` For example: ``` tdFrame,h310:https://tiledesk-conversational-app.tiledesk.repl.co/apps/creditcard ``` ![Set App's height with microlanguage](https://user-images.githubusercontent.com/32564846/161760857-2dd0b10b-789e-4c4a-ad79-4e520a5fe7b6.png) With Tiledesk displaying an app to the end-user means to simply send him a message. ## App status It's worth to understand that an app is totally under your control. You are totally responsable of the app data, app features, app Tiledesk and Third party's APIs usage and ...app status! The "app status" is the status of your app in the conversation workflow. Suppose for example that you embedded an App in the conversation to allow users to pay for a cart using their credit card. Wath you want is an App "active" only when the user has to pay, while the app should be in a sort of "inactive" status when the user stopped or terminated his payment. To manage the app status there is a simple way. You can use the *messageId* that comes in the webhook of you application to uniquely identify your application. Consider that in the most frequent use case there is a strict corrispondence between the App and the message where it is displayed into. ![Use the messageId as App's unique reference on your backend](https://user-images.githubusercontent.com/32564846/162071545-99326eca-de53-4931-95bc-35cb20a78427.png) The basic principle is that you can use the unique messageId to uniquely identify the app in the conversation flow and use this same messageId as a unique-id in your Database to save data relative to that app instance, including his status. ## App > Tiledesk APIs interaction Your App can always use *Tiledesk APIs* to communicate with your project, for example to send messages back to your conversation whenever it wants. How? With each webhook payload you receive a **token** that you can use to talk with the conversation where (as a message) the App is hosted into. Just use this token in Tiledesk APIs to call any (allowed) [REST method](https://developer.tiledesk.com/apis/rest-api) you want... ### Send messages to end-users ...but specially the [SendSupportMessage()](https://tiledesk.github.io/tiledesk-nodejs-libs/TiledeskClient.html#sendSupportMessage) method. This is a special method that allows the user to send messages to the conversation where the token belongs to. ![Send messages to the conversation](https://user-images.githubusercontent.com/32564846/162134720-84f37b1f-b52d-473d-aaa0-908d9563a0e6.png) As you can see in the picture sending messages from the App back to the conversation can be very useful. You can for example notify in a graceful and useful manner the end of an operation packed with some useful data. It's now time to face a **Tutorial example**, the [Credit Card payment App tutorial](/widget/widget-app-introduction/widget-app-payment). # Payment App Tutorial ## Introduction During a conversation is sometimes useful providing the user with a method to complete a task through a payment. ![image](https://user-images.githubusercontent.com/32564846/161642865-d7c9f00a-49fb-4a0c-b6a5-54014694e45b.png) Using an app is a secure way to accomplish this task. Using the app the end-user doesn't send any "sensible" payment information as a message in the conversation. He directly interacts with the payment system on the HTTPS protocol, leaving out from Tiledesk informations that Tiledesk absolutely doesn't want :) In this tutorial we'll only build a skeleton application, useful enough to show the basic principles of building a widget app with Tiledesk. We'll cover three basic needs. 1. Create and render an app to be shown and used in the conversation 2. Mark the app as "Terminated" changing his UI behaviour on the task end, avoiding further user interaction 3. Interact with the current conversation, i.e. sending a message, directly from the app code Let's start. ## Create and render an app ### Create a new Project To use Tiledesk APIs or integrate your own chatbots is mandatory to signup a new user on [Tiledesk](https://tiledesk.com/). Then go to the console, available on the following link After signup please follow the proposed wizard to create your first Tiledesk project We choosed "Widget Embedded App" as Project name: ![image](https://user-images.githubusercontent.com/32564846/162209056-dd4217ba-293c-47f6-99c2-bbccc1c3126b.png) As soon as you create the project you will be redirected to the project home (for this tutorial you can jump the last step, relative to the widget installation). ### Create a simple chatbot As first step we will create a simple chatbot. We'll use the chatbot so it can send back a conversation-embedded Application to the end-user who started the chat, asking him to pay for his order using his credit card info. The Application will implement the (fake) payment-logic and will reply to the user with a message showing the payment operation relevant info. Select the chatbot icon on the left menu, then press the "ADD BOT" button: ![image](https://user-images.githubusercontent.com/32564846/162210700-42c5b927-a7c1-4a34-914e-ef2faf7591b2.png) Choose "Resolution bot" as type: ![image](https://user-images.githubusercontent.com/32564846/160479723-f95ef4e5-47a0-4e70-af02-3f36403847bb.png) Set "Shopper" (or whatever you prefer) as the chatbot name and leave the other settings with their default value. Press "CREATE BOT": ![image](https://user-images.githubusercontent.com/32564846/162211018-cc29be2a-8770-4bde-841c-048b73b278fd.png) When asked, choose "Activate bot". In this manner the new chatbot is immediatly available as soon as someone starts a new conversation. ![image](https://user-images.githubusercontent.com/32564846/162211365-7b705564-9fcc-4616-b0ea-a9404b37f947.png) Now, in the Shopper chatbot intents list, select the "start" intent: ![image](https://user-images.githubusercontent.com/32564846/162285884-80b5d7f3-a64e-470f-b3d0-5ab3d2fb0acb.png) Then modify the start intent, adding a *Quick reply* button using the chatbot microlanguage (simply use an asterisk followed by a space and the quick reply text), as this: ![image](https://user-images.githubusercontent.com/32564846/162286307-7a3872d0-d1ec-4305-9f01-f43eee1caac5.png) Now save the answer and go back to the intents list. Add a new answer (+ *New answer* button). Configure the new answer as the following: **Intent**: "payment" **Questions**: "I want to pay" **Answer**: "Showing Paying app (placeholder)..." Do not forget to activate the webhook switch on the bottom "Enable webhook call for this intent". This will forward the webhook reply to the backend logic that we'll add later in the tutorial. ![image](https://user-images.githubusercontent.com/32564846/162287813-5739c1ec-036f-4735-add0-e3566e7bc306.png) ### Create the backend on Replit To develop our app logic, we'll need a web application endpoint where all the chatbot's requests will be forwarded. We'll use the [Repl.it](https://repl.it) service to fast create our own NodeJS web application endpoint. #### Develop your application logic. Let's fork! We simply fork the tutorial application, available at this url: Use the fork button and choose a name for your app: ![image](https://user-images.githubusercontent.com/32564846/162422896-78a544ad-0da9-4f0b-b390-4abb0d2d7dea.png) Once forked go on your replit application and do a little customization. You should set the APP\_ENDPOINT environment var using the option on the left menù, as shown in the figure. You must add to the **replit App endpoint** - in our case ** - the */apps/creditcard* suffix to build the full APP\_ENDPOINT functional to our integration, exactly as shown in the picture. ![Setup the APP\_ENDPOINT](https://user-images.githubusercontent.com/32564846/199575979-e20ed2ad-d1b8-4e9e-9c7f-a08a98bad9fe.png) Now press the *Run* button in the top bar. You application starts, as you can see in the log panel. Now you must connect this application to your *Shopper* chatbot. Go on the Shopper bot in Tiledesk Console, enable [Fullfilment](https://developer.tiledesk.com/resolution-bot/home#fulfillment) and put there the API\_ENDPOINT url of your chatbot using the previuos *Replit App endpoint* followed by the */bot* suffix: ** ![](https://user-images.githubusercontent.com/32564846/162305135-9a063e33-eaf0-49d4-8ae1-3b9dc3e4075a.png) And press the UPDATE BOT button. Now we are ready to see the embedded App in action with our chatbot. ### Let's run To run the example simply choose the "Simulate visitor" button on top of the console of your project. The widget "test page" will open. These are the main steps involved in the interaction: 1. Start a conversation. 2. The chatbot will greet you. 3. Press the "I want to pay" Quick reply button. It will decode the "payment" intent you already built. 4. The intent is connected to the API\_ENDPOINT you setup previously and the reply is dynamically generated by the /bot method 5. The reply sends back to the widget a message containing a "frame" with the API url of the application 6. The user interacts with the application, setting his name 7. The App gets the user data and disables further user interaction 8. The App sends a message back to the user containing his name (got from the app form) 9. The interaction ends. You can try a "live" tutorial [here](https://tiledesk-html-site.tiledesk.repl.co/conversation-embedded-app.html). You can get the source code directly from the replit app. If you have any problems do not esitate to write us on our [Community forum](https://tiledesk.discourse.group/)! See you on our next tutorial! Do you have suggestions on this article? Please send us your feedback writing an email to # Prechat form App Tutorial ## Introduction ![Prechat form in conversation](https://user-images.githubusercontent.com/32564846/165312900-4a7588c8-a408-44d8-a3a8-77ecd99af280.png) The widget's [native prechat form](https://developer.tiledesk.com/widget/advanced/prechat-form-json) is very userful to ask some data before starting a conversation. But sometimes you want let the end-user play around with your chatbot freely, avoiding asking him unuseful sensitive data. Just ask data only when necessary, i.e. just before talking with a human agent! We'll discuss here exactly this use case. We'll build a chatbot, placing it in front of a department. When the user asks for an agent a form appears in the conversation flow that will ask the user some personal info (i.e. email, fullname, telephone). As soon the user fills out the form the chatbot will handoff the conversation to a human agent that can read the user data from the conversation panel. Moreover with this use case you will be free to create your own form, without all the limitations of the widget's native form. In effect your form will be a complete web application shown as an iframe into the widget. You can implement whatever computation or your favourite user interaction. From your app you will be able to talk to Tiledesk using APIs or send messages back into the same conversation where the app is hosted into. In this tutorial we'll cover three basic features: 1. Render the prechat form exactly when the chatbot-human handover occurs 2. Mark the prechat form as "Terminated" changing his UI as soon as the task ends, avoiding further user interaction 3. Ask the prechat form only once to the same user, avoiding asking the same data on each chatbot-human handoff 4. Interact with the current conversation sending a message back to the user indicating a successfull operation Let's start. ## Create and render an app ### Create a new Project To use Tiledesk APIs or integrate your own chatbots is mandatory to signup a new user on [Tiledesk](https://tiledesk.com/). Then go to the console, available on the following link After signup please follow the proposed wizard to create your first Tiledesk project. We choosed "Widget Prechat App" as Project name: ![Create your project](https://user-images.githubusercontent.com/32564846/164986208-86d3223c-ace2-4332-acb5-62b6ed11328b.png) As soon as you create the project you will be redirected to the project home (for this tutorial you can jump the last step, relative to the widget installation). ### Create a simple chatbot As first step we will create a simple chatbot. We'll put the chatbot in front fo a Department so it will absorb all the initial support requests. When unsatisfied by the chatbot replies the user will ask for human. The chatbot, instead of suddenly deflect the conversation to the human will instead open a conversation-embedded Application asking the user to fill it with some data (i.e. his email, fullname). As soon as the form is completed the conversation will be switched to a human agent. The Prechat form application will interact with Tiledesk request-context through APis, filling the context with the info got from the prechat form panel. Select the chatbot icon on the left menu, then press the "ADD BOT" button: ![Chatbot creation](https://user-images.githubusercontent.com/32564846/162210700-42c5b927-a7c1-4a34-914e-ef2faf7591b2.png) Choose "Resolution bot" as chatbot type: ![Chatbot creation](https://user-images.githubusercontent.com/32564846/160479723-f95ef4e5-47a0-4e70-af02-3f36403847bb.png) Set "Helpbot" (or whatever you prefer) as the chatbot name and leave the other settings with their default value. Press "CREATE BOT": ![Chatbot creation](https://user-images.githubusercontent.com/32564846/164986414-e37ede39-8ce6-4bb3-9482-4bc15dd79626.png) When asked, choose "Activate bot". In this manner the new chatbot is immediatly available as soon as someone starts a new conversation. ![Activate chatbot](https://user-images.githubusercontent.com/32564846/162211365-7b705564-9fcc-4616-b0ea-a9404b37f947.png) Now, in the *Helpbot* chatbot intents list, select the "start" intent: ![Select the start intent](https://user-images.githubusercontent.com/32564846/162285884-80b5d7f3-a64e-470f-b3d0-5ab3d2fb0acb.png) Then modify the start intent, adding a [Quick reply](https://developer.tiledesk.com/widget/advanced/widget-json-protocol#quick-replies) button using the chatbot [microlanguage](https://developer.tiledesk.com/resolution-bot/rich-messages#microlanguage) (simply use an *asterisk* followed by a *space* and the quick reply text), as this: ![Add a quick reply to the Start intent](https://user-images.githubusercontent.com/32564846/165066393-4ad37f90-3766-4bc3-94c1-e2d60a088697.png) Now save the answer and go back to the intents list. Add a new answer (+ *New answer* button). Configure the new answer as the following: * Intent: "agent\_handoff" * Questions: "I want an agent" * Answer: "Prechat form (placeholder)..." Do not forget to activate the webhook switch on the bottom "Enable webhook call for this intent". This will forward the reply to the programmatic backend logic that we'll add later in the tutorial. ![Agent handoff intent](https://user-images.githubusercontent.com/32564846/165396321-f81834b8-476c-4f78-952a-be2853c07aeb.png) ### Create the backend on Replit To develop our app logic, we'll need a web application endpoint where all the chatbot's requests will be forwarded. We'll use the [Repl.it](https://repl.it) service to fast create our own NodeJS web application endpoint. #### Develop your application logic. Let's fork! We need tp simply fork the tutorial application, available at this url: Fork the app. Once forked press the *Run* button in the top bar. You application starts, as you can see in the log panel. Connect your application to our chatbot. Go on *Helpbot* in Tiledesk Console, enable [Fullfilment](https://developer.tiledesk.com/resolution-bot/home#fulfillment) and put there the /bot API\_ENDPOINT url that you will build by joining the *replit app endpoint* (see next figure) with the */bot* method. ![replit app endpoint](https://user-images.githubusercontent.com/32564846/165266643-7d3b5b09-c137-4f59-93da-50f998435cec.png) In our case the url is the following: ** ![image](https://user-images.githubusercontent.com/32564846/165267374-dc64e254-6299-4d49-b196-38c3b58898c6.png) And press the UPDATE BOT button. Now we are ready to see the prechatform App in action with our chatbot. ### Let's run To run the example simply choose the "Simulate visitor" button on top of the console of your project. The widget "test page" will open. These are the main steps involved in the interaction: 1. Start a conversation. 2. The chatbot will greet you. 3. Press the "I need agent" Quick reply button. It will decode the "agent\_handoff" intent you already built. 4. The intent is connected to the *fulfillment endpoint* you setup previously and the reply is dynamically generated by the */bot* method 5. The reply sends back to the widget a message containing a "frame" with the *prechat form application* 6. The user fills in the form, setting his name, email, telephone number, and accepting Privacy policy 7. The App gets the user data and disables further user interaction 8. The App sends a message back to the user containing his name (got from the form) 9. The interaction ends. ![From chatbot to human agent through a Prechat Form](https://user-images.githubusercontent.com/32564846/165395959-34de2716-0103-48e4-b856-1003546c9bd6.png) You can try a "live" tutorial [here](https://tiledesk-html-site.tiledesk.repl.co/conversation-embedded-prechat-form-app.html). You can get the source code directly from the replit app. If you have any problems do not esitate to write us on our [Community forum](https://tiledesk.discourse.group/)! See you on our next tutorial! Do you have suggestions on this article? Please send us your feedback writing an email to # Advanced # Preset the Widget on a specific Department Departments are very useful to separate support actions into “domains” of competences. This domains can be served by humans, chatbots or can be served in a hybrid fashion, mixing chatbots with humans handoff. Tiledesk has a very easy way to handle departments. Just go into the Departments section, create your own departments, configure these departments to be served by chatbots, humans or hybrid way: ![deps-705x371](https://user-images.githubusercontent.com/9378770/92229538-f2495f80-eea9-11ea-9331-33dc8a8f6c3d.png) Now simply open the widget in the test page and the departments are shown to the guests of your site every time they will start a new conversation: ![widgt-438x705](https://user-images.githubusercontent.com/9378770/92229579-ff664e80-eea9-11ea-9c2f-d797cc7d2d7b.png) ## The problem But, if you embed the widget in your “pricing” page, you probably don’t want all the new conversations in the page to be constrained choosing a department different by the “Pricing” one. ## Solution In this case, to skip departments selection, you can simply slightly modify the widget code in the page, setting the department ID upon which the widget must start the new conversation. Just add this line of code: ``` departmentID: 'ID-OF-DEPARTMENT' ``` In the position shown by the following picture: ![snippet-dep-450x165](https://user-images.githubusercontent.com/9378770/92229706-2de42980-eeaa-11ea-8166-62a838cd4c5e.png) You can always find the department id in the url of the “Modify Department” view, as shown in the following picture: ![edit-dep-705x304](https://user-images.githubusercontent.com/9378770/92229729-363c6480-eeaa-11ea-9709-26a6b14a7c51.png) If the widget finds this property set, he will always skip the Department selection view, moving the user directly into a conversation in the preset department. # Authentication Flow ## Anonymous authentication ![image](https://user-images.githubusercontent.com/9378770/91860033-6ea22f80-ec6b-11ea-9bfe-c90c446685d3.png) ## Custom authentication ![image](https://user-images.githubusercontent.com/9378770/91860102-87aae080-ec6b-11ea-8b67-18140e53d2e6.png) ## Authentication refresh ![image](https://user-images.githubusercontent.com/9378770/91860117-8d082b00-ec6b-11ea-921e-1b9aeba54718.png) # Widget protocol specs This document describes the raw JSON protocol specifications used by external chatbots (and by Tiledesk itself) to send messages to the widget. You can use this protocol from an [external chatbot](https://developer.tiledesk.com/external-chatbot/integrate-your-chatbot) to customize messages for your end-users. The JSON protocol allows you to discover what kind of content the widget supports, building enhanced chatbot replies for increased user experience that go beyond simple text messages, adding images, special buttons and interaction. New features are costantly added to Tiledesk widget so take a constant reference to this section to keep yourself updated with all the supported widget messages, controls and media that can be rendered in widget messages. ### Resources For a live demo of all the supported features described in this document you can refer to this external chatbot project on *repl.it* that you can use as a showcase of all the wideget features [External-bot widget demo on Repl.it](https://repl.it/@andreasponziell/tiledesk-widget-protocol-example#index.js) You can also see a live demo of this chatbot on this tiledesk live page: [Live demo](https://widget.tiledesk.com/v4/assets/twp/index.html?project_name=Widget+showcase+demo\&tiledesk_projectid=5f8474e99c9f0200125b01c0) ## Text message Sending a text to the widget (from your chatbot, or your generic chat client) really needs a minimal JSON. For example, if you want to send the "Hello" message use the following: ### JSON ``` { text: "Hello" } ``` You can also specify some options: **type** field: optional. the value 'text' is the default one. Use this field to change the message type (e.g. '[image](#message-with-image)'). **senderFullname** field: optional, because Tiledesk knows who he is talking to. But this field is useful to set if you want to change the sender name for some reason. ## Quick replies ![Quick replies](https://user-images.githubusercontent.com/32564846/95662490-abe5c100-0b37-11eb-8621-bfb7f324845c.png) *Quick Replies* (generally sent by chatbots) allow users to quickly reply with a proposed, pre-build option. Pressing the button simply sends the text contained in the button label to the recipient (most of the time the chatbot) on the other side. ### JSON ``` { type: "text", text: "Hello with buttons", attributes: { attachment: { type:"template", buttons: [ { type: "text", value: "REPLY ONE" }, { type: "text", value: "REPLY TWO" } ] } } } ``` ## URL buttons ![URL Buttons](https://user-images.githubusercontent.com/32564846/95662652-c9675a80-0b38-11eb-8bf7-a489dfb7e9ce.png) The URL button opens a link in a new browser tab, the same page hosting the widget or inside the widget itself. A *target* option is used to specify where to open the URL content. It can have the *blank*, *parent* or *self* values. If a value is not specified it defaults to "blank". Buttons of this type have a **small arrow** icon to help the user understand that tapping on a URL button will open a new window. The *self* button is special because it opens the URL content directly inside a special frame of the widget itself. It as a slightly different arrow, pointing to the right orizzontally. ![Self buttons](https://user-images.githubusercontent.com/32564846/140601014-e3967820-7dce-492a-b4f0-353dfbd57188.png) "self" buttons open the URL content in the "Widget frame" mode. In this mode the URL content appears into the same widget’s frame with a special header, showing the button title, a button to go back to the conversation and another button to open the content into a full browser window. ![Widget frame](https://user-images.githubusercontent.com/32564846/140600868-c3093864-d02d-4c72-ba09-acb2b767e7d8.png) You can obtain the best results with "self" option if the content you are displaying plays good with the "responsive" mode, because of the small dimension of the widget makes it act with mobile-device-like responsiveness. ### "blank" mode JSON ``` { type: "text", text: "Hello with buttons (blank)", attributes: { attachment: { type:"template", buttons: [ { type: "url", value: "SITE 1", link: "http://www.tiledesk.com", target: "blank" } ] } } } ``` ### "parent" mode JSON ``` { type: "text", text: "Hello with buttons (parent)", attributes: { attachment: { type:"template", buttons: [ { type: "url", value: "SITE 2", link: "http://www.ietf.org", target: "parent" } ] } } } ``` ### "self" (Widget frame) mode JSON ``` { type: "text", text: "Hello with buttons (self)", attributes: { attachment: { type:"template", buttons: [ { type: "url", value: "Dante", link: "https://en.m.wikipedia.org/wiki/Dante_Alighieri", target: "self" } ] } } } ``` ## Action buttons When a user presses an action button, an “action” message is sent to the chatbot. Your chatbot will receive the "action" field value that you can use to execute some specific actions. Upon receiving the action value, the chatbot can simply reply with a related-to-the-action reply message. If the **show\_echo** option is set to true the widget will also show in the chat the message in the **value** field, giving evidence to the user that a real message was sent to the chatbot. ### JSON ``` { type: "text", text: "Hello with buttons", attributes: { attachment: { type:"template", buttons: [ { type: "action", value: "EXECUTE AN ACTION", action: "my-action-name", show_echo: true } ] } } } ``` #### Action message (replied by the Widget) This format is used by Tiledesk chat clients (e.g. Web Widget) to send a message that contains an action for the backend. The message can be hidden or not on the widget, it doesn’t affect the message behaviour. The backend that receives messages with the “action” field set in the attributes section can choose to take a corresponding action, then optionally reply to the same message. A button with an action message has the same aspect as the standard reply button, but with a different, longest and evident animation. **JSON** ``` { type: "text", text: "This is an action for the backend", attributes: { action: "my-action-name" } } ``` ## Image attachment If you want to send an image from your external chatbot you should embed the image http source in the reply JSON schema shown below. **type** field must be set to **image** **text** field is optional **metadata.src** field is mandatory and must point to a valid image **metadata.width** and **metadata.height** fields are optional. If set they will reduce the image size accordingly in the reply message. ### JSON ``` { type: "image", text: "Hello with image", metadata: { src: "http://www.tiledesk.com/logo.jpg", width: 200, height: 200 } } ``` ## File attachment If you want to send a generic document from your backend to the Tiledesk Widget you should embed the document file http source in the reply JSON schema shown below. **type** field must be set to **file** **text** field is optional **metadata.src** field is mandatory. It must be a valid *http url* containing the document **binary file** **metadata.name** field is optional. It's the file name **metadata.type** field is mandatory. It must be a valid http *content-type* value representing the binary type of the document ### JSON ``` { type: "file", text: "My document is sent as attachment", metadata: { name: "sales-report.pdf", src: "http://www.mywebsite.com/sales-report.pdf", type: "application/pdf" } } ``` ## iframe content messages You can send content to the web widget that can be easily embeddable into an HTML *iframe*. For example you can send a youtube video, an external map, and also a mini HTML5 video game! **type** must be set to 'frame' **text** is optional. **metadata.src** is mandatory and must point to a valid http content embaddable into an HTML5 iframe **metadata.width** and **metadata.height** are optional. If set, they will reduce the iframe size accordingly in the reply message. ### JSON ``` { type: "frame", text: "This is a video!", metadata: { src: "https://www.youtube.com/embed/H1WfFkp4puw" } } ``` ## Disable the reply textbox You can temporarily disable the user input textbox. This feature is useful, for example, when you provide a set of reply buttons and you want the user to press one of these buttons to continue the conversation. **attributes.disableInputMessage** if true the reply textbox is disabled **attributes.inputMessagePlaceholder** if set the reply textbox placeholder is replaced by this text. Used only when *attributes.disableInputMessage* is *true* ### JSON To disable the reply textbox set the above properties in the attributes section, as in the following example: ``` { type: "text", text: "Do you agree? Please press one of the buttons to proceed", attributes: { disableInputMessage: true, inputMessagePlaceholder: 'Press a button to continue', attachment: { type:"template", buttons: [ { type: "text", value: "Yes, I do" }, { type: "text", value: "No, I do not" } ] } } } ``` In the following image, the input textbox is disabled, until the next message arrives. ![image](https://user-images.githubusercontent.com/32564846/144202116-3035b6e0-ba89-4fbb-b15c-fa24ec7825bb.png) ## Update user metadata Sometimes, while interacting with the chatbot, you can ask the user to update his info like his fullname. In this case the widget provides special attributes to update his user info, so he can send new messages with the correct user fullname. You can update user's fullname and email using the following message's properties: **attributes.updateUserFullname**: Use this attribute to update the Widget's new user *full name* **attributes.updateUserEmail**: Use this attribute to update the Widget's new user *email* ### JSON example ``` { text: "Thanks Andrea, we got your data and will take care of it!", attributes: { "updateUserEmail": "andrea@tiledesk.com", "updateUserFullname": "Andrea" } } ``` Once the Widget's receives a message with these attributes it will use the updated fullname and/or email in all subsequest messages. ## Hidden messages Sometimes it's useful to send messages hidden to end-users. For example, if some message should trigger a chatbot message without the user see the actual "question" that triggered that reply. To hide messages to the widget you can use "info" messages. All info messages are hidden to the end-users, but keep in mind that info messages are always visible in teammate chat, as in the following example. ![Info messages always visible in teamate chat](https://user-images.githubusercontent.com/32564846/154105533-ab9dd3ca-4b55-4d3f-83d8-902eec6f71ce.png) **attributes.subtype** set to "info". Hides the message to the end-user channels (Widget, whatsapp, Telegram, Facebook etc.) ### JSON Triggers a chatbot to start a conversation. This message is hidden in the end-users channels: ``` { type: "text", text: "start", attributes: { subtype: "info" } } ``` ## Splitted messages It's a common trend to break long chatbot messages in multiple messages. This can happen on the server side, but there are some issues with this approach, like sometimes unwished unordered messages in the conversation, client "live" reordering (this happens because Tiledesk cannot assure that "very timestamp near" messages arrival order is preserved in the long "message delivery chain". In this cases the "Widget side" splitting is a preferrable approach. You can send all the messages in a single "packet" to the Widget, specifing the "delay" between them. It will be the Tiledesk Widget to render the messages in the exact order, preserving the exact timing between the messages. Let's look at an example: Suppose you want to send these messages as a unique chatbot message, but splitted in multiple messages: ![image](https://user-images.githubusercontent.com/32564846/169641648-4271e7bf-0e20-4356-ab58-e61391ee25f7.png) ### JSON You have to send a single message like the following: ``` { "text": "Hello 👋. I'm a bot 🤖 I'm beautiful Do you need help I can really help you with joy!", "attributes": { "commands": [{ "type": "message", "message": { "text": "Hello 👋. I'm a bot 🤖", "type": "text" } }, { "type": "wait", "time": 500 }, { "type": "message", "message": { "text": "I'm beautiful", "type": "text" } }, { "type": "wait", "time": 1000 }, { "type": "message", "message": { "text": "Do you need help?", "type": "text" } }, { "type": "wait", "time": 2000 }, { "type": "message", "message": { "text": "I can really help you with joy!", "type": "text", "attributes": { "attachment": { "type": "template", "buttons": [{ "type": "url", "value": "Get Help", "link": "https://gethelp.tiledesk.com/articles/install-widget-on-your-website/", "target": "self" }, { "type": "url", "value": "Wikipedia", "link": "https://it.m.wikipedia.org/wiki/E_Street_Band", "target": "self" }] } } } }] } } ``` As you can see from the example above, the effective message is splitted in the *attributes.commands* section of the message JSON payload. The commands are alternated. Each command has a "type" property. * type: 'message' is an effective message. It carries an effective complete 'message' - *message* property, json payload, look at the example above - the real message (a splitted piece of the orginal one) you wish to display. * type: 'wait', it specifies a delay - *time* property, a number, milliseconds, look at the example above - for the next message to display Hope you enjoy to split messages like Tiledesk does! :) ## HTML messagees The widget is able to receive messages containing html tags and render them within the conversation. To do this, server-side the developer should value the **type** field of the message object with '**html**' and insert in the **text** field the HTML code that you want to show on the widget. Furthermore, the widget is currently capable of supporting link buttons as well. Below is a practical example of an HTML message and its rendering inside the widget. ![Html message preview example](https://user-images.githubusercontent.com/47848430/173019659-69e0e537-54ee-4d5b-8049-56ebd03abe7e.png) ### JSON Below we present an example of message json object with html message type ```html { "attributes": {}, "recipient_fullname: ... ... ... "type": "html", "text": `

This is an HTML message type example

Place any html tag to be loaded here...



Button example below 👇🏻



Image example below 👇🏻

`, ... ... } ``` As specified in the example presented, it is also possible, like a normal HTML page, to specify the style inside the **``** tag. The widget inside renders three types of styles, assigned respectively to the css classes *text-html*, *button-html* and *image-container*. The example shows an override of these css classes in order to customize the style of the elements as desired. # Prechat Form JSON specs ## Prechat Form JSON specs ![image](https://user-images.githubusercontent.com/32564846/140908272-673f6e7b-2395-4b5f-a850-7ec233b7be7e.png) ## Table of contents * [Introduction](#introduction) * [Default prechat form](#default-prechat-form) * [Custom Prechat Form](#custom-prechat-form) * [Inspect filled-in user data](#inspect-filled-in-user-data) * [Examples](#examples) * [Example 1: ask the telephone number](#example-1-ask-the-telephone-number) * [Example 2: accepting Privacy and ToS](#example-2-accepting-privacy-and-tos) * [Example 3: ask the first message](#example-3-ask-the-first-message) * [Control types](#control-types) * [Text](#text) * [Textarea](#textarea) * [Checkbox](#checkbox) * [Static](#static) * [Format specification](#format-specification) * [name attribute](#name-attribute) * [Reserved-names](#reserved-names) * [type attribute](#type-attribute) * [mandatory attribute](#mandatory-attribute) * [value attribute](#value-attribute) * [regex attribute](#regex-attribute) * [label attribute](#label-attribute) * [errorLabel attribute](#errorLabel-attribute) * [rows attribute](#rows-attribute) ### Introduction ![image](https://user-images.githubusercontent.com/32564846/140908024-29213c65-3af3-406b-b521-7a695abc01ec.png) The *Prechat Form* is used to collect some end-user data before starting a conversation. Generally this info are asked to guests users, because of authenticated users already providing some "certified" information into a custom JWT. The info collected by the Prechat Form will be used either by Agents, by the Tiledesk platform itself or by developers trough APIs. The prechat form is asked just once to the user, on the first conversation. Once filled and submitted the form data is saved in the browser Local Storage database. If the user wants to fill the prechat form again after the first submission he must "logout" from the widget. This will also change his anonymous user ID. To logout and reset the widget status, press the option menu (gear icon) in the bottom left corner of the widget home screen and click "logout". ### Default Prechat Form To activate the prechat form, got to the Tiledesk Dashboard, then Settings > Widget > Prechat form (section). Open this section and activate the form through the provided switch: ![image](https://user-images.githubusercontent.com/32564846/140116717-e34fa56b-90ff-4171-a332-b8ac63ee9f78.png) If you activate the Prechat Form and no custom format is specified, the default form is shown before starting any conversation. The default form asks the basic info necessary to interact with a Guest user: *email* and a *fullname*. For the default prechat form, *useremail* and *fullname* are required fields. ### Custom Prechat Form The prechat form provides customization, so if email is not enough you can ask a telephone number or you can make the user agree to your terms and conditions before proceeding with a conversation. Custom forms use a special (and easy) JSON syntax to customize the form fields. You can specify the fields type choosing the right "control type" (i.e. text/textarea, checkbox, static text etc.). You can also provide some options, useful to validate the field, show a custom validation error or make the field mandatory or not. Multilanguage for labels is also supported. #### Inspect filled-in user data Once you fill the custom prechat form, the operator can find the filled-in user data in the dedicated section of the conversation detail. Suppose the user fills the custom form of [Example 2](#example-2-accepting-privacy-and-tos) as in the following picture: ![image](https://user-images.githubusercontent.com/32564846/140916378-cae22b99-3aa0-403a-94fb-c9ab61e94226.png) The operator can see the filled-in form data looking at the "Prechat form section" of the conversation detail, as in the following picture: ![image](https://user-images.githubusercontent.com/32564846/140917336-413a6158-13ad-428e-a994-98b919ea4c11.png) ### Examples To understand how prechat form works we can start with some examples. These examples will show how to accomplish some common tasks with the prechat form. We will start asking the user's telephone number. In the second example we'll propose to read & accept a Privacy Policy and finally, in the third example, a form will ask the user to fill the first question in order to proceed to a new conversation. #### Example 1: ask the telephone number In this first example we'll show you how to ask the user telephone number in addition to email and fullname. To customize the prechat form, first sign in the Tiledesk dashboard using your credentials, then choose a project (if you have more then one). Move to the widget section, scroll down to the prechat form section and enable the prechat form using the switch. ![image](https://user-images.githubusercontent.com/32564846/135799563-92771635-3f48-49a3-9aee-901b5ea9db38.png) Now activate the custom form editor using the switch, as in the following figure: ![image](https://user-images.githubusercontent.com/32564846/135799722-be9f5d06-1370-43cd-9053-e546926a6df3.png) You will see the JSON source for an already provided example. Please replace the provided JSON with the following code: ``` [ { "name": "userFullname", "type": "text", "mandatory": true, "label": { "en": "Your name", "it": "Il tuo nome" } }, { "name": "userEmail", "type": "text", "mandatory": true, "regex": "/^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/", "label": { "en": "Your email", "it": "La tua email" }, "errorLabel": { "en": "Invalid email address", "it": "Indirizzo email non valido" } }, { "name": "tel", "mandatory": true, "label": { "en": "Your phone number", "it": "Il tuo numero di telefono" } } ] ``` Now save the pasted source pressing the `UPDATE WIDGET` button. On the top bar, press the green button to open the widget. Now Start a conversation. ![image](https://user-images.githubusercontent.com/32564846/135870494-0a129267-f4e0-431d-9275-e6433452f7e4.png) > **NOTE**: If you don't see the prechat form after starting a conversation, don't panic. You probably already submitted the prechat form. Open the option menu (gear icon) in the bottom left corner of the widget home screen and select "logout". On the next conversation start the form will appear again. We just added a phone number text field to the basic form. As you can guess, the form JSON is an array of "controls". Each control has some attributes that allow to fine tuning the control itself. In this case the first two elements (controls) of the array are a "name" textfield and an "email" textfield. We just focus on the added one, the phone number. The phone number is *mandatory* (mandatory attributes set to true) and we set a couple of multilanguage labels, to show you how multi-language is supported using the languages iso codes (en, it) of the desired languages (English and Italian in this example, respectively). > **Reserved fields names**: While choosing the controls "name" attribute, keep in mind that there are some reserved Tiledesk names: userEmail, userFullname and firstMessage. We discuss about those fields [here](#name) #### Example 2: accepting Privacy and ToS In this example we'll add an option for the user to proceed in the conversation only if "You accept our Terms and Conditions and Privacy Policy". We will add a couple of controls: 1. Static text to show the notice, 2. Checkbox to declare acceptance. We can modify the JSON for the *Example 1*, adding the new controls: Please replace the provided JSON with the following code: ``` [ { "name": "userFullname", "type": "text", "mandatory": true, "label": { "en": "Your name", "it": "Il tuo nome" } }, { "name": "userEmail", "type": "text", "mandatory": true, "regex": "/^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/", "label": { "en": "Your email", "it": "La tua email" }, "errorLabel": { "en": "Invalid email address", "it": "Indirizzo email non valido" } }, { "name": "tel", "mandatory": true, "label": { "en": "Your phone number", "it": "Il tuo numero di telefono" } }, { "type": "static", "label": "Before proceeding in the conversation please agree to our Terms and Privacy Policy" }, { "type": "checkbox", "name": "acceptedTermsPrivacy", "label": { "en": "I agree", "it": "Accetto" }, "mandatory": "true" } ] ``` Now save the pasted source pressing the `UPDATE WIDGET` button. On the top bar, press the green button to open the widget. Now Start a conversation. ![image](https://user-images.githubusercontent.com/32564846/140267086-2745f13f-9b0a-4a67-8712-7d99a4aab43a.png) As you can see the new controls are shown on the footer. If you try to proceed without accepting, the form will block you. ![image](https://user-images.githubusercontent.com/32564846/140267290-2a6b7b23-82b0-492a-a83c-b3c18daafaa4.png) Now check the option to accept the Terms of use and proceed with the conversation 😅 #### Example 3: ask the first message In this example we'll add an option for the user to write the first message before starting a conversation. This option is extremely useful when you don't have a chatbot and you want your agents get in contact with a great first message from the end-user, that exactly describes the problem. Note that with this special field (that uses for the "name" property the reserved value "firstMessage") the widget instantly sends the message to Tiledesk. We will add a new textarea control with *firstMessage* as the value of the *name* property. This will tell Tiledesk to use this value as the first message of the conversation. We can modify the JSON for the *Example 1*, adding the new textarea control: ``` [ { "name": "userFullname", "type": "text", "mandatory": true, "label": { "en": "Your name", "it": "Il tuo nome" } }, { "name": "userEmail", "type": "text", "mandatory": true, "regex": "/^(?=.{1,254}$)(?=.{1,64}@)[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+(.[-!#$%&'*+/0-9=?A-Z^_`a-z{|}~]+)*@[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?(.[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/", "label": { "en": "Your email", "it": "La tua email" }, "errorLabel": { "en": "Invalid email address", "it": "Indirizzo email non valido" } }, { "name": "firstMessage", "rows": 5, "type": "textarea", "mandatory": true, "label": { "default": "Your message for the support team" } } ] ``` Now save the pasted source pressing the `UPDATE WIDGET` button. On the top bar, press the green button to open the widget. Now Start a conversation. ![image](https://user-images.githubusercontent.com/32564846/140522941-3138cfe1-03d8-4f9e-b65f-93b64e44932c.png) You can see the new control, "Your message for the support team", shown as the last one. It's a mandatory field, you must fill it or the form will block you. As soon as you fill the form, the new conversation starts, with the first message appearing as the first one of the conversation. The agent (or the chatbot) will receive it and happily reply 😎 ![image](https://user-images.githubusercontent.com/32564846/140512666-328e7214-32a9-458a-813b-465acbf506e3.png) ### Control types Here follows a list and a description for all the control types actually supported by the Tiledesk prechat form. ### Text This is the default control, it's a simple text field. When *type* is omitted a Textfield control is rendered. You can provide a regex to validate the field. ![image](https://user-images.githubusercontent.com/32564846/140146075-79b748e5-fe09-490a-96e5-9935cf73c977.png) Example: ``` [ { "name": "userFullname", "type": "text", "mandatory": true, "label": { "default": "Your name", "en": "Your name", "it": "Il tuo nome" }, "regex": "/^[a-zA-Z\\s]*$/", "errorLabel": { "default": "Incorrect name, only letters and spaces are allowed", "en": "Incorrect name, only letters and spaces are allowed", "it": "Nome errato, sono permesse solo lettere e spazi" } } ] ``` ### Text - Format specification #### *name* attribute *mandatory* Example: ``` name: “phone” ``` **Reserved names** While choosing the controls "name" attribute, keep in mind that there are three reserved Tiledesk names: 1. *userEmail* It's the email used by Tiledesk to send automated messages. 2. *userFullname* When available it is used to identify the user by his fullname around Tiledesk. 3. *firstMessage* When provided, this value is used as the first message sent by the Widget as soon as the conversation starts. #### *type* attribute *optional*, *case insensitive* For *Textfield* use **text** value. #### *mandatory* attribute *optional*, *boolean* This property denotes if is mandatory to have a value for this control. “mandatory”: true | false Default is *false* If true filling some text is mandatory. #### *value* attribute *optional* The pre-defined value for the field. #### *regex* attribute *optional* If set, the field value will be validated with this regex. Example: ``` "regex" : "/^[a-zA-Z\\s]*$/" ``` #### *label* attribute *optional* This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used. ``` "label": { "default": "Your name", "en": "Your name", "it": "Il tuo nome" } ``` If *label* attribute is not configured, the “name” attribute is used as the control's label. If the *label*'s property value is a *string* (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation. Ex. label as string "email" will use the Tiledesk translation key "email". ``` "label": "email" ``` #### *errorLabel* attribute *optional* If available the errorLabel will be displayed if the regex doesn't match. If not set the standard message is displayed. ``` errorLabel: { "en": "Pattern not valid. Insert only 10-digits number", "it": "Campo non valido. Insersci solo un numero di dieci cifre" } ``` ### Textarea Textarea is a multi-line text input. Use "textarea" value for "type" property to render a Textarea. You can provide a regex to validate the textarea input text. Use the optional property "rows" to render a specific number of initial rows. ![image](https://user-images.githubusercontent.com/32564846/140148740-d1ab3cdb-173a-4727-9470-df1b89f71be4.png) Example: ``` [ { "name": "firstMessage", "type": "textarea", "label": { "default": "Your message" }, "mandatory": true, "rows": 5 } ] ``` ### Textarea - Format specification #### *name* attribute *mandatory* Example: ``` name: “description” ``` **Reserved names** While choosing the controls "name" attribute, keep in mind that there are three reserved Tiledesk names: 1. *userEmail* It's the email used by Tiledesk to send automated messages. 2. *userFullname* When available it is used to identify the user by his fullname around Tiledesk. 3. *firstMessage* When provided, this value is used as the first message sent by the Widget as soon as the conversation starts. #### *type* attribute *optional*, *case insensitive* For *Textarea* use **textarea** value. #### *mandatory* attribute *optional*, *boolean* This property denotes if is mandatory to have a value for this control. “mandatory”: true | false Default is *false* If true filling some text is mandatory. #### *value* attribute *optional* The pre-defined value for the field. #### *regex* attribute *optional* If set, the field value will be validated with this regex. Example: ``` "regex" : "/^[a-zA-Z\\s]*$/" ``` #### *label* attribute *optional* This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used. ``` "label": { "default": "Your name", "en": "Your name", "it": "Il tuo nome" } ``` If *label* attribute is not configured, the “name” attribute is used as the control's label. If the *label*'s property value is a *string* (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation. Ex. label as string "email" will use the Tiledesk translation key "email". ``` "label": "description" ``` #### *errorLabel* attribute *optional* If available the errorLabel will be displayed if the regex doesn't match. If not set the standard message is displayed. ``` errorLabel: { "en": "Pattern not valid. Insert only 10-digits number", "it": "Campo non valido. Insersci solo un numero di dieci cifre" } ``` #### *rows* attribute *optional* 'rows' property specifies the initial number of rows of the Textarea control. ``` { "name": "firstMessage", "type": "textarea", "rows": 5 } ``` ### Checkbox Checkbox represents an HTML checkbox. Use "checkbox" value for "type" property to render a Checkbox. It can only assume two values, 'checked' and 'unchecked'. Use "checkbox" value for "type" property to render a Checkbox. ![image](https://user-images.githubusercontent.com/32564846/140150681-4a5b349a-1638-4340-9c32-f3270797aea6.png) Example: ``` [ { "name": "acceptPrivacy", "type": "checkbox", "label": { "default": "Accept our privacy policy before contacting support" }, "mandatory": true } ] ``` ### Checkbox - Format specification #### *name* attribute *mandatory* Example: ``` name: “accept” ``` **Reserved names** While choosing the controls "name" attribute, keep in mind that there are three reserved Tiledesk names: 1. *userEmail* It's the email used by Tiledesk to send automated messages. 2. *userFullname* When available it is used to identify the user by his fullname around Tiledesk. 3. *firstMessage* When provided, this value is used as the first message sent by the Widget as soon as the conversation starts. #### *type* attribute *optional*, *case insensitive* For *Checkbox* use **checkbox** value. #### *mandatory* attribute *optional*, *boolean* This property denotes if is mandatory to have a value for this control. “mandatory”: true | false Default is *false* In the case of *checkbox* this means that checking the box is mandatory. #### *value* attribute *optional* The pre-defined value for the field. #### *label* attribute *optional* This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used. ``` "label": { "default": "Your name", "en": "Your name", "it": "Il tuo nome" } ``` If *label* attribute is not configured, the “name” attribute is used as the control's label. If the *label*'s property value is a *string* (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation. Ex. label as string "email" will use the Tiledesk translation key "email". ``` "label": "accept" ``` ### Static Static type is simple text. Use "static" value for "type" property to render a Static block of text. You can use simple text or HTML to render more complex pieces of text. ![image](https://user-images.githubusercontent.com/32564846/140153649-cb801282-dde3-422d-8b40-0fd1ad826135.png) Example: ``` [ { "type": "static", "label": { "default": "Accept the Terms before contacting support", "en": "Accept the Terms before contacting support", "it": "Accetta i Termini prima di contattare il supporto" } } ] ``` ### Static - Format specification #### *type* attribute *optional*, *case insensitive* For *Static* use **static** value. #### *label* attribute *optional* This is the control's label. Multilanguage is supported. Simply add the language's ISO code as in the following example to add languages. If no supported language is found, the "default" label value will be used. ``` "label": { "default": "Your name", "en": "Your name", "it": "Il tuo nome" } ``` If *label* attribute is not configured, the “name” attribute is used as the control's label. If the *label*'s property value is a *string* (not a JSON object with ISO language value) the translation is searched in Tiledesk translations using the label's string property as the key for the translation. Ex. label as string "email" will use the Tiledesk translation key "email". ``` "label": "terms" ``` # Prevent multiple conversations ![](https://user-images.githubusercontent.com/47848430/179253313-86628998-8a0b-4127-b7a1-7fd1ac6140be.png) A new feature in Tiledesk widget settings will prevent your customers from starting a new conversation if they already have one open. This change makes conversations more of a continuous thread, preventing customers from reaching out to your team multiple times, which saves your team time and effort. This feature is named as **Single Conversation** ## Overview Tiledesk Widget can handle only one conversation at a time by properly setting the singleConversation property. In fact, just set **singleConversation** to **true** (see how to do this [here](https://developer.tiledesk.com/widget/installation/attributes)) to be able to show the widget user only one conversation at a time. This option disables the possibility of viewing the home with the list of open conversations and those already archived as image below highlight. ![singleConversation](https://user-images.githubusercontent.com/47848430/179259137-42b932b1-1312-44c7-83c6-9534d39905bf.png) Once the user has been authenticated, the widget proceeds with the normal initialization flow of a new conversation only if the user has no active conversation previously, otherwise, the widget will load the most recent active conversation ## How to set *singleConversation* mode As with the other widget setting parameters, **singleConversation** mode can be enabled in various ways: as a url parameter or as a property of tiledeskSettings. ### Set property from **tiledeskSettings** You can passing the parameters to **window\.tiledeskSettings** object as shown in the example below ```html ``` The above script can start widget with the single conversation mode, immediately ### Set property from **URL** You can pass the a tiledesk widget property as a Url parameter with the **tiledesk\_** prefix. For example, in this case: ``` https://widget.tiledesk.com/6/assets/twp/index.html?tiledesk_projectid=&tiledesk_singleConversation=true ``` ## Make a Sign Out In this mode, the user can still logout from the system by using the menu at the top right corner in the conversation header, as shown in the figure below. ![](https://user-images.githubusercontent.com/47848430/179550749-cef51928-5d64-4f13-b70b-54f99ff7feeb.png) Once you have make a sign out, widget restarts itself and create a new user. New initialization flow of a new conversation starts and new user can starts to chat again!! # Old versions # Web SDK v4 #### Web SDK ver 4.0 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: ``` ``` To get your TILEDESK\_PROJECT\_ID go to the TileDesk Dashboard and click on the Widget item of the menu: ![](https://raw.githubusercontent.com/chat21/chat21-web-widget/master/docs/tiledesk-dashboard-widget-screenshots.png) ### Configuration Widget version 4.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. * **wellcomeTitle**: The welcome title to show on the widget home page. * **wellcomeMsg**: 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 componenent. 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. * **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) * **departmentID:** to skip departments selection, you can set the department ID upon which the widget must start the new conversation. See the turorial [here](/widget/advanced/preset-department). * **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. Permittet 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" * **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. Permittet 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. * **isLogEnabled**: Enable the widget log. Value type: boolean. The default value is false. #### Example 1. Widget with user fullname and email ``` ``` #### Example 2. Widget with preChatForm and left alignment: ``` ``` ### Configuration using URL parameters You can also pass the above configurations as a Url parameter with the **tiledesk\_** prefix. For example: ``` https://widget.tiledesk.com/v4/index.html?tiledesk_isOpen=true&tiledesk_align=right ``` ## Methods ### Open the widget This will open the widget: ``` window.tiledesk.open(); ``` ### Minimize the widget This will minimize the widget: ``` window.tiledesk.close(); ``` ### Hide the widget This will hide the widget: ``` window.tiledesk.hide(); ``` ### Show the widget This will show the widget: ``` window.tiledesk.show(); ``` ### 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. ``` window.tiledesk.reInit(); ``` ### Signin with JWT Custom Token This method make a signin using a JWT Custom Token as described [here](/widget/auth). ``` window.tiledesk.signInWithCustomToken(customJwt); ``` ### Make a logout This will logout the widget: ``` window.tiledesk.logout(); ``` ### Show or hide the PreChatForm This parameter configures the PreChatForm visibility: ``` window.tiledesk.setPreChatForm(true|false); ``` ### Send a message to a support conversation This method sends a message to the current 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 The function tileDeskAsyncInit is called when the basic apis of the widget are loaded. Inside the tileDeskAsyncInit function the object window\.tiledesk is defined and can be used. ### window\.tiledesk.on(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 | | 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 | | 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](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) | #### Example 3. Logging of widget events ``` ``` [Full example here](https://github.com/chat21/chat21-web-widget/blob/master/src/test.html) ### 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 ``` ``` [Full example here](https://github.com/chat21/chat21-web-widget/blob/master/src/test.html) #### Example 5. Widget with welcome message with current date ``` ``` ### 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 | Object | the message that is being sent | Example. Programmatic setting custom user metadata ``` ``` [Full example here](https://github.com/chat21/chat21-web-widget/blob/master/src/test.html) Example. Add a custom attribute (page title) to the message. ``` ``` [Full example here](https://github.com/chat21/chat21-web-widget/blob/master/src/test.html) ### After messsage sent This event is generated after the message has been sent. Important payload of event\_data: | Parameter | Type | Description | | --------- | ------ | ------------------------- | | detail | Object | the message that was sent | Example: ``` ``` ### 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 | number | Possible values: 0 if wasn't logged( with autoStart false), 200 already logged, 201 new login, 400 error, -2 from reinit method, -1 from logout | | 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: ``` ``` ### 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: In the following example Departments are filtered based on the current widget language. Actually a Deparment doesn't provide a specific "language" field. In this example Department language is put in the Department description field. A next update will provide specific Department "tags" (or "lables") that will be used to save specific informations into the Department resources. ``` ``` ### 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: 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. ``` ``` ### 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: ``` ``` ### 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: ``` ``` ## 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](/widget/auth) # Accessibility statement doc **Document type:** Consolidated alignment statement and implementation inventory\ **Language:** English\ **Last update:** 2026-05-12 This document describes **capabilities and patterns that are present** in the product engineering. It is **not** a legal certificate, VPAT, or third-party audit report. *** ## 1. Purpose and scope This statement describes how the Tiledesk chat widget product line positions its user interface engineering relative to internationally recognised accessibility norms. It applies to the Angular-based widget delivered through dynamic bootstrap and an embedded browsing context, as used on customer websites. The scope is the interactive widget experience (launcher, conversations, forms, media, and related overlays) as implemented in this codebase. This statement may be shared with customers, integrators, or accessibility specialists as **context** for how the widget is built and maintained. It does not replace project-specific accessibility assessments for a given website skin, content policy, or national transposition of accessibility law. *** ## 2. Reference frameworks (informative) Accessibility work on this product is informed by the following technical and regulatory reference layers, which organisations commonly use when specifying digital accessibility for public-sector procurement and enterprise risk management: | Reference | Role in product engineering | | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **W3C Web Content Accessibility Guidelines (WCAG) 2.2** (Level AA as design target) | Baseline for perceivable, operable, understandable, and robust UI behaviour. | | **W3C Accessible Rich Internet Applications (WAI-ARIA) 1.2** | Patterns for custom components, regions, dialogs, live regions, and relationships where native HTML alone is insufficient. | | **ETSI EN 301 549** (European accessibility standard for ICT products and services, including WCAG 2.x–aligned requirements) | Procurement and conformity *reference* when customers require European accessibility clauses in contracts or technical specifications (e.g. chapters 9, 11). | Formal conformity claims for a specific deployment remain the responsibility of the deploying organisation and are typically supported by independent evaluation against the applicable version of WCAG and any regional transposition of EN 301 549. *** ## 3. Engineering posture (state of the art) The widget is implemented as a focused single-page application within an iframe, with a parent-page bootstrap script responsible for embedding. Engineering attention is directed toward: * **Semantic controls and naming:** Primary navigation and chrome actions use native `button` elements where the interaction model is activational; icon-only controls are paired with translatable `aria-label` (or equivalent) text from the product’s translation maps. * **Structured regions and bypass:** Conversation views use landmark-style regions (for example `role="region"`) and skip affordances so keyboard users can move efficiently to the message composer. * **Modal and overlay semantics:** Key flows such as customer satisfaction rating, department selection, and pre-chat entry use dialog semantics (`role="dialog"`, `aria-modal`, labelling) consistent with WAI-ARIA dialog guidance, with focus management support via Angular CDK where applied. * **Forms and errors:** Dynamic form fields support programmatic association of labels, required state, invalid state, and error descriptions via ARIA relationships; error content uses live semantics where appropriate for time-sensitive feedback. * **Rich content:** Components for audio playback, carousels, and image preview follow patterns that expose control state and mark decorative graphics appropriately for assistive technologies. * **Motion and perception:** Stylesheets include reduced-motion handling so that users who prefer less animation receive a calmer visual experience. * **Embedding context:** The host iframe is given a descriptive title in the bootstrap layer so that the embedded application is identifiable in browsing contexts that surface frame titles. Testing and quality assurance combine static template review, build verification, diagnostics, manual keyboard walk-through, screen reader smoke tests, and reduced-motion verification, in line with common industry practice for complex widgets. *** ## 4. Document metadata | Field | Value | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Product | Tiledesk Web Widget | | Package | `@chat21/chat21-web-widget` | | Version | 5.1.33 | | Stack | Angular 18.2.x (NgModule bootstrap), Angular CDK 17 (`A11yModule`), iframe-hosted (`launch.js`) | | Standards orientation | WCAG 2.2 Level AA, WAI-ARIA 1.2 Authoring Practices, EN 301 549 v3.2.1 (informative reference for ICT accessibility chapters aligned with WCAG) | | Document language | English | *** ## 5. Accessibility engineering coverage (summary) The table below is the **engineering self-assessment summary** used internally to track breadth of accessibility work across product areas. Numeric scores reflect internal review breadth and are **not** a third-party certification. Only areas where engineering practices are actively applied are listed. | Area | Score (0–5) | Conformance level targeted | | ------------------------------- | ----------- | ----------------------------------------------------- | | Semantic HTML | 4.5 | WCAG 2.2 AA | | Keyboard accessibility | 4.5 | WCAG 2.2 AA | | ARIA compliance | 4.5 | WAI-ARIA 1.2 | | Forms accessibility | 5.0 | WCAG 2.2 AA | | Dialog / Modal accessibility | 4.5 | WAI-ARIA 1.2 (focus trap via Angular CDK) | | Live regions / SR announcements | 4.0 | WCAG 4.1.3 | | Reduced motion / animations | 5.0 | WCAG 2.3.3 / 2.2.2 | | Internationalization | 4.5 | WCAG 3.1.1 / 3.1.2 | | Iframe integration | 4.5 | WCAG 2.4.1 / 4.1.2 | | **Overall self-assessment** | **4.5 / 5** | **WCAG 2.2 AA — engineering-oriented implementation** | *** ## 6. Project overview | Topic | Detail | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Bootstrap mode** | NgModule (`AppModule`) via `platformBrowserDynamic().bootstrapModule(AppModule)` (`src/main.ts`). The compiled bundle is injected into a same-origin iframe by `src/launch.js`, which builds and styles `#tiledesk-container` in the host page. | | **Standalone components** | Not used; components are declared in `AppModule` (`src/app/app.module.ts`). | | **Routing** | Not used at runtime: navigation between `home`, `list-conversations`, `conversation`, `selection-department`, `prechat-form`, `star-rating-widget`, `error-alert` is driven by template flags inside `AppComponent`. | | **i18n** | `@ngx-translate/core` 16 with JSON dictionaries in `src/assets/i18n/{en,it,es,fr}.json` plus an optional remote dictionary. Active language is propagated to `` in the widget document. | | **Accessibility libraries used** | `@angular/cdk/a11y` (`A11yModule`) — focus trap support for modals where integrated. | *** ## 7. Component inventory and accessibility highlights The widget exposes 30+ components. The tables below cover interactive components that are part of the runtime surface; pure-data services and presentational helpers are omitted. ### 7.1 Shell components | Component | Selector | Role / landmark | Accessibility highlights | | ---------------------------- | -------------------------- | ---------------- | ----------------------------------------------------------------------------- | | `AppComponent` | `chat-root` | Application root | `:focus-visible` ring scoped to `chat-root`; `prefers-reduced-motion` honored | | `LauncherButtonComponent` | `chat-launcher-button` | `