Connect your calendar - telli API Documentation

Overview
Supported Providers

When you connect a calendar, your voice AI agent can:

Check availability — See open time slots in real-time during calls
Book appointments — Schedule meetings without any manual intervention
Collect 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 users
Cal.com — For Cal.com users
HubSpot — For HubSpot Meetings users
Generic 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

Open your agent in telli

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

Click Save

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

Open your agent in telli

Go to Calendar Integration → select Cal.com

Enter your Cal.com API key

Enter the event type slug

Click Save

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

Open your agent in telli

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

Click Save

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.write
- crm.schemas.contacts.write
- scheduler.meetings.meeting-link.read
- tickets
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

Open your agent in telli

Go to Calendar Integration → select Generic Calendar

Enter your Available Slots URL (required)

Enter your Book Appointment URL (optional — leave blank for availability-only)

Click Save

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

API Specification

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:

{
  "status": "success"
}

Failure Response:

{
  "status": "failed",
  "reason": "Appointment slot is no longer available"
}

Authentication

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.

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

How to Prompt

​Getting Started

​Provider Setup

​Fields Required

​Booking Fields

​Setup Steps

​Finding Your Event Type URI

​Fields Required

​Setup Steps

​Finding Your Event Type

​Fields Required

​Setup Steps

​Finding Your Meeting Link Slug

​Creating a HubSpot Private App

​Fields Required

​Setup Steps

​Implementation Notes

​Get Available Slots

​Book Appointment

Getting Started

Provider Setup

Fields Required

Booking Fields

Setup Steps

Finding Your Event Type URI

Fields Required

Setup Steps

Finding Your Event Type

Fields Required

Setup Steps

Finding Your Meeting Link Slug

Creating a HubSpot Private App

Fields Required

Setup Steps

Implementation Notes

Get Available Slots

Book Appointment