Cal.com

Enable scheduling in your care flows with Cal.com.

Category: Scheduling. Adds 6 actions and 3 webhooks to a care flow. Built by HTD.

What to configure

Set these once, on the extension in Awell Studio. An action fails at run time if a required setting is missing.

Actions

Cal.com adds these 6 actions to a care flow. Add one to a step, then fill in its inputs.

Book appointment

Enable a stakeholder to book an appointment via Cal.com.

Returns:

Create booking (v1)

Creates a new booking via the Cal.com API

This action can be previewed in Studio before you publish.

Returns:

Creates a booking and saves new bookingId as Data Points. Available fields:

• Event Type ID - ID of the event type to book
• Responses - Object containing email, name, location

  •     "responses": {
            "name": "John Doe",
            "email": "john.doe@example.com",
            "location": "Calcom HQ"
        },

• Metadata - Any metadata associated with the booking
• Timezone - Timezone of the Attendee
• Language - Language of the Attendee
• Recurring Event ID - Recurring Event ID if the event is recurring
• Title - Title of Booking event
• Description - Description of the meeting
• Status - Status of the meeting to be set. Possible values: "ACCEPTED", "PENDING", "CANCELLED", "REJECTED".
• Start - Start time of the Event in ISO 8601 format, e.g. 2023-05-24T13:00:00.000Z. Please note that start/end time must be within user's availability hours.
• End - End time of the Event in ISO 8601 format, e.g. 2023-05-24T13:00:00.000Z. Please note that start/end time must be within user's availability hours.

Delete booking (v1)

Deletes Booking in Cal.com

This action can be previewed in Studio before you publish.

Get booking (v1)

Get Booking and save data in Data Points

This action can be previewed in Studio before you publish.

Returns:

Get booking (v2)

Retrieve booking details from Cal.com using the v2 api

This action can be previewed in Studio before you publish.

Returns:

Update booking (v1)

Updates Booking

This action can be previewed in Studio before you publish.

Returns:

Updates a booking and saves new bookingId and bookingUid as Data Points. Values possible to update:

• Title - Title of Booking event
• Description - Description of the meeting
• Status - Status of the meeting to be set. Possible values: "ACCEPTED", "PENDING", "CANCELLED", "REJECTED".
• Start - Start time of the Event in ISO 8601 format, e.g. 2023-05-24T13:00:00.000Z. Please note that start/end time must be within user's availability hours.
• End - End time of the Event in ISO 8601 format, e.g. 2023-05-24T13:00:00.000Z. Please note that start/end time must be within user's availability hours.

Webhooks

Cal.com can send these 3 events into Awell, where each one can start a care flow or move a patient along. Point the webhook at the URL Studio shows you when you enable it.

bookingCancelled

Payload:

bookingCreated

Payload:

bookingRescheduled

Payload:

Setup and notes

Cal.com is a modern and **open source scheduling platform. With HIPAA, GDPR and SOC2 compliance, you can ensure that data is well-protected and that makes Cal.com a great fit for healthcare use cases.

Cal.com x Awell

This extension allows you to let a stakeholder (eg: a patient) book an appointment as part of a care flow and to retrieve the booking details of an appointment.

Extension settings

In order to set up this extension, you will need to provide a Cal.com API key. You can obtain an API key via the Cal.com portal (Settings > Developer > API keys).

Book appointment action

You can add this action to your care flow to enable a stakeholder (eg: a patient) to book an appointment in a predefined calendar. This is a stakeholder-actionable action which means it requires an actual user to book an appointment. Also note that this is a blocking action and that the care flow will not progress - unless there are parallel tracks or transitions - until the action/activity is completed (i.e. an appointment was booked).

The actual booking of the appointment can happen in two ways:

1. With Awell Hosted Pages: when the "Book appointment" action is activated, we serve the booking widget to the stakeholder so they can book an appointment directly from within Awell Hosted Pages.
2. If you are not leveraging Awell Hosted Pages but have built a custom integration then we expose you all the details via our API so you can either create a Cal.com booking widget yourself or redirect the user to the Cal.com platform. Additionally, we expose a mutation that allows you to complete the activity and pass in the required data.

Below you can find an overview of all Awell Apps and whether they support rendering of the booking widget.

Data points

Adding this action to your care flow will expose a new data point you can use in your care flow, the bookingId. When the care flow is orchestrated and the book appointment activity is completed, the id of the actual booking will be ingested as the value of that bookingId data point.

Get booking action

This action allows you to fetch the details of a booking based on the provided bookingId. This action will make the following data points available for you to use in your care flow:

1. Event type ID
2. Title
3. Description
4. Start time
5. End time
6. Status
7. Cancel URL
8. Reschedule URL
9. Video call URL (if available)
10. First Attendee's name
11. First Attendee's timezone
12. First Attendee's email
13. Organizer's email

Delete Boooking

Deletes a Booking with a given ID.

Pricing

This extension is free but keep in mind that you might need a paid plan for Cal.com depending on your needs.

Limitations

Rescheduling

When a previously made booking is rescheduled, there is no way yet to get the new/updated booking details into the care flow or have the care flow react on the updated booking.

Also note that when a booking is rescheduled, Cal.com doesn't update the original booking resource but creates a new one instead. As far as we know, there is no reference from the old booking to the new (rescheduled) booking.

Example

An appointment has been booked with Cal.com and we have the below booking resource:

{
    ...,
    "bookingId": "1",
    "date": "Jan 1, 2023"
}

However, the patient reschedules the booking to Jan 10, 2023. When querying Cal.com's API (GET v1/bookings/{bookingId}), it will still return the old booking date instead of the new/rescheduled date.

{
    ...,
    "bookingId": "1",
    "date": "Jan 1, 2023"
}

Webhooks

Webhooks offer a great way to automate the flow with Awell when invitees schedule, cancel, or reschedule events, or when the meeting ends.

Important notes**:

1. An Awell webhook endpoint can only listen to one event type. So make sure that when you create a webhook in Cal.com, the subscriber URL and the event trigger match the Awell webhook endpoint. This also means there can only be one event type per subscriber URL.
2. Using a secret to verify the authenticity of the received payload is not yet supported.
3. Custom payload templates are not supported, please use the default ones.

Changelog

September 15, 2023

• add createBooking action
• add first attendee name and timezone to getBooking data points

September 4, 2023

• add updateBooking and deleteBooking actions
• update and refactor structure of getBooking and bookAppointment actions

July 4, 2023

• Get booking action: add validation that bookingId and apiKey are not empty
• Get booking action: add validation of response data to make sure we have data points

April 27, 2023

• Get booking action: startTime and endTime data points are now of value type date instead of string.

Where this page comes from

The settings, actions, inputs, outputs and webhooks above are generated from the extension's own code, at @awell-health/awell-extensions v2.1.159. They match what the platform actually does rather than a description of it.

Field-level detail also appears in Awell Studio when you configure the action. Something wrong or missing? Email support@awellhealth.com.