Skip to main content
telli + Custom calendar integration

​
Overview

The custom calendar option lets you connect your existing calendar or appointment system with telli agents. Use this when you want telli to work with your own booking infrastructure instead of a built-in provider.

​
Before you start

  • A telli agent that should book appointments
  • An API endpoint to return available appointment slots
  • An API endpoint to book a selected appointment slot
  • Publicly reachable endpoints for telli to call

​
Set up a custom calendar in telli

1

Open the agent

Open the agent you want to configure in telli.
2

Choose Generic Calendar

In Calendar Integration, select Generic Calendar.
3

Add your endpoints

Provide the Available URL and, if telli should complete bookings, the Book URL for your scheduling API.
4

Save the agent

Save the agent so telli can request availability and book appointments through your endpoints.

​
Request flow

​
Endpoints

For full appointment scheduling, implement both endpoints below. If you only want telli to fetch availability, the booking endpoint can stay unset.

​
Get available slots

This endpoint returns a list of available appointment slots. 
POST /available

{
  "contact_id": "telli contact identifier",
  "external_contact_id": "your contact identifier",
  "contact_details": {
    "foobar": "baz"
  }
}

{
  "available": [
    {
      "start_iso": "2024-01-01T10:00:00.000",
      "end_iso": "2024-01-01T10:30:00.000"
    }
  ]
}

​
Book appointment

This endpoint handles the actual booking of a selected time slot. 
POST /book

{
  "contact_id": "telli contact identifier",
  "external_contact_id": "your contact identifier",
  "start_iso": "2024-01-01T10:00:00.000",
  "contact_details": {
    "foobar": "baz"
  }
}

{
  "status": "success"
}

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

​
Implementation notes

  • Use UTC timestamps in ISO 8601 format
  • telli uses start_iso as the slot identifier
  • Return HTTP 200 responses and indicate success or failure in the response body
  • Make sure telli can reach your endpoints

​
Request authentication

If you want to verify requests from telli, check the x-telli-signature header. 
const crypto = require("crypto");

function verifyRequest(payload, signature, apiKey) {
  const expectedSignature = crypto
    .createHmac("sha256", apiKey)
    .update(JSON.stringify(payload))
    .digest("hex");

  return signature === expectedSignature;
}