From 7dfbb42cedd655267fe2fd912f34df6545579fe4 Mon Sep 17 00:00:00 2001 From: Lauris Skraucis Date: Thu, 24 Apr 2025 14:47:09 +0200 Subject: [PATCH] docs: global platform event types and custom booking flows (#20940) * docs: global event types * docs: custom booking flow --- docs/mint.json | 4 +- docs/platform/guides/custom-booking-flow.mdx | 35 ++++ docs/platform/guides/global-event-types.mdx | 161 +++++++++++++++++++ 3 files changed, 199 insertions(+), 1 deletion(-) create mode 100644 docs/platform/guides/custom-booking-flow.mdx create mode 100644 docs/platform/guides/global-event-types.mdx diff --git a/docs/mint.json b/docs/mint.json index 4491968150..81f3ff2c31 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -220,7 +220,9 @@ "platform/guides/replacing-toasts", "platform/guides/booking-fields", "platform/guides/booking-redirects", - "platform/guides/teams-setup" + "platform/guides/teams-setup", + "platform/guides/global-event-types", + "platform/guides/custom-booking-flow" ] }, "platform/faq" diff --git a/docs/platform/guides/custom-booking-flow.mdx b/docs/platform/guides/custom-booking-flow.mdx new file mode 100644 index 0000000000..a5dac4fe77 --- /dev/null +++ b/docs/platform/guides/custom-booking-flow.mdx @@ -0,0 +1,35 @@ +--- +title: Custom booking flow +description: Learn how to intercept a booking to introduce your custom flow and then submit the booking. +--- + +If you want to have a custom payment flow or any other custom action before the booking happens, you can intercept the booking +once the user clicks book in the [Booker atom](https://cal.com/docs/platform/atoms/booker), run whatever custom code you need and then finally +submit the booking with the intercepted booking data. + +In your component that renders the Booker atom create a `interceptBooking` function that will be passed to the Booker atom `handleCreateBooking` hook. See [Booker atom](https://cal.com/docs/platform/atoms/booker) docs on how to use it - in this tutorial +we focus on the `handleCreateBooking` hook. + +``` +import { Booker, UseCreateBookingInput } from "@calcom/atoms"; + + +export function BookingPage(props: { calUsername: string; calEmail: string }) { + ... + const interceptBooking = useCallback((data: UseCreateBookingInput) => { + console.log(data); + }, []); + + return ( + + ); +} +``` + +1. When user clicks "Book" in the Booker atom the booking will not happen. Instead, the `interceptBooking` function will be called and will receive all the booking data. +2. Then, you can hide the Booker component and instead render another component, show a modal, redirect to a new page or whatever you want to do. +3. After your custom action is finished, extract the necessary information from the booking data passed to `interceptBooking` and make a POST request to +[create booking](https://cal.com/docs/api-reference/v2/bookings/create-a-booking) endpoint to actually create the booking. diff --git a/docs/platform/guides/global-event-types.mdx b/docs/platform/guides/global-event-types.mdx new file mode 100644 index 0000000000..521afceec8 --- /dev/null +++ b/docs/platform/guides/global-event-types.mdx @@ -0,0 +1,161 @@ +--- +title: Global event types +description: Event types that every managed user or a subset of managed users will have automatically +--- + +If you want that all of your managed users or a subset of managed users have the same event type setup automatically then follow along. + +## Prerequisites + +1. You need to have an oAuth client setup, since we'll need the client id and client secret from the oauth client to be included in the api requests. Here is the link for the [oauth client setup guide](https://cal.com/docs/platform/quickstart) +2. You need to have an ESSENTIALS plan or higher + +## Steps + +Overview: +1. Create a team. +2. Create managed team event type with `assignAllTeamMembers: true` - it is an event type that you can define once and that will be used as a template to create event types for managed users. We call it the parent +managed event type and the event types created for managed users based on it are called children managed event types. +3. Create managed users. +4. For each managed user you want to have this event type, create a membership within the team. + +Then the managed user will have the event type created. Once you have steps 1 and 2 setup then you simply need to add the managed user to the team +and the user will have the event type created. If you then update the parent managed event type then it will automatically update all of the children managed event types. + + + + + Create a team by sending a POST request to the [create a team](https://cal.com/docs/api-reference/v2/orgs-teams/create-a-team) endpoint. Example request body: + +``` +{ + "name": "coffee fans", + "slug": "coffee-fans" +} +``` + +You will need to note down the "id" of the created team from the response: +``` +{ + "status": "success", + "data": { + ... + "id": 1041, + ... + } +} +``` + + + + +Now we will create the managed team event type. Make a POST request to the [create an organization team event type](https://cal.com/docs/api-reference/v2/orgs-teams-event-types/create-an-event-type) endpoint. Example request body: +``` +{ + "lengthInMinutes": 60, + "title": "coffee tasting", + "slug": "coffee-tasting", + "schedulingType": "managed", + "assignAllTeamMembers": true +} +``` + +Note that `"schedulingType"` has to be set to `"managed"` and `"assignAllTeamMembers"` has to be set to `true`. `"assignAllTeamMembers"` being `true` means that once a managed user has membership in the team this event type will be automatically created for the managed user. + +You will need to note down the "id" of the created event type from the response: +``` +{ + "status": "success", + "data": [ + { + "id": 3672, + "lengthInMinutes": 60, + "title": "coffee tasting", + "slug": "coffee-tasting", + "schedulingType": "managed", + "assignAllTeamMembers": true, + ... + } + ] +} +``` + + + +The team created in the previous step has no members, so we need to create managed users and later their membership in the team. To create a managed user here is the [create managed user](https://cal.com/docs/api-reference/v2/platform-managed-users/create-a-managed-user) endpoint. Example request body: +``` +{ + "email": "charlie@gmail.com", + "name": "charlie", + "timeZone": "Europe/Rome" +} +``` + +After creating managed user you have to save its "id", "accessToken" and "refreshToken" in your database and note down the "id" for the next step. Here is response: +``` +{ + "status": "success", + "data": { + "user": { + "id": 1458, + "email": "charlie+clxyyy21o0003sbk7yw5z6tzg@gmail.com", + "username": "charlie-clxyyy21o0003sbk7yw5z6tzg-gmail-com", + "name": "charlie", + ... + }, + "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoiYWNjZXNzX3Rva2VuIiwiY2xpZW50SWQiOiJjbHh5eXkyMW8wMDAzc2JrN3l3NXo2dHpnIiwib3duZXJJZCI6MTQ1OCwiZXhwaXJlc0F0IjoxNzQ1NDkwODQwMDAwLCJpYXQiOjE3NDU0ODcyNTh9.FI9-Hi7O_j4QLn7SuNJlOnmk-0MHhZoXPCncsmgyCoQ", + "accessTokenExpiresAt": 1745490840000, + "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0eXBlIjoicmVmcmVzaF90b2tlbiIsImNsaWVudElkIjoiY2x4eXl5MjFvMDAwM3Niazd5dzV6NnR6ZyIsIm93bmVySWQiOjE0NTgsImV4cGlyZXNBdCI6MTc3Njk4MTYwMDAwMCwiaWF0IjoxNzQ1NDg3MjU4fQ.YYTH7WeshMR-BpbNeSYFUubjTlsAsOhdhrge-LngRiw", + "refreshTokenExpiresAt": 1776981600000 + } +} +``` + + + + +Now we will create a membership for this user within the team by making a POST request to the [create membership](https://cal.com/docs/api-reference/v2/orgs-teams-memberships/create-a-membership) endpoint. Example body: + +``` +{ + "userId": 1458, + "accepted": true, + "role": "MEMBER" +} +``` +Note that `"accepted"` has to be `"true"` and `"userId"` has to be the id of the managed user created in the previous step. + + + + +Now, if we fetch managed user event types using the [get event types](https://cal.com/docs/api-reference/v2/event-types/get-all-event-types) endpoint and given our example +query params `eventSlug` and `username` (`?eventSlug=coffee-tasting&username=charlie-clxyyy21o0003sbk7yw5z6tzg-gmail-com`), the response will contain the "global" event type: + +``` +{ + "status": "success", + "data": [ + { + "id": 3673, + "ownerId": 1458, + "lengthInMinutes": 60, + "title": "coffee tasting", + "slug": "coffee-tasting" + ... + } + ] +} +``` + +Note, that when we create the "parent" managed event type in step 2 it has an id `3672` but the child managed event type belonging to managed user has `3673`, so they are separate entities +and the "child" managed event type is the same as having individually created event type just for that managed user. + +Now, if we update the "parent" managed team event type via [update an organization team event type](https://cal.com/docs/api-reference/v2/orgs-teams-event-types/update-a-team-event-type) endpoint, and fetch +again managed user event type using the [get event types](https://cal.com/docs/api-reference/v2/event-types/get-all-event-types) endpoint with same query parameters `eventSlug` and `username` as above, +the child managed event type will also be updated automatically. + +Now with this setup you can: +1. Each time you create a new managed user simply create membership within the team and have the event type created automatically. +2. If you want that already existing managed users have the event type created, you have to create team and then membership within the team just like we saw above. +3. You can create a team called "global" where you add all managed users so all managed users have the same event type or a subset of managed users have the same event type belonging to "subset-team" +if you want to have a subset of managed users have the same event type.