Developers > Pick-a-Time Reference

Pick-a-Time adds availability awareness to your application for easy meeting coordination, without having to federate calendar data on your server. Should you require further assistance after reading this reference documentation, contact us by email or by using the in-app help button.

FreeBusy Pick-a-Time widget is a core offering for 3rd party developers to directly integrate availability awareness into their applications. The Pick-a-Time API supports the following scenarios:

  • scheduling a meeting at the time selected by your user directly through FreeBusy

FreeBusy has you covered. Your customers always see the combined availability view for all participants, so it's really easy to find a time that works!

Including Pick-a-Time

  1. Add this script tag to the <head> element of every page where Pick-a-Time should appear:

    <script type="text/javascript" src="https://js.freebusy.io/pick-a-time/v2"></script>

    Note: While you may add the script tag anywhere before the button in Step 2 below is declared on the page, we strongly recommend that you do so in the <head> tag. This will allow your application to reference Pick-a-Time API methods wherever, without having to worry if the Pick-a-Time widget has already been loaded.

  2. Decide how you want to display the Pick-a-Time button:

    1. Native button designed and injected by FreeBusy

      Use this option when you can freely edit the HTML template and don't need to change the button style.

      Injected button will look like this:
      native-button

      Add the Pick-a-Time button where you want it to show on the page:
      <div id="freebusy-pickatime-button"></div>

      Note: FreeBusy will automatically inject the native Pick-a-Time button wherever you place the above div element.

    2. Custom button designed by yourself

      Use this option when you can't add custom HTML to your page, have an existing element you want to attach Pick-a-Time to, or need to change the button style.

      Note down element ID or unique class name.

  3. Initialize the Pick-a-Time button by calling the freebusy.pickatime.init method.
    For details on how to call this method, see the Pick-a-Time API Reference below.

  4. Call the below methods, and subscribe to events, anywhere on the page.
    We recommend subscribing to all the events referenced below for a great UX.

Pick-a-Time API Reference

Public methods

freebusy.pickatime.init(JSON object: config)

Description Provides initialization configuration to the Pick-a-Time widget. You must call this method when your page loads. Config, which is a JSON object specified below, represents the configuration for the Pick-a-Time widget.
Parameters config
JSON object with the following accepted properties. Required in bold.
  • buttonType
    (string: "native", "custom" or "none")
  • buttonId
    (string: ID of element to attach the widget to; omit "#")
  • buttonClass
    (string: CSS class of element to attach the widget to; omit ".")

Note that buttonType denotes how you want to display the Pick-a-Time button on your page. If you select custom, you must provide either buttonId or buttonClass of an existing element on your page that the Pick-a-Time widget should get attached to. When this element is then clicked by your user, FreeBusy will open the Pick-a-Time widget as if a native button were used.

If you wish to inject the native FreeBusy Pick-a-Time button, only set the buttonType property. Do not supply the buttonId and buttonClass properties.

If you wish to start Pick-a-Time programmatically (e.g. in response to XHR callback), set the buttonType property to none. Do not supply the buttonId and buttonClass properties. To start Pick-a-Time programmatically, call freebusy.pickatime.open at the appropriate time.

Usage To inject the native Pick-a-Time button, use:
freebusy.pickatime.init({
  buttonType: "native"
});

To attach Pick-a-Time to an existing element, use:
freebusy.pickatime.init({
  buttonType: "custom",
  buttonId: "{YourCustomButtonId}"
});
or:
freebusy.pickatime.init({
  buttonType: "custom",
  buttonClass: "{YourUniqueButtonClassName}"
});
Note -

freebusy.pickatime.open(JSON object: availabilityRequest, JSON object: availabilityQuery)

Description Discloses the nature of the scheduling scenario to FreeBusy. You must call this method when or before the Pick-a-Time button is clicked by your user. AvailabilityRequest and AvailabilityQuery, which are JSON objects specified below, represent the inputs to the Pick-a-Time widget.
Parameters availabilityRequest
JSON object with the following accepted properties. Required in bold.
  • link
    (string: link to your event type)
  • display
    (string: "popup" or "modal")
  • language
    (string; defaults to "en")
  • branding
    (string; "visible" or "hidden"; defaults to "visible")
  • closeOnSchedule
    (boolean; defaults to true)

Decide how you want the Pick-a-Time widget to be shown using the display parameter. Choosing popup will open Pick-a-Time in a separate popup window. Selecting modal displays Pick-a-Time embedded directly in your application, using a modal with a backdrop.

In some scenarios, you may not be able to act upon scheduling of a meeting in your application directly. You can prevent the FreeBusy Pick-a-Time widget from closing when a meeting is scheduled, and let us display the meeting confirmation to your user in the widget directly. To do so, set closeOnSchedule to false. Note that this parameter is only observed for the "meet" scenario.

