Embedding

Coss.com's pages in your app, or your own UI, without your API key in a browser.

Your API key stays on your server. For a browser, your server creates a session: short-lived, for one thing, with its token in the URL's fragment, which never reaches a server.

In live environments, createForHost needs Scale and Enterprise. On other plans, connect a host's calendars and set their hours through the API. Live pages show "Scheduling by coss.com" below them, except on Scale and Enterprise.

// On your server:
const { :  } = await ...({
  : ,
  // Someone you've signed in: the browser can't book as anyone else.
  : { : "patient_77", : "Sam Lee", : "sam@example.com", : "UTC" },
});
// Pass session?.url to the browser.

To send them to a particular kind of host, add attributes.

Open the url on its own, or embed it with coss/scheduling:

import { mountBooker, mountHostPortal } from "coss/scheduling";

mountBooker({
  url: session.url,
  container: document.getElementById("booking"),
  onEvent: (event) => {
    if (event.type === "booked") showThanks(event.booking_id);
  },
});

mountHostPortal({
  url: hostSession.url,
  container: document.getElementById("availability"),
});

A team lead gets a page of their own, for the hosts you name or everyone matching some attributes:

const { :  } = await ...({
  : { : "cardiology" },
});
// Pass session?.url to the browser, or `mountTeamPortal` from `coss/scheduling`.

It shows who's away and bookings that need cover, and moves them, one at a time or many at once. A filter's asked again on every request, so someone changing teams leaves the page's reach. It sees times, event types and hosts, never attendees' details. It only moves bookings between people it reaches, and a run from it says who each goes to, since "the fairest who's free" could be on another team. read_only: true makes it look but not touch.

The page's origin must be in your settings' allowed_origins:

await ...({
  : ["https://app.example.com"],
  : "Acme Health",
});

Events carry ids and statuses only. The pages tell your app ready, booked, rescheduled, cancelled, availability_saved, calendar_connected and error.

Your own UI

A session's token also works directly from a browser, against the client API at /scheduling/client/*, with Authorization: Bearer <token>. It's how coss.com's own pages work, so nothing they do is out of your reach. Calls are only accepted from your allowed_origins, and a session reaches only its own scope: an attendee sees times, never who else could take them.

A booking made this way says whether the attendee will be emailed about it (attendee_emailed), so your page only promises a confirmation when one is coming. It can choose among the event type's locations by type, but not supply its own link or address, only a phone number where the event type leaves that open.

Booker sessions have GET /session, GET /slots and POST /bookings. Manage sessions have GET /booking, GET /booking/slots, POST /booking/reschedule and POST /booking/cancel. Host sessions have /host/schedules, /host/calendar_connections, /host/calendars/{id}, /host/locations and /host/bookings (with ?when=past, those that started in the last 30 days), and for one of their bookings GET /host/bookings/{id}/slots and POST /host/bookings/{id}/approve, /decline, /cancel, /reschedule and /no_show. A host isn't held to the cutoffs attendees are, and can't move a booking to another host.

Last updated