Appointment booking

Build a voice agent that collects what the caller wants, reads a Google Calendar for free time, offers two concrete slots, books the chosen one, and transfers to a person when booking is not what they need or the calendar fails. The example is Northside Dental, a practice on Asia/Kolkata. Substitute your own account, calendar address and numbers.

What you need


A Google account that owns the calendar being booked	Writes reach only calendars the connected account owns; a calendar merely shared with it is read-only
Dashboard access	Google Calendar connects over OAuth, which only the dashboard can start
Provider keys for OpenAI and Deepgram	See provider keys
A practice phone number to transfer to	Frozen into the published transfer tool
`TALQING_API_KEY` exported	A personal access token

Connect Google Calendar

In the dashboard, go to Integrations → Add integration → Google Calendar and sign in as the account that owns the calendar. Then read the integration id and the tools it exposes:

curl -sS https://api.talqing.com/v1/integrations \
  -H "Authorization: Bearer $TALQING_API_KEY" \
| jq '.items[] | select(.provider == "google_calendar") | {id, status, tools_namespace, allowed_tools}'

INTEGRATION=6a2c98f1-4b73-4e05-9d18-0c7f3a5b2e94

curl -sS "https://api.talqing.com/v1/integrations/$INTEGRATION/mcp-tools" \
  -H "Authorization: Bearer $TALQING_API_KEY" | jq '.tools[] | {name, exposed_name}'

Nine tools come back, all approved on a fresh connection. See Google Calendar for each one’s arguments.

Approve only the tools this agent needs

Booking on the account’s primary calendar needs two: suggest_time to find free periods and create_event to write the appointment. Every approved tool is described to the model on every turn, so fewer tools means fewer input tokens and fewer wrong choices. Shorten the namespace too, so the model sees calendar_suggest_time instead of google_calendar_suggest_time:

curl -sS -X PATCH "https://api.talqing.com/v1/integrations/$INTEGRATION" \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_tools": ["suggest_time", "create_event"], "tools_namespace": "calendar"}'

allowed_tools takes the tool’s own name (create_event), never the exposed one.
The prompt must use the exposed name (calendar_create_event).
allowed_tools replaces the list wholesale and applies to every agent attached to the integration on its next turn, without a republish.

See MCP servers.

Create the two tools of your own

record_booking writes the booked appointment into userdata, so it is readable for the rest of the call, stored on the call record, and visible to post-call analysis as an unambiguous tool call:

curl -sS https://api.talqing.com/v1/tools \
  -H "Authorization: Bearer $TALQING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "record_booking",
    "description": "Save the appointment you have just booked. Call it immediately after calendar_create_event has come back successfully, and never before or instead. Do not call it if the booking failed or if the patient has not confirmed a time.",
    "json_schema": {
      "type": "object",
      "properties": {
        "starts_at": {
          "type": "string",
          "description": "The start of the appointment as a full ISO 8601 timestamp, for example 2026-09-14T15:30:00+05:30. Copy it from the arguments you sent to calendar_create_event."
        },
        "service": {
          "type": "string",
          "description": "What the appointment is for, in a few words, for example \"cleaning\"."
        },
        "patient_name": {
          "type": "string",
          "description": "The full name the patient gave for the appointment."
        },
        "event_id": {
          "type": "string",
          "description": "The id of the event calendar_create_event created. Copy it exactly from that tool result."
        }
      },
      "required": ["starts_at", "service", "patient_name", "event_id"]
    },
    "operations": [
      { "kind": "set_variable", "config": { "key": "booking_starts_at", "value": "{{args.starts_at}}", "store": "userdata" } },
      { "kind": "set_variable", "config": { "key": "booking_service", "value": "{{args.service}}", "store": "userdata" } },
      { "kind": "set_variable", "config": { "key": "booking_patient_name", "value": "{{args.patient_name}}", "store": "userdata" } },
      { "kind": "set_variable", "config": { "key": "booking_event_id", "value": "{{args.event_id}}", "store": "userdata" } }
    ]
  }'

No operation returns a result, so the tool is silent: the agent says nothing extra after it.transfer_to_reception reaches a person. Its description is the escalation policy:

{
  "name": "transfer_to_reception",
  "description": "Put the caller through to a person at the practice. Use it when the caller asks for a person, wants to move or cancel an existing appointment, is in pain and needs to be seen today, asks about a bill or treatment plan, or a calendar tool has failed. Do not use it because a first choice of time was unavailable - offer another time first.",
  "json_schema": {},
  "disable_interruptions": true,
  "operations": [
    { "kind": "say", "config": { "text": "Let me put you through to the practice now, one moment." } },
    {
      "kind": "transfer",
      "config": { "destination": "+912261204455", "mode": "cold", "ringing_timeout": 30, "on_failure": "continue" }
    }
  ]
}

