Joe Au-YeungGitHubDevin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>Hariom Balhara* docs: update embed-events.mdx with all currently emitted embed events Co-Authored-By: joe@cal.com <j.auyeung419@gmail.com> * docs: remove V2 suffix from event names in documentation Per feedback, the documentation should not expose internal versioning details. Event names are now presented as clean, non-versioned names: - bookingSuccessful (instead of bookingSuccessfulV2) - rescheduleBookingSuccessful (instead of rescheduleBookingSuccessfulV2) - dryRunBookingSuccessful (instead of dryRunBookingSuccessfulV2) - dryRunRescheduleBookingSuccessful (instead of dryRunRescheduleBookingSuccessfulV2) Added note about using wildcard listener for future-proofing. Co-Authored-By: joe@cal.com <j.auyeung419@gmail.com> * docs: use V2 suffix for embed event names to match code (#25263) * docs: update embed events to use V2 event names - Document bookingSuccessfulV2 instead of deprecated bookingSuccessful - Document rescheduleBookingSuccessfulV2 instead of deprecated rescheduleBookingSuccessful - Keep dryRunBookingSuccessful and dryRunRescheduleBookingSuccessful without V2 suffix (only V2 versions exist) - Add comprehensive event documentation with all public and internal events - Organize events into Public Events and Internal Events sections Co-Authored-By: hariom@cal.com <hariombalhara@gmail.com> * fix: use V2 suffix for dry-run event names - Change dryRunBookingSuccessful to dryRunBookingSuccessfulV2 - Change dryRunRescheduleBookingSuccessful to dryRunRescheduleBookingSuccessfulV2 - These match the actual event names emitted in the code (only V2 versions exist) Co-Authored-By: hariom@cal.com <hariombalhara@gmail.com> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> --------- Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Co-authored-by: Hariom Balhara <hariombalhara@gmail.com>
62 lines
8.0 KiB
Plaintext
62 lines
8.0 KiB
Plaintext
---
|
|
title: Embed Events
|
|
---
|
|
|
|
## Actions
|
|
|
|
You can listen to an action that occurs in embedded cal link as follows. You can think of them as DOM events. We are avoiding the term "events" to not confuse it with Cal Events.
|
|
|
|
```js
|
|
<script>
|
|
Cal("on", {
|
|
action: "ANY_ACTION_NAME",
|
|
callback: (e)=>{
|
|
// `data` is properties for the event.
|
|
// `type` is the name of the action(You can also call it type of the action.) This would be same as "ANY_ACTION_NAME" except when ANY_ACTION_NAME="*" which listens to all the events.
|
|
// `namespace` tells you the Cal namespace for which the event is fired/
|
|
const {data, type, namespace} = e.detail;
|
|
}
|
|
})
|
|
</script>
|
|
```
|
|
|
|
## Following are the list of supported actions.
|
|
|
|
<Info>Event payloads may evolve over time. For the most reliable integration, you can listen to `action: "*"` to receive all events and inspect `e.detail.type` and `e.detail.data` at runtime.</Info>
|
|
|
|
### Public Events
|
|
|
|
These events are intended for external use and provide information about user interactions and booking lifecycle.
|
|
|
|
| Action | Description | Properties |
|
|
|----------------------------|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
|
|
| eventTypeSelected | When user chooses an event-type from the listing. | `eventType: object` // Event Type that has been selected |
|
|
| bookingSuccessfulV2 | When a booking is successfully created. It might not be confirmed. | `uid: string` // Booking unique identifier <br /> `title: string` // Booking title <br /> `startTime: string` // Booking start time <br /> `endTime: string` // Booking end time <br /> `eventTypeId: number` // Event type ID <br /> `status: string` // Booking status <br /> `paymentRequired: boolean` // Whether payment is required <br /> `isRecurring: boolean` // Whether this is a recurring booking <br /> `allBookings: array` // For recurring bookings, array of all booking times <br /> `videoCallUrl: string` // Video call URL if available |
|
|
| rescheduleBookingSuccessfulV2 | When a booking is successfully rescheduled. | Same properties as `bookingSuccessfulV2` |
|
|
| dryRunBookingSuccessfulV2 | When a dry run booking is successfully created (test mode). | Same properties as `bookingSuccessfulV2` (without `uid`) |
|
|
| dryRunRescheduleBookingSuccessfulV2 | When a dry run reschedule is successful (test mode). | Same properties as `bookingSuccessfulV2` (without `uid`) |
|
|
| bookingCancelled | When a booking is cancelled. | `booking: object` // Booking details including cancellationReason <br /> `organizer: object` // Organizer details (name, email, timeZone) <br /> `eventType: object` // Event type details |
|
|
| availabilityLoaded | When availability slots are successfully loaded. | `eventId: number` // Event type ID <br /> `eventSlug: string` // Event type slug |
|
|
| routed | When a routing form routes to an action (event type, external URL, or custom page). | `actionType: string` // Type of action: "customPageMessage", "externalRedirectUrl", or "eventTypeRedirectUrl" <br /> `actionValue: string` // The value/URL of the action |
|
|
| navigatedToBooker | When user navigates to the booker interface. | None |
|
|
| linkReady | Tells that the link is ready to be shown now. | None |
|
|
| linkFailed | Fired if link fails to load. | `code: string` // Error Code <br /> `msg: string` // Human Readable message <br /> `data: object` // More details to debug the error (includes url) |
|
|
|
|
### Internal Events
|
|
|
|
These events are used internally by the embed system for communication between the iframe and parent window. They are prefixed with `__` and are not intended for external use.
|
|
| Action | Description | Properties |
|
|
|----------------------|-------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
|
|
| __iframeReady | Fired when the embedded iframe is ready to communicate with parent snippet. | `isPrerendering: boolean` // Whether the iframe is in prerender mode |
|
|
| __windowLoadComplete | Tells that window load for iframe is complete. | None |
|
|
| __dimensionChanged | Tells that dimensions of the content inside the iframe changed. | `iframeWidth: number` <br /> `iframeHeight: number` <br /> `isFirstTime: boolean` // Whether this is the first dimension change |
|
|
| __routeChanged | Fired when the route changes within the iframe. | None |
|
|
| __closeIframe | Fired when the iframe should be closed. | None |
|
|
| __connectInitiated | Fired when connection to a prerendered iframe is initiated. | None |
|
|
| __connectCompleted | Fired when connection to a prerendered iframe is completed. | None |
|
|
| __scrollByDistance | Instructs the parent to scroll by a specific distance. | `distance: number` // Distance in pixels to scroll by |
|
|
|
|
<Info>Events that start with `__` are internal and should not be relied upon for external integrations as they may change without notice.</Info>
|
|
|
|
To get more details on how Embed actually works, you can refer to this [Embed Flowchart](https://www.figma.com/file/zZ5oaUpg12Fuu5mGZrPlP5/Embed-Flowchart).
|