Installing the Netcoder booking widget on your website

The Netcoder booking widget lets the visitors of any website book a meeting with your team, with a single snippet of HTML. They pick a meeting type, a day and a time, give their name and email, and are booked right away: the meeting goes into the calendar of the person they are given, and they receive a confirmation email with an invite for their own calendar.

1. Installation

Add an empty element where the widget should appear, and the following script tag just before the closing </body> tag of the page. Replace the placeholder values with the ones for your account (see section 5).

<div id="nc-booking"></div>
<script src="https://cdn.netcoder.com/booking.v1.js"
        data-backend-url="wss://relay.netcoder.ca/booking"
        data-client-key="YOUR-CLIENT-GUID"
        data-calendar-key="YOUR-CALENDAR-GUID"
        data-container="#nc-booking"></script>

That is all that is required. The meeting types, the calendar, the times, the booking form, the styling and the confirmation are provided by the script, and nothing else needs to be installed on your server.

The simplest way to get it is from the Netcoder app: click Calendar in the menu, open the calendar menu, the button with three dots (⋮) at the top of the calendar, and choose Integration parameters. Pick a calendar or a grouped calendar, and copy the code with your keys already filled in.

Before anyone can book, set up in the app the meeting types to offer, who can take each of them, and the availability of those people (section 2).

2. Who is booked

A guest picks a meeting type and a time. Who the meeting is booked with is named by the code in one of two ways, never both.

A calendar

With data-calendar-key, the widget books one person, the one whose calendar it is. The widget shows the name of that calendar: its Calendar name, set in Availability, or else the name of the person.

A grouped calendar

With data-grouped-calendar-key, the widget books the people of a grouped calendar: the one free at the time chosen, in turn. To create one in the app, choose Grouped calendars in the calendar menu, and give it a name guests see, such as Sales, a language, and the people in it. The widget then shows the name of the grouped calendar and speaks its language.

        data-grouped-calendar-key="GROUPED-CALENDAR-GUID"

The code gives one or the other. With both, or neither, the widget shows “This calendar cannot be booked online.”

What the guest is offered

• Meeting types — the meeting types at least one of these people can take, as set by Who can take it on each meeting type in the app. Disabled types are not shown.
• Times — the times when at least one of them who can take the type is free, according to their availability hours, the bookings they already have, and the busy times of their connected Google or Microsoft calendar. The notice, buffers and days ahead of the meeting type apply.
• The person — the booking goes to one of those free at the time chosen, in turn: the one booked the longest ago comes first. Two guests booking the same time at once get two different people, as long as two are free.

3. What the visitor sees

The widget is drawn inside the element named by data-container; without it, just before the script tag. It takes the full width of that element; about 360 to 560 px suits it best.