POST it to /v1/tools the same way. Publish both (POST /v1/tools/{tool_id}/publish) — an unpublished tool cannot be attached. See transfer.

Write the prompt

Save as reception-prompt.txt:

You are the receptionist for Northside Dental, a two-chair dental practice.
You book appointments for patients who call.

THE CLOCK
Right now it is {{system_vars.time}} on {{system_vars.date}}; the exact moment
is {{system_vars.now}}. The practice runs on Asia/Kolkata. Work out "tomorrow"
or "next Tuesday" from that date. Never ask the patient today's date.

BEFORE YOU TOUCH THE CALENDAR
Collect, one question at a time: the patient's full name, what the
appointment is for, and roughly when they want it (day, and morning or
afternoon). Do not call a calendar tool until you have all three.

HOW LONG THINGS TAKE
A check-up or cleaning is 30 minutes. A filling, an extraction or a first
visit is 60 minutes. If unsure, use 60.

FINDING TIMES
Say "let me look at the diary, one moment", then call calendar_suggest_time
with:
- attendeeEmails: {{vars.clinic_email}} and nothing else
- startTime and endTime: the window the patient asked for, as ISO 8601
  timestamps, never earlier than now
- timeZone: Asia/Kolkata
- durationMinutes: the length above
- preferences: startHour "09:30", endHour "18:00", excludeWeekends true

It returns free periods, not slots. Pick at most two start times inside them,
at least two hours apart, and offer only those. Never read out a list or a
period. If nothing comes back, offer the next window yourself.

BOOKING
When the patient picks a time, read the day, time and service back and wait
for a yes. Then say "booking that in now" and call calendar_create_event with:
- summary: service, then name - "Cleaning - Anita Rao"
- startTime and endTime: the exact slot as ISO 8601 timestamps
- timeZone: Asia/Kolkata
- description: the caller's number, {{system_vars.human_phone_number}}
- no attendees and no calendarId
When it succeeds, call record_booking, then confirm the day and time once more.

WHEN THE CALENDAR FAILS
If a calendar tool returns an error, do not retry and do not pretend it
worked. Say the diary is not responding and offer to put them through.

SPEAKING
- Two or three sentences per turn, one question per turn.
- No markdown, lists, emoji or JSON.
- Dates as "Thursday the ninth of April"; times as "half past ten in the
  morning". Never read a timestamp aloud.

The clock tokens resolve in config.timezone and are a save error without it; in a prompt they are fixed when the call is answered. {{system_vars.now}} is a machine timestamp for building arguments. See variables.

Calendar rules the prompt relies on

Rule	Consequence
A `startTime`/`endTime` needs a UTC offset or a `timeZone`	Without either, the tool refuses the call. Passing `timeZone` every time also overrides an offset the model got wrong
`suggest_time` returns free periods, not slots	Choosing offerable start times is the model’s job
A calendar `suggest_time` cannot read is listed in `unreadableCalendars`	Treat it as unknown, not free
Writes reach only calendars the account owns	Otherwise `403`/`404`
`notificationLevel` defaults to `NONE` when there are no attendees	The booking above emails nobody

Create and publish the agent

Save the config as reception-agent.json, with your integration id and the two tool ids:

{
  "config": {
    "name": "Northside Dental reception",
    "channel": "voice",
    "language": "en",
    "timezone": "Asia/Kolkata",
    "greeting": {"message": "Northside Dental, would you like to book an appointment?"},
    "stt": { "provider": "deepgram", "model": "nova-3-general" },
    "llm": { "provider": "openai", "model": "gpt-5.4-mini" },
    "tts": { "provider": "deepgram", "model": "aura-2", "voice": "aura-2-thalia-en" },
    "vars": [
      {
        "name": "clinic_email",
        "description": "The Google account whose free/busy the agent books against.",
        "default": "reception@northside-dental.example"
      }
    ],
    "mcps": [{ "integration_id": "6a2c98f1-4b73-4e05-9d18-0c7f3a5b2e94" }],
    "tools": [
      { "tool_id": "0c5e39a7-1f84-4b26-8d93-72a0e5c14b68" },
      { "tool_id": "b7d24f10-9c36-4a58-8e01-3f6b5d072a9c" }
    ],
    "analysis": {
      "enabled": true,
      "summary": true,
      "outcome": {
        "prompt": "Success: an appointment was created and the agent read the day and time back. Anything else - no time suited, the calendar failed, the caller was transferred - is a failure."
      },
      "fields": [
        { "name": "appointment_at", "type": "string", "description": "Start of the booked appointment as YYYY-MM-DD HH:MM local time, from the record_booking call. Null if nothing was booked." },
        { "name": "service", "type": "string", "description": "What the caller booked for, in a few words. Null if they never said." },
        { "name": "not_booked_reason", "type": "string", "description": "If nothing was booked, why, in a few words - e.g. \"no time suited\", \"calendar error\", \"asked for a person\". Null if booked." }
      ]
    }
  }
}