availabilityQuery
JSON object with the following accepted properties. Required in bold.
  • participants
    (Participant array: [{
    email: (string: email address),
     name: (string: participant name),
     role: ("proposer" or "requiredAttendee")
     timeZone: (string: IANA time zone)
    }])
  • agenda
    (string: set agenda programatically; not editable by proposer)
  • management
    ({
     canProposeNewTime: (boolean; defaults to true)
    })
Note -

freebusy.pickatime.enable()

Description Enables the Pick-a-Time button.
Parameters -
Note Pick-a-Time button is enabled by default.

freebusy.pickatime.disable()

Description Prevents the Pick-a-Time button from being clicked. In this state, your users won’t be able to interact with the FreeBusy Pick-a-Time widget.
Parameters -
Note -

Public events

freebusy.pickatime.onclick(callback)

Description Fired when the Pick-a-Time button is clicked. Callback allows setting of input data via freebusy.pickatime.open(request, query)
Usage
freebusy.pickatime.onclick(function() {
  freebusy.pickatime.open({
    link: 'https://freebusy.io/freebusy.io/pick-a-time-demo',
    scenario: 'pick-a-time'
  },
  {
    participants: [{
      email: '[email protected]',
      name: "John Doe",
      role: "proposer",
      timeZone: "America/Los_Angeles"
    }] 
  });
});

3rd party developers may instead choose to reference a variable from their own, or global, namespace:
freebusy.pickatime.onclick(function() {
  freebusy.pickatime.open(
    MyAppNamespace.availabilityRequest,
    MyAppNamespace.availabilityQuery
  );
});

3rd party developers may also decide to set the availability request and query inside their own functions and pass their references only:
freebusy.pickatime.onclick(function() {
  var request = GetRequest();
  var query = GetQuery();
  freebusy.pickatime.open(request, query);

  feedbackToUser();
});
Note While you may set the availability request and query at any time, we recommend doing so in the callback of freebusy.pickatime.onclick() as detailed above. This ensures that FreeBusy will receive up-to-date data when your user clicks the Pick-a-Time button.

freebusy.pickatime.onselect(callback)

Description Fired when a user selects a time in the Pick-a-Time widget.
Usage
freebusy.pickatime.onselect(function(response, proposal) {
  if (response.statusCode === 200) {
    var meetingDate = new Date(proposal.startTime);
    var clientTz = response.organizer.timeZone;
  }
  else {
    handleProposalFailure(response, proposal);
  }
});

3rd party developers may instead choose to pass a reference to their own function:
freebusy.pickatime.onselect(MyAppNamespace.setFcn);

where, for example, MyAppNamespace.setFcn is defined as:
MyAppNamespace.setFcn = function (response, proposal) {
  if (response.statusCode === 200) {
    var dt = new Date(proposal.startTime);
    setUI(dt);
  }
  else {
    handleProposalFailure(response, proposal);
  }
};
Note Callback function must define two parameters, response and proposal, whose properties are:
var response = {
  statusCode: (int; success returns 200),
  id: (string: meetingId)
}
and
var proposal = {
  organizer: {
    email: (string: email address),
    name: (string: organizer name),
    timeZone: (string: IANA time zone)
  },
  participants: [{
    email: (string: email address),
    name: (string: participant name),
    timeZone: (string: IANA time zone)
  }],
  startTime: (string: ISO 8601 date),
  durationInMin: (int),
  subject: (string),
  location: (string),
  id: (string: meetingId)
}

freebusy.pickatime.onopen(callback)

Description Fired when the Pick-a-Time widget popup opens.
Usage
freebusy.pickatime.onopen(function() {
  console.log("opened");
});

3rd party developers may also pass a reference to their own function.
Note -

freebusy.pickatime.onclose(callback)

Description Fired when the Pick-a-Time widget popup is closed.
Usage
freebusy.pickatime.onclose(function(response, proposal) {
  if (response.statusCode === 199) {
    console.log("Pick-a-Time closed by user");
  }
  else {
    console.log("Pick-a-Time closed itself");
  }
});

3rd party developers may also pass a reference to their own function.
Note Callback function must define two parameters, response and proposal, whose properties are:
var response = {
  statusCode: (int; closed by user returns 199),
  id: (string: meetingId if scheduled through "meet" scenario)
}
and
var proposal = {
  organizer: {
    email: (string: email address),
    name: (string: organizer name),
    timeZone: (string: IANA time zone)
  },
  participants: [{
    email: (string: email address),
    name: (string: participant name),
    timeZone: (string: IANA time zone)
  }],
  startTime: (string: ISO 8601 date),
  durationInMin: (int),
  subject: (string),
  location: (string),
  id: (string: meetingId if scheduled through "meet" scenario)
}

Proposal is null if Pick-a-Time was closed by the user.

freebusy.pickatime.onerror(callback)

Description Fired if Pick-a-Time throws an error.
Usage
freebusy.pickatime.onerror(function(error) {
  console.log("error " + error);
});

3rd party developers may also pass a reference to their own function.
Note -