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, please 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 v1 supports the following scenarios:

  • returning a single time selected by your user to your application,
  • scheduling a meeting at the time selected by your user directly through FreeBusy

So whether you want the perfect time, or schedule a meeting while you're at it, FreeBusy has you covered. And remember - your user always sees the combined availability view for all participants, making it 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/v1"></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" or "custom")
  • 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.

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.
  • scenario
    (string: "meet" or "pick-a-time")
  • display
    (string: "popup" or "modal")
  • closeOnSchedule
    (boolean; defaults to true)

Note that the "meet" scenario allows your user to schedule a meeting through FreeBusy directly. Use the "pick-a-time" scenario if you want FreeBusy to return the selected time to your application without scheduling the meeting.

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.
  • calendarOwner
    (string: email address or group slug)
  • participants
    (Participant array: [{
    email: (string: email address),
     name: (string: participant name),
     role: ("proposer" or "requiredAttendee")
     timeZone: (string: IANA time zone)
    }])
  • durationInMin
    (int; valid values: 30,60,90,120; default 30)
  • subject
    (string; not editable by proposer if set)
  • location
    (string; not editable by proposer if set)
  • notes
    (string: notes by proposer; not editable by proposer if set)
  • calendarOwnerNotes
    (string: notes by the calendarOwner; 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({
    scenario: 'pick-a-time'
  },
  {
    calendarOwner: '[email protected]',
    durationInMin: 60,
    participants: [{
      email: '[email protected]',
      name: "My Colleague",
      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 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)
}

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 -