Fold in the prompt, create, validate and publish:

AGENT=$(jq --rawfile prompt reception-prompt.txt '.config.prompt = $prompt' reception-agent.json \
  | curl -sS https://api.talqing.com/v1/agents \
      -H "Authorization: Bearer $TALQING_API_KEY" \
      -H "Content-Type: application/json" \
      --data @- | jq -r .id)

curl -sS -X POST "https://api.talqing.com/v1/agents/$AGENT/validate" \
  -H "Authorization: Bearer $TALQING_API_KEY"

curl -sS -X POST "https://api.talqing.com/v1/agents/$AGENT/publish" \
  -H "Authorization: Bearer $TALQING_API_KEY"

import { readFileSync } from "node:fs";
import { TalqingClient } from "@talqing/sdk";

const talqing = new TalqingClient({
  baseUrl: "https://api.talqing.com",
  token: process.env.TALQING_API_KEY,
});

const body = JSON.parse(readFileSync("reception-agent.json", "utf8"));
body.config.prompt = readFileSync("reception-prompt.txt", "utf8");

const agent = await talqing.agents.create({ createAgentRequest: body });
const check = await talqing.agents.validate({ agent_id: agent.id });
if (check.errors.length) throw new Error(check.errors.join("\n"));
await talqing.agents.publish({ agent_id: agent.id });

import json
from pathlib import Path

from talqing import Talqing

config = json.loads(Path("reception-agent.json").read_text())["config"]
config["prompt"] = Path("reception-prompt.txt").read_text()

with Talqing.from_env(base_url="https://api.talqing.com") as talqing:
    agent = talqing.agents.create(config=config)
    check = talqing.agents.validate(agent["id"])
    if check["errors"]:
        raise SystemExit("\n".join(check["errors"]))
    talqing.agents.publish(agent["id"])

mcps is part of the published version: the calendar tools reach calls only after you publish. allowed_tools on the integration is live.
clinic_email has a default because an inbound call supplies no vars. A required var without a default makes assigning the agent to a number fail. See variables.

To answer a phone line, assign the agent to a number as in phone numbers.

Test it

Book something, then check the calendar. Use the agent editor’s test panel (it runs the latest published version): give a name, a reason, “sometime Thursday morning”, and accept the first slot. In Google Calendar, confirm:

The event is at the time the agent said aloud. An hour off means a missing timeZone.
The title is service and name.
The duration matches the prompt.

Read the call. GET /v1/calls/{session_id} returns:

the function_call items for calendar_suggest_time and calendar_create_event, with the arguments the model chose;
session.userdata with the four booking_* keys;
session.analysis once the call ends, with appointment_at matching the calendar.

A web test call cannot exercise the transfer (transfer is phone-only), and {{system_vars.human_phone_number}} is empty there, so the event description is blank. Test the failure path too: disable the integration and confirm the agent offers a person instead of claiming a booking.

What to watch in the first week

Offers, not lists. Read the turn after calendar_suggest_time in a few transcripts. Two concrete times is the target; anything longer is a prompt fix.
Calls with no booking. GET /v1/calls?outcome=failure, then group not_booked_reason. “No time suited” means the preferred hours are wrong; “calendar error” means read the tool results.
What the voice says. Listen to a few recordings: dates and times read wrongly are fixed in the SPEAKING section.

Limits of this setup

No confirmation message. There is no SMS, and with no attendees Google emails nobody. Add the caller as an attendee (they must spell an email aloud), or post the booking to your own system from an http tool.
No rescheduling or cancelling. That needs search_events plus update_event/delete_event approved and prompted for. An eventId from a search names one occurrence of a recurring event, not the series.
Two concurrent callers can be offered the same slot. suggest_time reads free/busy when it runs and nothing holds the slot until create_event; Google accepts both bookings. If double-booking is unacceptable, book through a system of yours that can hold a slot, from an http tool.
suggest_time takes at most 50 addresses, and calendars Google will not share come back as unreadable.

Google Calendar

All nine native tools, argument by argument.

Call analysis

Tune the extraction against a finished call.

Phone numbers

Put the agent on a number.

Get started

Build

Guides

Appointment booking

What you need

Calendar rules the prompt relies on

Test it

What to watch in the first week

Limits of this setup

Next

Google Calendar

Call analysis

Phone numbers

​What you need

​Calendar rules the prompt relies on

​Test it

​What to watch in the first week

​Limits of this setup

​Next

Google Calendar

Call analysis

Phone numbers

What you need

Calendar rules the prompt relies on

Test it

What to watch in the first week

Limits of this setup

Next