sales-calcom

What this skill does

# Cal.com Platform Help

## Step 1 — Gather context

If `references/learnings.md` exists, read it first for accumulated platform knowledge.

Ask the user:

1. **What area of Cal.com do you need help with?**
   - A) Booking pages & event types — setup, customization, branding
   - B) Round-robin & team scheduling — routing, collective events, managed events
   - C) Routing forms — lead qualification before booking
   - D) API & webhooks — building integrations, automation
   - E) Self-hosting — Docker setup, calendar sync, Outlook issues
   - F) Workflows — automated reminders, notifications, follow-ups
   - G) Embeddable atoms — embedding Cal.com in your app
   - H) Payments — Stripe/PayPal collection on booking
   - I) Choosing Cal.com vs Calendly vs other tools
   - J) Something else

2. **Are you on cloud or self-hosted?**
   - A) Cal.com cloud (cal.com)
   - B) Self-hosted (Docker/custom)
   - C) Not sure yet / evaluating

3. **What plan are you on?**
   - A) Free
   - B) Teams ($12/user/mo)
   - C) Organizations ($28/user/mo)
   - D) Enterprise
   - E) Self-hosted (no plan)

**If the user's request already provides most of this context, skip directly to Step 2.** Lead with your best-effort answer using reasonable assumptions (stated explicitly), then ask only the most critical 1-2 clarifying questions at the end.

## Step 2 — Route or answer directly

If the request maps to a specialized skill, route:
- General scheduling strategy → "This is a scheduling strategy question — run: `/sales-meeting-scheduler {user's question}`"
- CRM integration patterns → "This is a tool integration question — run: `/sales-integration {user's question}`"
- No-show recovery or reminder design → "This is a scheduling optimization question — run: `/sales-meeting-scheduler {user's question}`"

Otherwise, answer directly from platform knowledge.

## Step 3 — Cal.com platform reference

**Read `references/platform-guide.md`** for the full platform reference — capabilities, pricing, data model, API quick-starts, webhook payloads, integration recipes.

Answer the user's question using only the relevant section. Don't dump the full reference.

## Step 4 — Actionable guidance

You no longer need the platform guide — focus on the user's specific situation.

1. **Step-by-step instructions** for their goal in Cal.com
2. **Configuration recommendations** — specific settings, with navigation paths
3. **Code examples** for API/webhook questions — point to `references/calcom-api-reference.md`
4. **Verification steps** — how to confirm it worked

If you discover a gotcha, workaround, or tip not covered in `references/learnings.md`, append it there.

## Gotchas

> *Best-effort from research — review these, especially items about plan-gated features and integration gotchas that may be outdated.*

- **Round-robin and routing forms require the Teams plan ($12/user/mo).** Free plan users can't distribute meetings across reps. Check plan before recommending team scheduling features.
- **Self-hosted calendar sync does not auto-detect cancellations immediately.** If a user deletes an event in Google/Outlook, Cal.com may still show the slot as booked until the next sync cycle. This is a common complaint — recommend checking sync interval settings.
- **Removing a user from a team doesn't remove them from round-robin host tables.** After removing someone, manually check the round-robin event type's host list. Otherwise departed reps keep getting booked.
- **Self-hosted Outlook integration requires Azure AD app registration.** Missing this step is the #1 cause of "can't connect Outlook" on self-hosted instances. The cloud version handles this automatically.
- **Webhook payloads differ between booking events and meeting events.** Booking events use `{ triggerEvent, createdAt, payload: {...} }` wrapper. Meeting events (MEETING_STARTED/ENDED) use a flat structure with no nested payload. Don't assume consistent shape.
- **Custom API access requires the Teams plan or higher.** Free plan users get basic API key access for personal use but custom API integrations need Teams+.

## Related skills

- `/sales-meeting-scheduler` — Scheduling strategy across all tools — booking page CRO, no-show recovery, round-robin design, tool selection
- `/sales-integration` — Connect Cal.com to CRM and other tools via webhooks, Zapier, or API
- `/sales-vimcal` — Vimcal platform help (keyboard-first calendar alternative)
- `/sales-reclaim` — Reclaim.ai platform help (AI task scheduling with scheduling links)
- `/sales-do` — Not sure which skill to use? The router matches any sales objective to the right skill. Install: `npx skills add sales-skills/sales --skill sales-do`

## Examples

### Example 1: Setting up booking pages for a solo founder
**User says**: "I just signed up for Cal.com free plan — how do I set up a booking page for discovery calls?"
**Skill does**:
1. Walks through creating a 30-min discovery call event type
2. Configures availability — working hours, 15-min buffer, 4-hour minimum notice
3. Sets up Cal Video or Zoom integration for auto-generated meeting links
4. Creates email reminder workflow (24hr + 1hr)
5. Connects Google Calendar for conflict checking
**Result**: Fully configured booking page with reminders and calendar sync — ready to share

### Example 2: Webhook integration for CRM sync
**User says**: "How do I listen for new bookings and push them to my CRM via webhook?"
**Skill does**:
1. Points to `references/calcom-api-reference.md` for webhook payload schema
2. Walks through creating a BOOKING_CREATED webhook subscription at `/settings/developer/webhooks`
3. Shows HMAC-SHA256 signature verification code
4. Provides example payload parsing to extract attendee email, meeting time, and event type
5. Shows how to map fields to CRM contact/event creation
**Result**: Working webhook listener that verifies signatures and syncs bookings to CRM

### Example 3: Self-hosted Outlook calendar not connecting
**User says**: "I self-host Cal.com with Docker and can't connect my Outlook calendar"
**Skill does**:
1. Identifies root cause: Azure AD app registration required for self-hosted Outlook
2. Walks through creating an Azure AD app with Calendar.ReadWrite permissions
3. Shows the environment variables needed (MS_GRAPH_CLIENT_ID, MS_GRAPH_CLIENT_SECRET)
4. Verifies the redirect URI matches the Cal.com instance URL
**Result**: Outlook calendar connected with bi-directional sync

## Troubleshooting

### Self-hosted instance stuck at localhost or giving 404
**Symptom**: Booking pages return 404 or the app redirects to localhost:3000 despite setting NEXT_PUBLIC_WEBAPP_URL
**Cause**: Environment variables not applied correctly, or Docker container not rebuilt after changes
**Solution**: Verify `.env` has `NEXT_PUBLIC_WEBAPP_URL=https://your-domain.com`, `NEXTAUTH_URL=https://your-domain.com`, and `CALENDSO_ENCRYPTION_KEY` set. Rebuild the container after any `.env` change. If using reverse proxy (nginx/Caddy), ensure it forwards the Host header.

### Calendar sync not reflecting external changes
**Symptom**: Events deleted or moved in Google/Outlook still show as booked in Cal.com
**Cause**: Cal.com polls calendars on a sync interval — it doesn't get instant push notifications from all providers
**Solution**: Check Settings > Calendars to verify bi-directional sync is enabled. For faster sync, use the API to trigger a manual refresh. On self-hosted, check the `CRON_ENABLE_CALENDAR_SYNC` environment variable is set to true.

### Webhooks not firing for booking events
**Symptom**: Webhook subscription exists but no POST requests arrive at the subscriber URL
**Cause**: Subscriber URL must be HTTPS on cloud Cal.com (HTTP only allowed on self-hosted). Private IPs and localhost are blocked on cloud.
**Solution**: Verify the subscriber URL is publicly accessible HTTPS. Check that the correct trigger events are selected. Use a tool like webhook.site to test. On self-hosted, check that the webhook worker process