• Meeting type — the meeting types, with their duration, where they happen (an address, at the visitor's address, a phone call or a video call) and their description. This step is skipped when there is only one.
• Day — a month calendar where the days with free times stand out, with arrows to the previous and next months. A month without any free time moves on to the next one by itself.
• Time — the free times of the day chosen, in the visitor's own time zone, named under the times.
• Details — the name and the email, both required, a phone number and notes. The phone number is required for a phone call, and the visitor's address is asked for a meeting at its address.
• Confirmation — the meeting booked, where it happens (an address opens in Google Maps, a video call gives its link), the address the confirmation was sent to, a Reschedule or cancel link, and a button to book another time.

4. Configuration parameters

Set on the script tag.

Attribute	Required	Description	Default
data-backend-url	Yes	Address of the Netcoder relay: wss://relay.netcoder.ca/booking
data-client-key	Yes	Your client key
data-calendar-key	One of the two	The calendar of one person
data-grouped-calendar-key	One of the two	A grouped calendar, its people in turn
data-language		en or fr	That of the grouped calendar
data-title		Title of the widget	Book a meeting with {{calendar-name}}
data-title-en, data-title-fr		Title in one language, before data-title
data-container		CSS selector of the element to draw the widget in	Before the script
data-accent-color		Main colour	#D97955
data-accent-text-color		Colour of the text on the main colour	#FFFFFF

5. Getting your keys

The keys are GUIDs, for example 3f2a7b10-9c4d-4e21-8a6f-1b2c3d4e5f60. They are found in the Netcoder app:

• Client key — your account. Shown in Integration parameters.
• Grouped calendar key — a grouped calendar. Shown in Integration parameters when A grouped calendar is chosen, and copied with Copy the key in the list of grouped calendars.
• Calendar key — the calendar of one person. Shown in Integration parameters when A calendar is chosen.

If a key is missing or malformed, or if both keys or neither are given, the widget shows “This calendar cannot be booked online.” and the server is not contacted. The same message is shown when a key is valid but not recognized, belongs to another account, or names a deleted grouped calendar: check the values in Integration parameters.

6. Language and title

The data-language attribute sets the language of the dates and times, and of the meeting types: their names, descriptions and locations are shown in French when their French is filled in the app, and in English otherwise.

• en — English.
• fr — French.

Without data-language, the widget takes the language of its grouped calendar, so the code of a French grouped calendar needs no language of its own; with neither, the language of your account. On a bilingual website, set the matching language on each page. The buttons and messages of the widget follow data-language, in English or in French.

The title

The title is, in this order: data-title- followed by the language, such as data-title-fr for French, then data-title, then the default, “Book a meeting with {{calendar-name}}”. In a title, {{calendar-name}} is replaced by the name of the grouped calendar, or of the calendar.

        data-title-en="Book a meeting with {{calendar-name}}"
        data-title-fr="Prendre rendez-vous avec {{calendar-name}}"

7. Styling with CSS

For more than the title and the two colours, style the widget from your own stylesheet. Its styles load after yours: start your selectors with body to win, rather than using !important.

body .ncb-title { font-size: 22px; }

Selector	What it is
.ncb	The widget
.ncb-title	The title
.ncb-type	A meeting type
.ncb-day	A day; ncb-open with free times, ncb-selected when chosen
.ncb-time	A time
.ncb-field, .ncb-primary	The fields of the form and the Book button

White text on the default #D97955 is below the WCAG AA contrast of 4.5:1: darken the accent, or use a dark text colour such as #1B1B1B.

8. How it works

The widget holds a secure WebSocket to the Netcoder relay. Each thing it asks for — what can be booked, the free times of a month, a booking — is handled on Netcoder's servers, and the answer is pushed back to the page.

• Times checked again — when the visitor books, the time is checked again with the people who can take it. If it was taken in the meantime, the visitor is told, and brought back to the times still free, with what was typed kept.
• Confirmation — the guest receives a confirmation email with an invite to add the meeting to its calendar, where it happens, and a link to reschedule or cancel. The person booked receives an email too, and the meeting goes into its connected calendar, with the address or the video link.
• Reminders — the guest is reminded before the meeting, by email, and by SMS when the meeting type says so and the guest gave a phone number.
• Rescheduling — a meeting moved by the guest stays with the same person.
• Connection — if the connection drops, the widget reconnects by itself; a request left without an answer is reported, and can be tried again.

9. Testing and troubleshooting

• The widget does not appear — check that the script URL is reachable, that the code is placed before </body>, and that data-container matches an element of the page. After changing the code, hard-refresh the page (Ctrl+Shift+R).
• “This calendar cannot be booked online.” — a key is missing, malformed, unknown, of another account, or names a deleted grouped calendar; or both keys, or neither, are given. See section 5.
• “There is nothing to book at the moment.” — none of the people booked can take an enabled meeting type. Check Who can take it, and that the type is enabled.
• “No time is available this month.” — check the availability hours of the people, the minimum notice and the days ahead of the meeting type, and their connected calendars, whose busy times are left out.
• “The booking service cannot be reached.” — the relay could not be reached or did not answer in time. Check the backend URL, and that it starts with wss:// on an https:// page.
• No confirmation email — check the visitor's spam folder, then ask Netcoder to check the email settings of your account.
• Any domain works — the widget can be embedded on any website; nothing needs to be configured on your server.

10. Complete example

A widget booking a grouped calendar, with every option set:

<div id="nc-booking"></div>
<script src="https://cdn.netcoder.com/booking.v1.js"
        data-backend-url="wss://relay.netcoder.ca/booking"
        data-client-key="3f2a7b10-9c4d-4e21-8a6f-1b2c3d4e5f60"
        data-grouped-calendar-key="a1b2c3d4-e5f6-4788-9a0b-1c2d3e4f5a6b"
        data-language="en"
        data-title-en="Book a meeting with {{calendar-name}}"
        data-container="#nc-booking"
        data-accent-color="#D97955"
        data-accent-text-color="#FFFFFF"></script>