> ## Documentation Index
> Fetch the complete documentation index at: https://tinytalk.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Calendly
> Let your agent offer the right Calendly event type and embed the booking flow inline in the chat.
The Calendly tool lets your agent answer "can I book a call?" with an inline scheduler instead of a dead-end "yes, here's a link." Visitors see a booking card in the chat, click it, pick a time, and return to the conversation when they're done.
You don't need to give Tiny Talk your Calendly login or an API key. Calendly event-type URLs are public — you paste them into the configuration and the agent constructs a personalised booking link at conversation time.
For how tools work in general, plan limits, and the security model, see [Tools](/features/tools).
## What you need
* A Calendly account (free or paid — both work).
* One or more **active event types** with public booking URLs, like `https://calendly.com/your-handle/discovery-call`.
* An agent on a paid plan, using a model that supports tool calling. Most modern models do; the [AI Models](/features/ai-models) page lists the exceptions.
## Setting up Calendly
In Calendly, open **Event Types**. For each event you want to offer through the agent:
1. Click the event to open it.
2. Copy the **Public URL** at the top — it looks like `https://calendly.com/your-handle/discovery-call` or `https://calendly.com/team/your-org/intro`.
You can offer up to **10 event types** per agent. Pick the ones a visitor would realistically book through chat — a "Discovery Call", a "Demo", an "Onboarding session" — rather than every event you've ever created.
Don't include query strings in the URL. The agent appends visitor details (name, email, topic) automatically as Calendly prefill parameters; pre-existing query strings are rejected by the validator.
In the dashboard, go to **Agent → Tools → Platform Tools**. Find the **Calendly** card and click **Install**.
The configuration screen opens. Calendly is installed against the current agent — installing it once doesn't enable it on every agent in the workspace.
Under **Event types**, click **Add** for each event you want the agent to be able to book. Each event type has four fields.
* **Slug** — A short, lowercase identifier the agent uses to pick this event type (e.g. `discovery-call`, `demo`, `onboarding`). Lowercase letters, digits, and hyphens; up to 64 characters. Must be unique within this agent.
* **Label** — The display name shown to visitors in the booking card (e.g. *Discovery Call*). Up to 120 characters.
* **When to use** — The single most important field for routing accuracy. Describe the situation or intent that should trigger this event type — *not* what the meeting is, since the label already covers that. Up to 500 characters.
* **Calendly URL** — The public URL you copied in step 1.
Write **When to use** from the agent's point of view: *"Use when a prospect wants to evaluate the product or asks for a walkthrough."* Concrete intents and triggers route better than restating the meeting topic.
Under **Default event type**, pick one of the events you added. The agent will fall back to this when the conversation doesn't make it obvious which event type the visitor wants.
Leave it on **First in list** to use the first event type you added as the fallback. With a single event type configured, this setting doesn't matter — that event is always picked.
Under **Embed appearance**, two toggles control how Calendly renders inside the chat:
* **Hide event type details** — Hides the description and duration block at the top of Calendly's widget. Useful when the agent has already explained what the meeting is. Off by default.
* **Hide GDPR banner** — Hides Calendly's GDPR cookie banner inside the embed. On by default; turn it off if your privacy posture requires Calendly's banner to be visible.
These toggles only affect how the embed looks on your **website widget**. On WhatsApp and Slack the agent posts a markdown link, and Calendly's own page handles the styling.
Click **Save changes**. The tool is enabled by default — the agent can start booking from the next conversation.
The Platform Tools list now shows Calendly with an **Installed** badge.
## How the agent uses Calendly
Once installed, the agent sees Calendly as a tool it can call when a visitor asks to schedule something. The runtime is **channel-aware** — what the visitor sees depends on where the conversation is happening.
| Channel | What the visitor sees |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Website widget** (Messenger) | An inline booking card. Clicking it opens Calendly's scheduler embedded in the chat. After booking, the chat resumes automatically. |
| **WhatsApp** | A markdown link to the personalised Calendly URL. The visitor taps the link to open Calendly in their browser. |
| **Slack** | A markdown link in the Slack thread. |
| **API** (custom integration) | The same link, returned in the assistant message. |
The agent picks the right event type based on the **slug** and **when to use** description you set. If the conversation is ambiguous, it falls back to the default.
## What gets prefilled
If the visitor has already shared their contact details with the agent — through a [lead form](/features/contacts-leads), a Help Desk hand-off, or earlier in the conversation — the agent prefills them into Calendly automatically:
* **First name** and **last name**
* **Email**
The agent can also pass a short **topic** describing what the visitor wants to discuss. This is mapped to the **first custom question** on your Calendly event type (Calendly's `a1` slot), so visitors don't have to retype context they've already given the agent.
If you want richer prefill — for example, separate fields for company size or use case — add custom questions on the Calendly event type and the agent's topic answer will land in the first one.
## What visitors see in the chat
On the website widget, when the agent decides to use Calendly, it sends a short framing message ("Pick a time below 👇") followed by a card showing:
* A calendar icon
* The event type **label** you configured
* A **Schedule your call** button
* "Powered by Calendly" attribution
Tapping the button slides Calendly's scheduler into the chat. When the visitor finishes booking, the view returns to the conversation automatically after a couple of seconds — no extra tap required.
On WhatsApp or Slack the agent skips the embed and posts a markdown link instead, since neither channel can render an inline iframe.
## Example use cases
### Single event type: book a discovery call
The simplest setup. One event type the agent can offer when a visitor wants to talk to the team.
| Field | Value |
| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| Slug | `discovery-call` |
| Label | Discovery Call |
| When to use | When the visitor asks to talk to a human, requests a demo, or wants to discuss whether the product fits their use case. |
| Calendly URL | `https://calendly.com/your-handle/discovery-call` |
A visitor message like *"can someone walk me through how this works?"* triggers the tool. The visitor picks a time, and the booked meeting lands in your Calendly account with their name, email, and (if the agent collected it) a short topic note prefilled.
### Multiple event types: route by intent
Three event types let the agent route bookings based on what the visitor is asking for.
1. **Discovery Call** (`discovery-call`) — Use when a prospect wants to evaluate the product or has questions about pricing and fit. URL: `https://calendly.com/your-handle/discovery-call`
2. **Product Demo** (`demo`) — Use when the visitor explicitly asks for a demo or walkthrough of features. URL: `https://calendly.com/your-handle/demo`
3. **Onboarding** (`onboarding`) — Use when an existing customer wants help setting up the product or migrating data. URL: `https://calendly.com/your-handle/onboarding`
Set **Discovery Call** as the default — that's the safe pick when a visitor says "can I book a call?" without giving more context. The other two get picked when the conversation makes the intent specific.
Make each **When to use** describe a situation the others *wouldn't* match. If two descriptions overlap, the model has to guess — and may pick the wrong one.
### Internal scheduling assistant
Calendly works just as well for internal-facing agents. An HR assistant on an intranet portal could offer:
* **1:1 with HR** — Use when an employee wants to discuss benefits, leave, or any HR matter privately.
* **Manager office hours** — Use when an employee wants to talk to their manager outside their regular schedule.
Pair it with a [Custom Tool](/features/tools/custom-tool) that looks up the employee's manager, and the agent can offer the right person's calendar without the employee hunting for it.
## Disabling and uninstalling
Open the Calendly configuration and toggle **Enabled** off to stop the agent from offering bookings without losing your event-type configuration. The installation still counts against your per-agent tool limit while disabled.
To remove Calendly entirely, scroll to **Danger zone** and click **Uninstall**. A confirmation modal asks you to confirm. Uninstalling is immediate and can't be undone — your event-type configuration is deleted, but no Calendly data is touched. Existing bookings in your Calendly account are unaffected.
## Troubleshooting
The model decides whether to use the tool based on the **Label** and **When to use** fields you set. If it skips Calendly even when a visitor clearly wants to book:
* Make **When to use** explicit about the kinds of phrasing visitors actually use — *"asks to book a call, requests a meeting, wants to talk to someone"* — rather than generic descriptions.
* Confirm the installation is **enabled**.
* Check that the AI model on the agent supports tool calling. Older or very small models don't, and the runtime silently skips tool registration on unsupported models. The [AI Models](/features/ai-models) page lists what each model supports.
* Make sure you haven't hit your per-agent tool cap. Disabled tools count against the limit too.
Two event types with overlapping **When to use** descriptions force the model to guess. Rewrite each one so it describes a situation the others wouldn't match. Use concrete intents — *"asks for a demo or product walkthrough"* — rather than restating the event label.
A clear default also helps. The agent uses it whenever the conversation is ambiguous, so put the safest, most general event type there.
On the website widget, the agent should render an inline booking card with a **Schedule your call** button. If you only see a plain markdown link instead:
* Check you're viewing the live widget, not a Help Desk preview or a takeover thread. The card is rendered by the messenger.
* The visitor's browser needs to allow Calendly's iframe domain (`calendly.com`). Strict content-security policies on a host page can block it.
* Make sure the model selected for the agent supports tool calling — if it doesn't, the agent never invokes Calendly and posts a generic message instead.
Calendly prefill only works when the agent already knows the visitor's name and email. That happens automatically when the visitor has gone through a [lead form](/features/contacts-leads), been recognised by their contact token across sessions, or shared the details earlier in the conversation.
For first-time anonymous visitors, the booking form appears blank — they fill it in on Calendly directly. No configuration is needed; this is by design.
Not yet. Calendly is the only scheduler integration available right now; others are on the roadmap. In the meantime you can wire any scheduler with a public booking URL through a [Custom Tool](/features/tools/custom-tool), but you won't get the inline embed — the agent will post a link.
No. Calendly event-type URLs are public — you paste them into the configuration and that's it. Tiny Talk never authenticates against your Calendly account. Disabling or rotating your Calendly account doesn't affect anything Tiny Talk stores.
The validator accepts URLs in the form `https://calendly.com//` (or `https://calendly.com///` for team accounts). Common reasons it rejects a URL:
* The URL has query parameters (`?month=...`). Strip them — the agent adds prefill parameters automatically.
* The URL points to your profile page (`https://calendly.com/your-handle`) instead of a specific event. You need the per-event public URL.
* The URL uses `http://` instead of `https://`.
Tool calls don't consume extra credits — credit cost is determined by the AI model's response, the same as for any other reply. The booking flow itself happens on Calendly and isn't billed by Tiny Talk.