# Cal.com URL: https://docs.awellhealth.com/docs/marketplace/caldotcom > For the complete documentation index, see [llms.txt](https://docs.awellhealth.com/llms.txt). 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 [#what-to-configure] Set these once, on the extension in Awell Studio. An action fails at run time if a required setting is missing. | Setting | Required | Notes | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | API Key | Yes | Enter an API key so Awell can communicate with Cal.com. Stored as a secret. | | Custom Domain | No | Custom domain for your Cal.com deployment. Defaults to [https://cal.com](https://cal.com) but can be overridden for enterprise Cal.com accounts with custom domains (e.g., [https://myorg.cal.com](https://myorg.cal.com)). | ## Actions [#actions] Cal.com adds these 6 actions to a care flow. Add one to a step, then fill in its inputs. ### Book appointment [#book-appointment] Enable a stakeholder to book an appointment via Cal.com. | Input | Type | Required | Description | | -------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | Cal Link | `string` | Yes | The Cal Link that you want to embed e.g. "john". Just give the username. No need to give the full URL [https://cal.com/john](https://cal.com/john). | Returns: | Data point | Type | | ----------- | -------- | | `bookingId` | `string` | ### Create booking (v1) [#create-booking-v1] Creates a new booking via the Cal.com API This action can be previewed in Studio before you publish. | Input | Type | Required | Description | | ----------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Event Type ID | `numeric` | Yes | ID of the event type to book | | Start | `string` | Yes | 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 | `string` | No | 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. | | Responses | `json` | Yes | Object containing email, name, location | | Metadata | `json` | No | Any metadata associated with the booking | | Timezone | `string` | Yes | Timezone of the Attendee | | Language | `string` | Yes | Language of the Attendee | | Title | `string` | No | Title of Booking event | | Recurring Event Type ID | `numeric` | No | Recurring event ID if the event is recurring | | Description | `string` | No | Description of the meeting | | Status | `string` | No | Status of the meeting to be set. Possible values: "ACCEPTED", "PENDING", "CANCELLED", "REJECTED". | Returns: | Data point | Type | | ----------- | -------- | | `bookingId` | `string` | 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 * ```json "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) [#delete-booking-v1] Deletes Booking in Cal.com This action can be previewed in Studio before you publish. | Input | Type | Required | Description | | ---------------------- | --------- | -------- | ------------------------------------------ | | Booking ID | `string` | Yes | The ID of a Booking in Cal.com | | All remaining bookings | `boolean` | No | Delete all remaining bookings | | Reason | `text` | No | The reason for cancellation of the booking | ### Get booking (v1) [#get-booking-v1] Get Booking and save data in Data Points This action can be previewed in Studio before you publish. | Input | Type | Required | Description | | ---------- | -------- | -------- | ----------- | | Booking ID | `string` | Yes | — | Returns: | Data point | Type | | ----------------------- | -------- | | `cancelUrl` | `string` | | `description` | `string` | | `endTime` | `date` | | `eventTypeId` | `string` | | `firstAttendeeEmail` | `string` | | `firstAttendeeName` | `string` | | `firstAttendeeTimezone` | `string` | | `location` | `string` | | `rescheduleUrl` | `string` | | `startTime` | `date` | | `status` | `string` | | `title` | `string` | | `userEmail` | `string` | | `videoCallUrl` | `string` | ### Get booking (v2) [#get-booking-v2] Retrieve booking details from Cal.com using the v2 api This action can be previewed in Studio before you publish. | Input | Type | Required | Description | | ----------- | -------- | -------- | ----------- | | Booking UID | `string` | Yes | — | Returns: | Data point | Type | | ------------------------ | -------- | | `bookingData` | `json` | | `bookingFieldsResponses` | `json` | | `cancelUrl` | `string` | | `description` | `string` | | `endTime` | `date` | | `eventTypeId` | `string` | | `firstAttendeeEmail` | `string` | | `firstAttendeeName` | `string` | | `firstAttendeeTimezone` | `string` | | `hostEmail` | `string` | | `location` | `string` | | `metadata` | `json` | | `rescheduleUrl` | `string` | | `startTime` | `date` | | `status` | `string` | | `title` | `string` | ### Update booking (v1) [#update-booking-v1] Updates Booking This action can be previewed in Studio before you publish. | Input | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Booking ID | `string` | Yes | The ID of a Booking in Cal.com | | Title | `string` | No | Title of Booking event | | Description | `string` | No | Description of the meeting | | Start | `string` | No | 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 | `string` | No | 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. | | Status | `string` | No | Status of the meeting to be set. Possible values: "ACCEPTED", "PENDING", "CANCELLED", "REJECTED". | Returns: | Data point | Type | | ------------ | -------- | | `bookingId` | `string` | | `bookingUid` | `string` | 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 [#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` [#bookingcancelled] Payload: | Data point | Type | | ------------ | -------- | | `bookingId` | `string` | | `bookingUid` | `string` | ### `bookingCreated` [#bookingcreated] Payload: | Data point | Type | | ------------ | -------- | | `bookingId` | `string` | | `bookingUid` | `string` | ### `bookingRescheduled` [#bookingrescheduled] Payload: | Data point | Type | | ------------ | -------- | | `bookingId` | `string` | | `bookingUid` | `string` | ## Setup and notes [#setup-and-notes] [Cal.com](https://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 [#calcom-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 [#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 [#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. | App | Supported | | ----------------------------- | --------- | | Awell Hosted Pages | Yes | | Your app (custom integration) | Yes | | Awell Care | No | | Awell MyCare | No | ##### Data points [#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 [#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 [#delete-boooking] Deletes a Booking with a given ID. ### Pricing [#pricing] This extension is free but keep in mind that you might need a paid plan for Cal.com depending on your needs. ### Limitations [#limitations] #### Rescheduling [#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 [#example] An appointment has been booked with Cal.com and we have the below booking resource: ```json { ..., "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. ```json { ..., "bookingId": "1", "date": "Jan 1, 2023" } ``` ### Webhooks [#webhooks-1] 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 [#changelog] ### September 15, 2023 [#september-15-2023] * add createBooking action * add first attendee name and timezone to getBooking data points ### September 4, 2023 [#september-4-2023] * add updateBooking and deleteBooking actions * update and refactor structure of getBooking and bookAppointment actions ### July 4, 2023 [#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 [#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 [#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](mailto:support@awellhealth.com).