Calendly
Audience: Sales, management, support, engineering · Where in app: Settings → Integrations → Calendly · Plan availability: All plans (verify)
Calendly gives customers the familiar Calendly scheduling experience embedded directly inside the Knock Knock widget, while also capturing bookings made outside the widget (e.g. from an email link) via webhook. Every booking is treated as a direct-verification trigger and a hot-lead signal, so it lands on the visitor's timeline and bumps their lead score.
What it does
- Embeds the Calendly inline scheduler inside the widget.
- Captures bookings made anywhere (widget or external) via webhook.
- Verifies the booker's identity and stitches the booking to the Person.
- Fires the
booked_meetinglead-score event and queues CRM sync.
How it works
Auth model: OAuth + webhook + embed. Connect from Settings → Integrations → Calendly. Stored on companies.calendly_integration:
connected_at— the connected marker both booking ladders (backendresolveProvider, ms-commSchedulingClientHelper) read (d2a31ae9f).access_token/refresh_tokennow live in the credential vault (provider: 'calendly', auto-refreshed), and the old CryptHelper/token fallbacks in ms-comm are gone (9459aec). The dashboard never receives the tokens, so the card reads aconnectedflag (frontend4c9af445).owner_uri(the connected user URI)event_type_uri(selected event type, e.g. "30 min demo") +event_type_durationscheduling_url,organization_uri,event_type_namewebhook_status(active | failed | null),webhook_error(≤300 chars),webhook_checked_at— written bycalendlyApi.recordWebhookStatus()so the card can warn "Bookings are not syncing" with Retry
Calendly's OAuth, token storage, and webhook receipt/verification live in the backend, not ms-ai. The ms-ai Calendly module is a thin delegator: the AI agent's availability/booking calls go to backend
GET /calendly/{company_id}/available-slotsandPOST /calendly/{company_id}/book-meeting(authenticated with the cross-servicex-api-key).
Direction: inbound (bookings) + embed.
Widget embed
When connected, the AI agent can offer booking via a tool call ("Want to book a demo? Here's my calendar"), and the "Book a meeting" CTA opens the Calendly inline scheduler in the widget. The visitor picks a slot → booking created → Calendly sends the confirmation.
Webhook
Calendly's webhook fires on invitee.created and invitee.canceled (CALENDLY_WEBHOOK_EVENTS in app/lib/calendlyApi.js, which also owns token refresh + persistence on 401). A reschedule arrives as invitee.created carrying old_invitee; the paired invitee.canceled with rescheduled: true is ignored. Reschedules and cancels now emit the tenant booking_rescheduled / booking_cancelled webhook events. On receipt, the backend:
- Unifies the booking onto
PersonProfile.bookings[]withsource=calendly. - Creates a
BookingModelrow. - Fires the
booked_meetinglead-score event. - Queues CRM sync.
This means bookings made via Calendly outside the widget (e.g. from an email link) still appear on the Person's timeline.
Booking questions (2026-09-29)
The event type's invitee questions are asked of the visitor instead of guessed:
- Backend: public
GET /calendly/:company_id/booking-questions→CalendlyAdapter.bookingQuestions(company)readscustom_questionsoffGET /event_types/<uuid>, keeps enabled ones sorted byposition, and returns{ name, type, required, position, answer_choices, include_other }(type:string | text | phone_number | single_select | multi_select). Module-level cache keyed byevent_type_uri, 5-minute TTL. Never throws —[]keeps the plain flow. - Widget:
useBookingQuestions(chat sheet + both in-call layouts) fetches them when the slots'bookingType === 'calendly', renders choices (+ an Other sentinel with free text wheninclude_other), text areas, and inputs;completeblocks continue until required ones are answered. Answers ride oncalendar_booking_meta.answersand in the booking message text, and on calls as a contextual update to the voice agent. Multi-select is newline-separated (Calendly's own format). Off for reschedule. - ms-ai:
booking-questions.tsfetches the same route;meetings.agent.tsrenders a "BOOKING QUESTIONS" prompt block only when there are questions (every other company's prompt is unchanged). The agent collects name + answers after the slot is picked and passesuser_name+booking_answersonbook_meeting; a missing required answer or an invented choice is refused with the exact question/choices so the agent asks. Voice tools get optionalparticipant_name/booking_answers("Question: answer" per line) — never inrequired, so agents without questions send nothing. - ms-comm (
MessageController.bookCalendlySlot) forwards the widget'scalendar_booking_meta.answers(≤30, trimmed) asinvitee.answersto the backend booking call. - Precedence at booking (
CalendlyAdapter): visitor-supplied answers win (snapped onto the exact choice text, case-insensitive; unlisted text kept as "Other" text); only unanswered questions fall back to_getLeadContextheuristics (best choice / "Other" / chat digest for required, blank for optional).
Placeholder emails: ms-ai placeholder-email.ts refuses participant_email on reserved/stand-in domains (example.com/org/net/edu, .test/.invalid/.localhost, domain.com, yourdomain.com, test.com, …) at the controller and the chat tool — an LLM once sent user@example.com and Calendly booked it and mailed nobody. Prompts tell the agent to offer a callback when the visitor won't give an email.
Error detail: calendlyApi.apiErrorMessage appends Calendly's data.details[] (parameter: message) — its 400s otherwise say only "The supplied parameters are invalid." The card shows the upgrade hint only when webhook_error matches upgrade|permission denied|plan; anything else (e.g. a bad callback URL) reads "Please retry, or contact support if this keeps happening."
UTM tracking (2026-10-14)
app/lib/calendlyTracking.js (afe477309) stamps every Knock Knock-made Calendly booking so the tenant's own Calendly → CRM pipeline can tell them apart and find the conversation:
utm_source=knock_knock_ai, or — for a company with anagency_id— the agency's name slugified (Next Level Digital→next_level_digital), so a white-labelled client never sees our name.calendlyUtmSource(company)never throws (falls back to the default).utm_content= theuser_session_id(same id as ournew_bookingwebhook). It must stay the session id:CalendlyController@webhookusestracking.utm_contentto tieinvitee.createdback to its session. A transcript wouldn't fit anyway — Calendly drops UTM values of 255+ chars (fit()caps at 254).- Direct bookings (
POST /invitees) send atrackingobject viabookInviteeWithTracking; if Calendly 400s on the tracking object itself (isTrackingRejection), it books again without it — losing UTMs never loses the meeting. The follow-up webhook dedupes against the row oncalendly_invitee_id. - Booking links (
_withSessionTracking→withCalendlyTracking) carry the same values as query params, which Calendly copies into the invitee'stracking.
Test: test/calendly-booking-link.spec.js.
Identity verification
When the form intercept detects calendly.event_scheduled, the email is captured directly from the Calendly invitee data, the session is verified (direct trigger), and the Person is stitched to the booking.
Multiple event types
An auxiliary CalendlyModel tracks per-event-type configuration when more than one event type is needed.
Configuration & options
| Item | Detail |
|---|---|
| Connect | Settings → Integrations → Calendly (OAuth) |
| Event type | One default event_type_uri per company |
| Backend availability | GET /calendly/{company_id}/available-slots |
| Backend booking | POST /calendly/{company_id}/book-meeting |
| Webhook events | invitee.created, invitee.canceled |
| Booking questions | GET /calendly/:company_id/booking-questions (public) |
Slot-already-taken: the booking flow handles the already_filled error with a "slot taken" message to the visitor. A retry after a lost success (6953e9336) recognises the session's own booking at that time — including one made under an email the caller has since corrected — instead of reporting the slot as taken.
Behaviors & edge cases
- One event type per company: to direct visitors to different scheduling links per context, use the widget's page rules + the AI agent system prompt.
- Cancellations / reschedules: mirrored onto the booking copies and dispatched as webhook events; there's no auto-rebook flow.
- Re-subscribe sweep (
app/lib/calendlyWebhookResubscribe.js, admin page Integrations Maintenance →POST /admin/maintenance/calendly-resubscribe+ jobs poll, background-only): matches subscriptions by callback path/calendly/webhook; on apply it deletes all of ours first, then creates — Calendly allows one subscription per callback URL — and restores the previous event set if the create fails. Seven free-plan accounts can't hold webhooks at all. - Backfill: the webhook only fires for new bookings — bookings from old emails require a manual import (admin tool).
- Free-tier webhook limits: Calendly's free tier limits webhooks; make sure the workspace can receive them.
- Time zones: come from Calendly; the widget displays the visitor's local time.
Plan & limits
- Available on all plans (verify exact tier gating).
- Webhook availability depends on the customer's Calendly plan.
Technical implementation
- Owning service:
backendholds OAuth, token storage, the webhook endpoint, and booking persistence (BookingModel,CalendlyModel). - AI-side delegation:
ms-aisrc/integrations/actions/calendly/calendly.service.ts→ backend availability/booking endpoints, via the unifiedcalendar-router.service.ts. - Config:
companies.calendly_integration.*.
What Nox can tell you
- Connection status.
- Recent Calendly bookings (
knox-recent-bookings(source=calendly)). - Booking attribution to the visitor journey; "of yesterday's bookings, how many came via Calendly?" (split by source).
Tools: knox-recent-bookings, knox-visitor-bookings.
Related
- Google Calendar · GoHighLevel (GHL calendar) · Integrations Overview
- Identity Graph