Javascript API: Attributes
Configuration with tiledeskSettings
You can customize the widget by setting parameters on the window.tiledeskSettings object.
Javascript API
Visual attributes
These attributes modify general widget behaviour.
projectid
string
The Tiledesk project id. Find your Tiledesk ProjectID in the Tiledesk Dashboard under the Widget menu
departmentID
string
To skip departments selection, set the department ID upon which the widget must start the new conversation (see the tutorial: https://developer.tiledesk.com/widget/advanced/preset-department)
welcomeTitle
string
The welcome title shown on the widget home page
welcomeMsg
string
Widget welcome message
widgetTitle
string
Widget title label shown in the widget header. Default: "Tiledesk"
calloutTitle
string
Title of the callout window
calloutMsg
string
Message of the callout window
calloutTimer
integer
Proactively open the chat window: -1 (disabled), 0 (immediately) or positive integer seconds (e.g. 5)
logoChat
string
URL of the logo shown on the widget home page
lang
string
ISO 639 two-letter code to force widget language. Widget will try browser lang first; default "en"
recipientId
string
Enable the widget to open a specific conversation
userFullname
string
Current user fullname (visitor)
userEmail
string
Current user email address (visitor)
persistence
string
How authentication state persists with the Tiledesk JS SDK. Permitted: local, session. Default: local
singleConversation
boolean
If true, the widget becomes a single conversation channel (see: https://developer.tiledesk.com/widget/advanced/singleConversation-mode)
typingLocation
string
Location of typing indicator: 'content' (default) or 'header'
Style attributes
These attributes modify widget appearance (theme color, position, size, etc.)
align
string
Position of chat: 'right' or 'left'. Default: 'right'
marginX
string
Side margin (left/right depending on align). Default: "20px"
marginY
string
Distance from page bottom. Default: "20px"
mobileMarginX
string
Side margin on mobile. Default: "0px". (See: https://developer.tiledesk.com/widget/tutorials/widget-mobile)
mobileMarginY
string
Bottom distance on mobile. Default: "0px". (See: https://developer.tiledesk.com/widget/tutorials/widget-mobile)
size
string
Widget size: 'min', 'max', 'top'. Default: "min"
themeColor
string
Main widget color. Hex (e.g. #87BC65) or RGB (rgb(135, 188, 101))
themeColorOpacity
number [0..100]
Opacity of theme color in backgrounds. Default: 50
themeForegroundColor
string
Text and icon color. Hex or RGB
launcherWidth
string
Launcher width. Default: "60px"
launcherHeight
string
Launcher height. Default: "60px"
baloonImage
string
Balloon image URL. Min size: 60x60px. Allowed formats: .jpg, .jpeg, .jfif, .JPG, .JPE
baloonShape
string
Balloon border-radius. Accepts 1–4 values or percentage (e.g. "50%"). Default: "50%"
fullscreenMode
boolean
If true, chat opens in fullscreen. Default: false
General settings attributes
General settings for the widget.
allowTranscriptDownload
boolean
Allow user to download chat transcript (button appears when chat closed by operator). Default: false
allowReopen
boolean
Allow continuing to write in archived conversations. Default: false
hideHeaderCloseButton
boolean
Hide the close button in widget header. Default: false
hideHeaderConversationOptionsMenu
boolean
Show/hide options menu in conversation header. Default: false
hideCloseConversationOptionMenu
boolean
Show/hide 'Close chat' option in conversation header menu. Default: false
hideRestartConversationOptionsMenu
boolean
Show/hide 'Restart chat' option in conversation header menu. Default: false
hideSettings
boolean
Show/hide options menu in home component. Default: false
openExternalLinkButton
boolean
Open action-button links externally. Default: true
showWaitTime
boolean
Show expected agent response time in home widget. Default: true
dynamicWaitTimeReply
boolean
Share the average response time of the team. Default: true
showAvailableAgents
boolean
Show available agents with avatar in home widget. Default: true
showLogoutOption
boolean
Show logout option in home widget. Default: false
showAttachmentButton
boolean
Show/hide attachment button in conversation footer. Default: true
showAllConversations
boolean
Show/hide list of all conversations. Default: true
soundEnabled
boolean
Enable sound on new message. Default: true
open
boolean
Widget status: true (open) or false (closed) on load. Default: false
isLogEnabled
boolean
Enable widget log. Default: false
logLevel
string
Log level: 'ERR' < 'WARN' < 'INFO' < 'DEBUG'. Default: 'ERROR'
startFromHome
boolean
If false, widget starts directly with a new conversation; if true shows the home component. Default: true
autoStart
boolean
—
startHidden
boolean
Start widget in hidden mode. Default: false
preChatForm
boolean
Require customers to enter info (name, email) before sending a message. Default: false
preChatFormJson
Array
Customize pre-chat form fields. (See: https://developer.tiledesk.com/widget/advanced/prechat-form-json)
customAttributes
Object
Custom key-value attributes. Keys/values must be strings. Special keys 'userFullname' and 'userEmail' set user info from external sources.
nativeRating
boolean
Show/hide widget rating page. Default: true
showInfoMessage
string
Comma-separated list of info message keys to show in conversation (e.g. MEMBER_JOINED_GROUP,CHAT_CLOSED). Default: 'MEMBER_JOINED_GROUP'
restartConversation
boolean
When singleConversation is enabled, if true forces a new conversation at each page refresh/widget restart. Default: false
participants
boolean
If true allows talking only with specific users passed as comma-separated list of ids (e.g. 'ID_user1,ID_user2')
fileUploadAccept
string
Allowed file types for attachments. Default: 'image/*,.pdf,.txt'. See: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/accept#unique_file_type_specifiers
Message style attributes
Modify message appearance (bubble colors, buttons, font sizes, etc.)
bubbleSentBackground*
string
Sent message bubble background color (Hex or RGB)
bubbleSentTextColor*
string
Sent message text color (Hex or RGB)
bubbleReceivedBackground
string
Received message bubble background color (Hex or RGB)
bubbleReceivedTextColor
string
Received message text color (Hex or RGB)
fontSize
string
Font size for bubble messages (e.g. "1.4em"). Allowed values: medium, xx-small, x-small, small, large, x-large, xx-large, smaller, larger, length, or %. Default: "1.4em"
buttonFontSize
string
Font size for attachment buttons. Default: "15px"
buttonBackgroundColor
string
Background color for attachment buttons (Hex or RGB)
buttonTextColor*
string
Text color for attachment buttons (Hex or RGB)
buttonHoverBackgroundColor*
string
Background color for attachment buttons on hover (Hex or RGB)
buttonHoverTextColor
string
Text color for attachment buttons on hover (Hex or RGB)
*These properties, if not provided, will be automatically calculated starting from themeColor.
Widget visibility
Manage visibility on desktop and mobile.
displayOnDesktop*
boolean
Display/hide widget on desktop. Default: true
onPageChangeVisibilityDesktop*
string
Widget state on page load/change on desktop: 'open', 'close', 'last'. Default: 'close'
displayOnMobile
boolean
Display/hide widget on mobile. Default: true
onPageChangeVisibilityMobile
string
Widget state on page load/change on mobile: 'open', 'close', 'last'. Default: 'close'
Message style attributes helper schema:
Social channels attributes
(Available only in the window.tiledeskSettings object)
These attributes allow adding buttons to reach your social channels (WhatsApp Business, Facebook Messenger page, Telegram). Buttons appear at the bottom of the home page.
whatsappNumber
boolean
Allow users to start a conversation on your official WhatsApp Business account
messangerPageTitle
boolean
Allow users to start a conversation on your official Facebook Page with Messenger
telegramUsername
boolean
Allow users to start a conversation on your official Telegram account
Read-only properties
isShown
string
Returns visibility of the whole widget including the balloon. Use window.tiledesk.show() and window.tiledesk.hide() to change visibility.
Configuration using URL parameters
You can pass the same configurations as URL parameters with the tiledesk_ prefix. Example:
Examples
Example: Widget with user fullname and email
Example: Widget with preChatForm and left alignment
Example: Widget with custom attributes
You can pass custom attributes as a key-value object in window.tiledeskSettings or as URL parameters with the tiledesk_customAttributes prefix.
customAttributes are shown in conversation detail as payload keys under the attributes accordion:
To set userFullname or userEmail from an external source (for example, from your mobile app after an internal login):
Previous: Javascript API: Methods — https://developer.tiledesk.com/widget/methods Next: Javascript API: Listeners/Events — https://developer.tiledesk.com/widget/events
Last updated 2 months ago
Privacy: This page references the Tiledesk privacy policy: https://tiledesk.com/privacy.html