Integration

Calendly, when the scheduling rules already live somewhere else

A Calendly integration lets a Telegram bot hand a qualified person to an existing scheduling page and learn what they booked. It is a handoff rather than native booking — Calendly owns the availability rules — which is right when those rules already exist and wrong when the goal was booking inside the chat.

Calendly integration: auth, limits and availability

Auth model: OAuth 2.0
Ownership: Calendly owns availability, buffers and routing — the API does not expose fine-grained control
GCC availability: No regional restriction; API access is gated by plan tier
Data flow: 5 hops, worker-mediated

As of 2025-10-01, Telegram Bot API 13.4

Why this integration exists

Plenty of teams already run scheduling through Calendly, with buffer times, minimum notice, round-robin assignment and routing forms configured over years. Rebuilding that inside a bot means recreating rules somebody already tuned, and it means two systems disagreeing about whether Thursday afternoon is available.

So the pragmatic pattern is a handoff. The bot does what it is good at — qualifying, answering questions, capturing context — and then passes a scheduling link with what it knows already filled in. Calendly does the availability arithmetic, and a webhook tells the bot what was booked so the conversation can continue with the appointment in it.

The honest limitation is that this is not booking in Telegram. The person leaves the chat, completes a web flow and comes back, and every one of those transitions loses some proportion of people. For a B2B call where the prospect is motivated, that loss is small and the saved complexity is large. For a consumer booking a haircut, it is the wrong trade and a native flow inside the chat converts considerably better.

How the data actually moves

The scheduling link carries what the bot already knows, so the prospect is not asked twice for their name and email.

A personal access token for a single-organisation integration, or OAuth where the bot serves several Calendly accounts. The token is a Worker secret. Webhook subscriptions are created through the API and their signing key is verified on every delivery, since an unverified endpoint accepts fabricated booking events.

Auth model: OAuth 2.0

Their limits, and what they mean for you

Calendly owns availability, buffers, notice periods and routing; the API does not expose fine-grained control over them.

This is a handoff rather than a booking engine. Where the requirement is booking rules the bot controls, Calendly is the wrong component.

Webhook subscriptions are created via the API and are scoped to a user or organisation.

Subscriptions are created at setup and verified on startup. A missing subscription means bookings happen and the bot never learns, which looks like people abandoning.

Prefill parameters populate the booking form but do not bypass it.

The prospect still completes a form, and prefill reduces friction rather than removing the step. Presenting it as one-tap booking oversells what happens.

API rate limits apply per token and are modest.

The integration is event-driven rather than polling. Polling for new bookings consumes the allowance and adds latency for no benefit.

How it fails, and what happens when it does

A prospect books and the bot never mentions it again.

A missing or expired webhook subscription. Verified on startup, because the symptom is indistinguishable from the prospect losing interest.

The person is asked for details the bot already had.

Prefill parameters were not passed. It is a small thing that reads as the two systems not talking to each other, which is exactly what it is.

A cancellation happens in Calendly and the bot still expects the meeting.

Cancellation and reschedule events are subscribed to as well as creation. Handling only the booking event leaves the bot confidently wrong.

A large share of qualified people never complete the booking.

The handoff is costing conversion. This is measurable, and where the loss is material a native in-chat flow is the answer rather than a better link.

Availability in the UAE and the wider GCC

Global

No regional restriction. API access depends on plan tier, with webhooks requiring a paid plan.

B2B scheduling

The strong case. A motivated prospect completing a short web form loses little, and the saved complexity is real.

Consumer booking

A poor fit. Every transition out of the chat costs completion, and a native flow converts considerably better.

Free plan

Webhooks are unavailable, so the bot cannot learn what was booked. That removes most of the reason to integrate at all.

When not to use this integration

You are booking consumers. Every hop out of the chat costs completion, and a native flow inside Telegram converts materially better.
You need the bot to control availability rules. Calendly owns them, which is the point and also the limit.
You are on a plan without webhooks. The bot cannot learn what was booked, which removes most of the value.
You do not already use Calendly. Adopting it to integrate with it is backwards; build booking natively instead.

What it runs on

Component	Version	Why
Cloudflare Workers	current	Link generation, webhook verification and subscription checks.
Cloudflare D1	current	Bookings linked to leads, and handoff completion tracking.
Zod	4.4	Validation of webhook payloads after signature verification.
grammY	1.45	Qualification, handoff and the follow-up conversation.

Questions that come up during scoping

Is this booking inside Telegram?

No, and describing it as such would be dishonest. The person leaves the chat for a web form and comes back. That trade is good for B2B scheduling where rules already exist and poor for consumer booking, where a native flow converts considerably better.

Why not rebuild the scheduling rules in the bot?

Because somebody already tuned buffers, notice periods and routing over years, and two systems will eventually disagree about whether a slot is free. Where those rules do not already exist, building natively is the better answer.

Why does the bot sometimes not know a meeting was booked?

A missing or expired webhook subscription. It is verified on startup because the symptom — silence after the handoff — is indistinguishable from the prospect simply losing interest.

Do we need a paid Calendly plan?

For webhooks, yes. Without them the bot cannot learn what was booked and the integration is reduced to sending a link, which the bot could do without any integration at all.

What happens if someone cancels?

Cancellation and reschedule events are subscribed to alongside creation. Handling only the booking event leaves the bot confidently expecting a meeting that is no longer happening.

How do we know if the handoff is costing us?

By measuring it. The proportion of qualified people who complete the booking is tracked, and where the loss is material the honest recommendation is to replace the handoff with a native flow rather than to keep improving the link.