Customise Your TIMIFY Booking Widget: Advanced Settings
Here is what you need to know:
If you just want the basics on how to integrate our booking widget, check out our article how to embed the TIMIFY booking widget in your website or CMS.
In this article we dive deep, and show you how to make customisations that deliver really impressive results. We give you the script you need to do things like change the colour of your widget overlay, pre-select a service, or pre-fill customer details.
Here is how the article is structured:
Customisation Options for a Booking Widget Overlay
1.1 General and Layout Related Attributes
1.2 Service Related Attributes
1.3 Resource Related Attributes
1.4 Date Related Attributes
1.5 Customer Related Attributes
1.6 Customisation Related Attributes
1.7 Trigger the Rescheduling for a Specific Booking
1.8 Display Hidden Booking Slots from a Pre-reservation
1.9 Tracking Marketing Campaign ConversionsCustomisation Options for a Booking Widget iFrame
2.1 General and Layout Related Parameters
2.2 Service Related Parameters
2.3 Resource Related Parameters
2.4 Date Related Parameters
2.5 Customer Related Parameters
2.6 Customisation Related Parameters
2.7 Trigger the Rescheduling for a Specific Booking
2.8 Display Hidden Booking Slots from a Pre-reservation
2.9 Tracking Marketing Campaign Conversions
1. Customisation Options for a Booking Widget Overlay
STEP 1:
In TIMIFY, go to Integration -> Booking Widget -> Booking Button/Overlay, and select “flexible position”.
STEP 2:
The flexible position doesn’t include the "data-id" attribute, as your booking ID lies within the HTML element that you have just defined as your booking button.
As you’re going to edit the appearance and positioning of the button, the parameter "data-position" needs to have the value “flexible".
Paste the snippet code right before the </head> or the </body> tag of your template.
STEP 3:
Now let's define the HTML element on your website that allows the browser to open the widget. You usually have one of the following HTML elements:
However, you can choose any other HTML tag for your button. Please always note that you need to:
add a class "timify-button" for the element to which the snippet refers
add the attribute "data-account-id=" with your TIMIFY booking ID within the ""
Attributes you can add to your code to customise the widget and/or the booking workflow
Use the below list of attributes (we’ve added handy explanations!) to adjust your widget, so that you can make it appear exactly how you like. Attributes can be integrated into existing buttons as follows.
Let's say you would like to pre-select a service when a certain booking button on your page is clicked. In this case you would have to put the attribute data-service-id="5f6cbdb98e434611ef5bbf73" to your button element:
<div class="timify-button" data-account-id="5f6cbd042e148e11ac2acaad" data-service-id="5f6cbdb98e434611ef5bbf73">Book a massage</div>
If you would like to pre-select a service globally for all your buttons via your JavaScript code then simply add the attribute to the TIMIFY JS snippet:
<script async
src="//book.timify.com/widget/widget.min.js"
id="timify-widget"
data-position="flexible"
data-account-id="5f6cbd042e148e11ac2acaad"
data-service-id="5f6cbdb98e434611ef5bbf73">
</script>If you are loading your button elements dynamically, after your page is loaded, then you can use the following JS function to trigger an opening of the widget:
TimifyWidget.openIframe({ accountId: '...' });
For this particular case you should use the parameters as defined here.
Here is a list with all supported attributes for the TIMIFY booking widget integration as an overlay:
1.1 General and Layout Related Attributes
Attributes | Description | Example |
data-account-id | Use this to load your account or a specific branch to the widget. |
|
data-is-external-id | Use this to load a specific branch from your Branch Manager to the widget by using a pre-defined external id. |
|
data-enterprise-id | Use this to load the location finder as a first step of your widget. Works only if you have a TIMIFY Branch Manager account with more then 1 location. |
|
data-hide-close-button | Use this to hide the close button of the widget. This is a 'boolean'. The value can be only true or false. |
|
data-fullscreen | Use this to open the widget in full screen mode. This is a 'boolean'. The value can be only true or false. |
|
data-overlay-color | Use this to change the background colour of the overlay that covers your website when the widget is triggered (the background colour behind the widget). |
|
data-overlay-opacity | Use this to change the opacity of the background colour of the overlay. |
|
data-locale | Use this to pre-select a specific language for the booking widget. French: Italian: Spanish: Dutch: Danish: Bulgarian: |
|
data-position | Use this to allow multiple buttons to be positioned on the same page. |
|
data-custom-button-image | Use this to replace the standard TIMIFY button that appears on the right or left hand side of your website with an individual button graphic of your choice. |
|
data-button-attribute | Use this to allow the attribute |
|
data-show-company-name-in-header | Use this if you have multiple accounts/locations via the TIMIFY Branch Manager to display the name of the selected location from the Location Finder. This is a boolean. |
|
data-placeholder | Use this if you want to dynamically place the widget within a DIV element in your page layout. |
|
data-display-weekly-view | Use this to overwrite the company setting of displaying the weekly view in the booking slots step. It defaults to showing the slots with the day by day layout. |
|
data-horizontal-calendar-layout | Use this to force-display a horizontal week day picker instead of the default Date selectbox. |
|
data-show-locations | Use this attribute to show select Branch Account locations
|
|
data-hide-locations | Use this attribute to hide select Branch Accounts, before the services display.
|
|
1.2 Service Related Attributes
Attributes | Description | Example |
data-show-services | Use this to only show a number of pre-defined services in the first step of the booking widget. |
|
data-show-services-external-ids | This attribute has the same function as data-show-services, but using the external Id of the services instead. |
|
data-hide-services | Use this to hide some pre-defined services in the first step of the booking widget. Make sure to use the ID of the respective service - you can find this on the service details page. You may use multiple service IDs - just make sure to separate them with commas. |
|
data-hide-services-external-ids | This attribute has the same function as data-hide-services, but using the external Id of the services instead. |
|
data-service-id | Use this to pre-select a service of your choice and skip the first step of the widget by using the ID of the service in TIMIFY |
|
data-service-external-ids | Use this to pre-select a service of your choice and skip the first step of the widget by using the external ID you've defined for it. |
|
data-course-id | Use this to pre-select a group service of your choice and skip the first step of the widget by using the ID of the group. |
|
1.3 Resource Related Attributes
Attributes | Description | Example |
data-resource-id | Use this to automatically pre-select a resource of your choice using its ID. |
|
data-resource-externalids | Use this to automatically pre-select a resource of your choice using the external ID you've defined for it. |
|
data-filter-resources | Use this to filter the resources in the booking widget and only show the selected resources using their TIMIFY IDs. |
|
data-filter-resources-by-external-id | Use this to filter the resources in the booking widget and only show the selected resources using the external ID you've defined for them. |
|
data-show-selected-resource-only | Use this to display only the pre-selected resource in the resource overview. This is a boolean. |
|
data-show-resources | Use this to overwrite the Widget Setting that hides the resources by default. In order for this to work you should first go to Settings > Bookings > Booking Widget and from there activate the switch-box in the section Resource Display. This will lead to hiding by default your resources from all customers that see your widget. When you use this attribute you can overwrite this setting and display the resource select component in some cases to your customers. |
|
1.4 Date Related Attributes
Attributes | Description | Example |
data-date | Use this to automatically pre-fill and display the free slots on a specific date. |
|
data-date-range | Use this to filter a pre-defined period for the date selection and display ONLY the available slots within this period. |
|
data-disable-other-dates | Use this to block the user from selecting any other date then the pre-filled one. This is a boolean. |
|
1.5 Customer Related Attributes
Attributes | Description | Example |
data-show-guest-booking-form | Use this to display only the guest booking as the authentication method for your bookers. This is a boolean. |
|
data-skip-customerfields-section | Use this to skip showing the guest booking form and directly display the booking confirmation view. |
|
data-hide-filled-fields | Use this to hide pre-filled data fields in the booking overview. |
|
data-external-customer-id | Use this to pre-select an already existing customer in TIMIFY by providing it's external ID. |
|
data-guest-firstname | Use this to pre-fill the booker's first name automatically in the guest form. |
|
data-guest-lastname | Use this to pre-fill the booker's last name automatically in the guest form. |
|
data-guest-email | Use this to pre-fill the booker's email automatically in the guest form. |
|
data-guest-phone | Use this to pre-fill the booker's phone number automatically in the guest form. |
|
data-guest-phonecountry | Use this to pre-fill the booker's phone country code automatically in the guest form. |
|
data-customer-field-1 | Use this to pre-fill any custom data field that you've enabled in the booking form. If you have multiple custom data fields that you want to pre-fill it is important to give each of them a unique attribute name. So in the above example if now I want to pre-fill another field, where I ask my booker what food they prefer, since we already use the attribute name |
|
data-ext-customer-field-1 | Use this to pre-fill any custom data field that you've enabled in the booking form using an external Data Field ID. |
|
1.6 Customisation Related Attributes
Attributes | Description | Example |
data-customization-id | Use this to overwrite the default company or enterprise widget customisation. For example you can trigger a special widget customisation when a specific service or a resource is pre-filled. |
|
data-template-customization-id | Use this to overwrite the default company or enterprise email template customisation. For example you can trigger a special email template customisation when a specific service is pre-filled or you are triggering the widget from a different medium - let's say you have one customised widget for your website and a different one for your mobile app. |
|
1.7 Trigger the Rescheduling for a Specific Booking
If you're using the TIMIFY REST API and let's say you want to display all booked appointments that will take place in the future in the customer's section of your app or website so your customers can easily reschedule a particular booking from there. You can trigger a rescheduling process for a specific booking by providing both the data-event-id and data-secret of the booking. Usually you would obtain these if you have subscribed to receive a webhook with the scope EVENT-CREATED. The secret for cancellation or rescheduling can be obtained only via webhook and can be found in the metadata.
Attributes | Description | Example |
data-event-id | This is the id of the booking in TIMIFY. |
|
data-secret | This is the secret for the booking in TIMIFY. |
|
1.8 Display Hidden Booking Slots from a Pre-reservation
In TIMIFY, currently available only via the Booking Links App, you are able to pre-reserve a specific slot or a range of slots within a date range and make those available only to customers who have a special access to your widget that reveals them by parsing a secret key of that pre-reservation. Using the data-pre-reservation-key you can parse this secret to the widget and reveal the otherwise hidden slots. Let's say you want to make Thursday the 25th of October 2021 between 15:00 and 17:00 available ONLY to some selected customers of yours. You can create a pre-reservation for that day and time range and you will block it for all your regular customers. Then by parsing the secret key of the pre-reservation in your booking widget you can make this date and time slots visible only to those selected few customers.
Attributes | Description | Example |
data-pre-reservation-key | The secret key for the pre-reservation. |
|
1.9 Tracking Marketing Campaign Conversions
If you want to track from which source, medium, or campaign a booking comes, you can do that by parsing your UTM parameters to the booking widget. The data will be then displayed in the Booking Statistics of your account. Here is a list with the currently supported attributes:
Attributes | Description | Example |
data-meta-utmcontent | Use this attribute to parse and save the UTM Content with the booking. This is usually an optional field. If you have multiple links in the same campaign, like two links in the same email, you can fill in this value so you can differentiate between them. |
|
data-meta-utmsource | Use this attribute to parse and save the UTM Source with the booking. This is usually a required parameter and is used to identify which site sent the traffic and made the conversion. |
|
data-meta-utmmedium | Use this attribute to parse and save the UTM Medium with the booking. This is usually used to identify what type of link was used, such as cost per click or email. |
|
data-meta-utmcampaign | Use this attribute to parse and save the UTM Campaign with the booking. This is usually used to identify a specific product promotion or strategic campaign. |
|
data-meta-utmterm | Use this attribute to parse and save the UTM Search Term with the booking. This is usually used to identify the search term in Google Ads. |
|
2. Customisation Options for a Booking Widget iFrame
To see a live example of how a user has customised their iFrame widget, click here
The code snippet for the iFrame should look something like this:
<iframe src="https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&hideCloseButton=true" style="border:0px #ffffff none;" name="myTimifyWidget" scrolling="no" frameborder="0" marginheight="0px" marginwidth="0px" height="800px" width="700px" allowfullscreen></iframe>Copy and paste this code into the HTML of the page where you want the widget to appear on your page. Don't forget to adjust the URL in the "src" attribute according to your account by using the individual accountId for your TIMIFY account. You can also change the height and width of the iFrame by changing the values of the parameters ("height" or "width") in the code above.
With the following parameters you can make further customisations in your widget and adapt the booking process perfectly to your requirements.
A parameter is always appended with a "&" to the existing widget URL. Let's say you would like to hide the close button of the widget when a customer of yours opens the widget link. In this case you need to add the parameter &hideCloseButton=true. This is how your link would look like:
https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&hideCloseButton=true2.1 General and Layout Related Parameters
Parameters | Description | Example |
accountId | Use this to load your account or a specific branch to the widget. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad |
companyExternalId | Use this to load a specific branch from your Branch Manager account to the widget by using a pre-defined external id. | https://book.timify.com/services?enterpriseId=5c79487bed89503cfac758b3&companyExternalId=branch07 |
enterpriseId | Use this to load the location finder as a first step of your widget. Works only if you have a TIMIFY Branch Manager account with more then 1 location. | https://book.timify.com/locations?enterpriseId=5c79487bed89503cfac758b3 |
showLocations | Use this to load specific locations in the widget's location search. | |
hideCloseButton | Use this to hide the close button of the widget. This is a 'boolean'. The value can be only true or false. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&hideCloseButton=true |
fullscreen | Use this to open the widget in full screen mode. This is a 'boolean'. The value can be only true or false. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&fullscreen=true |
overlayColor | Use this to change the background colour behind the widget. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&overlayColor=#F09368 |
overlayOpacity | Use this to change the opacity of the background colour behind the widget. | |
locale | Use this to pre-select a specific language for the booking widget. French: Italian: Spanish: Dutch: Danish: Bulgarian: | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&locale=da-dk |
showCompanyNameInHeader | Use this if you have multiple accounts/locations via the TIMIFY Branch Manager to display the name of the selected location from the Location Finder. This is a boolean. | https://book.timify.com/locations?enterpriseId=5c79487bed89503cfac758b3&showCompanyNameInHeader=true |
horizontalCalendarLayout | Use this to force-display a horizontal week day picker instead of the default Date selectbox. | |
displayWeeklyView | Use this to overwrite the company setting of displaying the weekly view in the booking slots step. It defaults to showing the slots with the day by day layout. | https://book.timify.com/locations?enterpriseId=5c79487bed89503cfac758b3&displayWeeklyView=false |
showLocations | This parameter will show only the Branches specified | |
hideLocations | This parameter will hide the Branches specified |
2.2 Service Related Parameters
Parameters | Description | Example |
showServices | Use this to only show a number of pre-defined services in the first step of the booking widget. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&showServices=5f6cbdb98e434611ef5bbf73 |
showServicesExternalIds | This parameter has the same function as showServices, but using the external Id of the services instead. | |
hideServices | Use this to hide some pre-defined services in the first step of the booking widget. Make sure to use the ID of the respective service - you can find this on the service details page. You may use multiple service IDs - just make sure to separate them with commas. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&hideServices=5f6d9ceeda9f6046487ed20b |
hideServicesExternalIds | This parameter has the same function as hideServices, but using the external Id of the services instead. | |
serviceId | Use this to pre-select a service of your choice and skip the first step of the widget. | |
serviceExternalIds | Use this to pre-select a service of your choice and skip the first step of the widget by using the external ID you've defined for it. | https://book.timify.com/availability?accountId=5f6cbd042e148e11ac2acaad&serviceExternalIds=service03 |
courseId | Use this to pre-select a group service of your choice and skip the first step of the widget by using the ID of the group. |
2.3 Resource Related Parameters
Parameters | Description | Example |
resourceId | Use this to automatically pre-select a resource of your choice. | |
resourceExternalIds | Use this to automatically pre-select a resource of your choice using the external ID you've defined for it. | https://book.timify.com/conflict?accountId=5f6cbd042e148e11ac2acaad&resourceExternalIds=room02 |
filterResources | Use this to filter the resources in the booking widget and only show the selected resources using their TIMIFY IDs. | |
filterResourcesbyExternalId | Use this to filter the resources in the booking widget and only show the selected resources using the external ID you've defined for them. | |
showSelectedResourcesOnly | Use this to display only the pre-selected resource in the resource overview. This is a boolean. | |
showResources | Use this to overwrite the Widget Setting that hides the resources by default. In order for this to work you should first go to Settings > Bookings > Booking Widget and from there activate the switch-box in the section Resource Display. This will lead to hiding by default your resources from all customers that see your widget. When you use this parameter you can overwrite this setting and display the resource select component in some cases to your customers. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&showResources=true |
2.4 Date Related Parameters
Parameters | Description | Example |
date | Use this to automatically pre-fill and display the free slots on a specific date. | https://book.timify.com/availability?accountId=5f6cbd042e148e11ac2acaad&date=2021-08-17 |
dateRange | Use this to filter a pre-defined period for the date selection and display ONLY the available slots within this period. | |
disableOtherDates | Use this to block the user from selecting any other date then the pre-filled one. This is a boolean. |
2.5 Customer Related Parameters
Parameters | Description | Example |
showGuestBookingForm | Use this to display only the guest booking as the authentication method for your bookers. This is a boolean. | https://book.timify.com/customer-fields?accountId=5f6cbd042e148e11ac2acaad&showGuestBookingForm=true |
skipCustomerFieldsSection | Use this to skip showing the guest booking form and directly display the booking confirmation view. | |
hideFilledFields | Use this to hide pre-filled data fields in the booking overview. | |
externalCustomerId | Use this to pre-select an already existing customer in TIMIFY by providing it's external ID. | https://book.timify.com/success?accountId=5f6cbd042e148e11ac2acaad&externalCustomerId=customer-123 |
guestFirstName | Use this to pre-fill the booker's first name automatically in the guest form. | |
guestLastName | Use this to pre-fill the booker's last name automatically in the guest form. | |
guestEmail | Use this to pre-fill the booker's email automatically in the guest form. | |
guestPhone | Use this to pre-fill the booker's phone number automatically in the guest form. | |
guestPhoneCountry | Use this to pre-fill the booker's phone country code automatically in the guest form. | |
customerField[ID] | Use this to pre-fill any custom data field that you've enabled in the booking form. | |
externalCustomerField[ID] | Use this to pre-fill any custom data field with an external ID that you've enabled in the booking form. If you use as a data field type a checkbox the value should be replaced simply with |
2.6 Customisations Related Parameters
Parameters | Description | Example |
customisationId | Use this to overwrite the default company or enterprise widget customisation. For example you can trigger a special widget customisation when a specific service or a resource is pre-filled. | |
templatesCustomisationId | Use this to overwrite the default company or enterprise email template customisation. For example you can trigger a special email template customisation when a specific service is pre-filled or you are triggering the widget from a different medium - let's say you have one customised widget for your website and a different one for your mobile app. |
2.7 Trigger the Rescheduling for a Specific Booking
If you're using the TIMIFY REST API and let's say you want to display all booked appointments that will take place in the future in the customer's section of your app or website so your customers can easily reschedule a particular booking from there. You can trigger a rescheduling process for a specific booking by providing both the eventId and secret of the booking. Usually you would obtain these if you have subscribed to receive a webhook with the scope EVENT-CREATED. The secret for cancellation or rescheduling can be obtained only via webhook and can be found in the metadata.
Parameters | Description | Example |
eventId | This is the id of the booking in TIMIFY. This parameter works only in combination with | |
secret | This is the secret for the booking in TIMIFY. This parameter works only in combination with |
2.8 Display Hidden Booking Slots from a Pre-reservation
In TIMIFY, currently available only via the Booking Links App, you are able to pre-reserve a specific slot or a range of slots within a date range and make those available only to customers who have a special access to your widget that reveals them by parsing a secret key of that pre-reservation. Using the preReservationKey you can parse this secret to the widget and reveal the otherwise hidden slots. Let's say you want to make Thursday the 25th of October 2021 between 15:00 and 17:00 available ONLY to some selected customers of yours. You can create a pre-reservation for that day and time range and you will block it for all your regular customers. Then by parsing the secret key of the pre-reservation in your booking widget you can make this date and time slots visible only to those selected few customers.
Parameters | Description | Example |
preReservationKey | The secret key for the pre-reservation. |
2.9 Tracking Marketing Campaign Conversions
If you want to track from which source, medium or campaign a booking is coming, you can do that by parsing your UTM parameters to the booking widget. The data will be then displayed in the Booking Statistics of your account or if you use our Branch Manager tool in the Statistics Dashboard. Here is a list with the currently supported attributes:
Parameters | Description | Example |
meta[utmcontent] | Use this parameter to parse and save the UTM Content with the booking. This is usually an optional field. If you have multiple links in the same campaign, like two links in the same email, you can fill in this value so you can differentiate between them. | https://book.timify.com/availability?accountId=5f6cbd042e148e11ac2acaad&meta[utmcontent]=HeaderLink |
meta[utmsource] | Use this parameter to parse and save the UTM Source with the booking. This is usually a required parameter and is used to identify which site sent the traffic and made the conversion. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&meta[utmsource]=Google |
meta[utmmedium] | Use this parameter to parse and save the UTM Medium with the booking. This is usually used to identify what type of link was used, such as cost per click or email. | https://book.timify.com/services?accountId=5f6cbd042e148e11ac2acaad&meta[utmmedium]=cpc |
meta[utmcampaign] | Use this parameter to parse and save the UTM Campagin with the booking. This is usually used to identify a specific product promotion or strategic campaign. | |
meta[utmterm] | Use this parameter to parse and save the UTM Search Term with the booking. This is usually used to identify the search term in Google Ads. |
-----------------------------------------------------------------------------------------------------------------------------
3. Customisation options using our REST API
If you want to have an online booking experience that takes on board your corporate branding and specific booking workflows, this is for you. We go deep into your existing IT infrastructure, break down our widget, and re-build it so that it becomes a seamless extension of your API and interface. We take into account the needs and preferences or your clients, so that online booking becomes an integral part of your omni-channel experience.
This option involves accessing our developer platform, and a little bit of training with a dedicated technical specialist. To find out more, please contact our customer support via the chat bubble in the bottom right corner of your browser when you authenticate with your TIMIFY account.