Skip to main content

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_meeting lead-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 (backend resolveProvider, ms-comm SchedulingClientHelper) read (d2a31ae9f). access_token / refresh_token now 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 a connected flag (frontend 4c9af445).
  • owner_uri (the connected user URI)
  • event_type_uri (selected event type, e.g. "30 min demo") + event_type_duration
  • scheduling_url, organization_uri, event_type_name
  • webhook_status (active | failed | null), webhook_error (≤300 chars), webhook_checked_at — written by calendlyApi.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-slots and POST /calendly/{company_id}/book-meeting (authenticated with the cross-service x-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:

  1. Unifies the booking onto PersonProfile.bookings[] with source=calendly.
  2. Creates a BookingModel row.
  3. Fires the booked_meeting lead-score event.
  4. 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) reads custom_questions off GET /event_types/<uuid>, keeps enabled ones sorted by position, and returns { name, type, required, position, answer_choices, include_other } (type: string | text | phone_number | single_select | multi_select). Module-level cache keyed by event_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 when include_other), text areas, and inputs; complete blocks continue until required ones are answered. Answers ride on calendar_booking_meta.answers and 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.ts fetches the same route; meetings.agent.ts renders 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 passes user_name + booking_answers on book_meeting; a missing required answer or an invented choice is refused with the exact question/choices so the agent asks. Voice tools get optional participant_name / booking_answers ("Question: answer" per line) — never in required, so agents without questions send nothing.
  • ms-comm (MessageController.bookCalendlySlot) forwards the widget's calendar_booking_meta.answers (≤30, trimmed) as invitee.answers to 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 _getLeadContext heuristics (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 an agency_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 = the user_session_id (same id as our new_booking webhook). It must stay the session id: CalendlyController@webhook uses tracking.utm_content to tie invitee.created back 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 a tracking object via bookInviteeWithTracking; 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 on calendly_invitee_id.
  • Booking links (_withSessionTracking → withCalendlyTracking) carry the same values as query params, which Calendly copies into the invitee's tracking.

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​

ItemDetail
ConnectSettings → Integrations → Calendly (OAuth)
Event typeOne default event_type_uri per company
Backend availabilityGET /calendly/{company_id}/available-slots
Backend bookingPOST /calendly/{company_id}/book-meeting
Webhook eventsinvitee.created, invitee.canceled
Booking questionsGET /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: backend holds OAuth, token storage, the webhook endpoint, and booking persistence (BookingModel, CalendlyModel).
  • AI-side delegation: ms-ai src/integrations/actions/calendly/calendly.service.ts → backend availability/booking endpoints, via the unified calendar-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.