Documentation Index Fetch the complete documentation index at: https://docs.telli.com/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Supported Providers
When you connect a calendar, your voice AI agent can:
Check availability — See open time slots in real-time during callsBook appointments — Schedule meetings without any manual interventionCollect information — Gather booking details from callers or your CRM Each agent can have its own calendar connection, so different workflows can book different meeting types or route to different teams. telli supports four main calendar integrations: Provider Best For Calendly Teams already using Calendly with complex booking forms Cal.com Teams using Cal.com for scheduling HubSpot Meetings HubSpot users who book through HubSpot Custom Calendar API Companies with their own scheduling system
Getting Started
Open Your Agent
Log in to the telli app
Navigate to Agents in the sidebar
Select the agent you want to configure
Scroll to the Calendar Integration section
Choose Your Provider
Click the Select Integration Type dropdown to see available options:
Calendly — For Calendly usersCal.com — For Cal.com usersHubSpot — For HubSpot Meetings usersGeneric Calendar — For custom API connections Provider Setup Calendly
Cal.com
HubSpot Meetings
Custom Calendar API
When to Use
Your team already uses Calendly
You have custom booking questions on your event types
You want to automatically populate form fields from caller data
Different agents should book different meeting types
Fields Required Field Description API Key Your Calendly API key Event Type URI The Calendly event type to use (e.g., johndoe/30min) External URL (Optional) Your Calendly booking page URL Booking Fields Mappings for custom questions on your event type
Booking Fields You can map how each question on your Calendly form gets answered: Source Type How It Works When to Use Constant Fixed value every time Company name, internal notes, team name Contact Property Pulled from the caller’s contact record in your CRM Email, phone, company, first/last name System Variable Resolved from internal data Contact ID, timezone, account tier LLM Parameter Agent asks the caller during the call Meeting topic, preferred language, special requests
Every required custom question on your Calendly event type must have a mapping configured, or the booking will fail. Optional questions without a mapping are simply skipped.
Setup Steps
Go to Calendar Integration → select Calendly
Enter your Calendly API key
Enter your event type URI (from your Calendly link)
Configure booking field mappings for each required question
Finding Your Event Type URI Your Calendly event link looks like: https://calendly.com/johndoe/30min-call
The URI is: johndoe/30min-call When to Use
Your team uses Cal.com for scheduling
You need agent-specific routing (different agents → different event types)
You want the flexibility of Cal.com’s open-source platform
Fields Required Field Description API Key Your Cal.com API key Event Type The Cal.com event type to use
Setup Steps
Go to Calendar Integration → select Cal.com
Enter your Cal.com API key
Enter the event type slug
Finding Your Event Type Your Cal.com event link looks like: https://cal.com/johndoe/30min
The event type is: 30min When to Use
Your team uses HubSpot for sales and scheduling
You want bookings to automatically create HubSpot records
You need meetings tied directly to your HubSpot CRM
Fields Required Field Description Access Token Your HubSpot private app access token Meeting Link Slug The slug from your HubSpot meeting URL Meeting Duration Duration in minutes (e.g., 30)
Setup Steps
Go to Calendar Integration → select HubSpot
Enter your HubSpot private app access token
Enter your meeting link slug (e.g., johndoe/30min-call)
Enter the meeting duration in minutes
Finding Your Meeting Link Slug
Go to HubSpot’s Meetings Scheduler
Open the meeting you want to use
Copy the meeting URL — it looks like:
https://meetings.hubspot.com/johndoe/30min-call
The slug is everything after meetings.hubspot.com/: johndoe/30min-call
Creating a HubSpot Private App
In HubSpot, go to Settings → Integrations → Private Apps
Click Create a private app
Give it a name (e.g., telli Integration)
Go to the Scopes tab
Add these scopes:
crm.objects.contacts.writecrm.schemas.contacts.writescheduler.meetings.meeting-link.readtickets
Click Create
Copy the access token (shown once — save it securely)
Use this token in telli
When to Use
You have your own scheduling system
You need full control over the booking logic
You’re not using any of the supported third-party tools
You want to integrate with an internal booking system
Fields Required Field Description Available Slots URL Your API endpoint to fetch available appointments Book Appointment URL (Optional) Your API endpoint to book a selected slot
Setup Steps
Go to Calendar Integration → select Generic Calendar
Enter your Available Slots URL (required)
Enter your Book Appointment URL (optional — leave blank for availability-only)
Implementation Notes
Use UTC timestamps in ISO 8601 format
Return HTTP 200 responses with success/failure in the body
Make sure your endpoints are publicly reachable by telli
The start_iso field is used as the slot identifier for bookings
Get Available Slots Request: POST https: //your-api.com/available { "contact_id" : "telli contact identifier" , "external_contact_id" : "your internal contact ID" , "contact_details" : { "email" : "[email protected] " , "name" : "John Doe" } }
Response: { "available" : [ { "start_iso" : "2024-01-02T14:00:00.000Z" , "end_iso" : "2024-01-02T14:30:00.000Z" }, { "start_iso" : "2024-01-02T15:00:00.000Z" , "end_iso" : "2024-01-02T15:30:00.000Z" } ] }
Book Appointment Request: POST https: //your-api.com/book { "contact_id" : "telli contact identifier" , "external_contact_id" : "your internal contact ID" , "start_iso" : "2024-01-02T14:00:00.000Z" , "contact_details" : { "email" : "[email protected] " , "name" : "John Doe" } }
Success Response: Failure Response: { "status" : "failed" , "reason" : "Appointment slot is no longer available" }
Requests from telli include a signature header you can verify: const crypto = require ( "crypto" ); function verifyRequest ( payload , signature , apiKey ) { const expectedSignature = crypto . createHmac ( "sha256" , apiKey ) . update ( JSON . stringify ( payload )) . digest ( "hex" ); return signature === expectedSignature ; }
Check the x-telli-signature header on incoming requests. Per-Agent Configuration
Example
Troubleshooting
Each agent can have its own calendar connection. This is powerful for:
Different teams with different calendars
Different sales motions (demo calls vs. discovery vs. support)
Routing to specific reps or departments
A/B testing different scheduling flows
Simply configure the calendar integration separately for each agent. Once connected, your agent can handle scheduling conversations like this:
Caller: “I’d like to schedule a demo”Agent: “Let me check availability” → calls your calendarAgent: “I have Tuesday at 2pm or Wednesday at 10am — which works?”Caller: “Tuesday please”Agent: Books the slot and confirms the appointment The entire interaction is hands-free. Issue Solution Booking fails Check that all required booking fields are mapped (Calendly) No available slots shown Verify your API credentials and endpoints are correct HubSpot booking fails Ensure your private app has all required scopes Authentication errors For custom APIs, verify your signature verification logic
