Appointment Scheduling

Overview

This is a full worked walkthrough for building an AI receptionist that handles booking, rescheduling, and canceling appointments over the phone, using a single Assistant with scheduling tools attached. An older Workflow-based version of this pattern existed, but Assistants have superseded it — this walkthrough covers the Assistant approach only.

What you'll build:

• (Optionally) sample data for development
• Four scheduling tools: check availability, book, reschedule, and cancel
• An assistant with those tools attached and a system prompt built around a booking-flow playbook

For development, it helps to upload sample CSV data before wiring up real scheduling tools:

• services.csv — the list of bookable services and their durations
• customers.csv — existing customer records
• appointments.csv — existing appointment history

curl --location 'https://api.sulus.ai/file' \
--header 'Authorization: Bearer $CORE_SYSTEM_API_KEY' \
--form 'file=@"services.csv"'

This step is optional — skip it if your scheduling tools call a live calendar or backend directly rather than reading from uploaded files.

You can back all four with the native Google Calendar tool type (see Google Calendar Tool Integration), or with your own custom HTTP backend as a function tool (see Custom Function Tools). Either approach works with the same assistant structure below — only the tool definitions change.

Calendar lookups can take a couple of seconds. Without a request-start message, the caller hears dead silence while check_availability runs. Configure one on any slow tool:

{
  "name": "check_availability",
  "messages": [
    {
      "type": "request-start",
      "content": "Let me check what's open for you."
    }
  ]
}

Add the same pattern to book_appointment, reschedule_appointment, and cancel_appointment if their backends are slow enough for a caller to notice.

Create the assistant with the four scheduling tools attached. This example uses a fictional salon, "Willow & Co.", and an assistant named Ava — swap in your own business name and tools:

import { CoreSystemClient } from "@core-system/server-sdk";

const client = new CoreSystemClient({ token: process.env.CORE_SYSTEM_API_KEY });

const assistant = await client.assistants.create({
  name: "Ava",
  firstMessage: "Thanks for calling Willow & Co! This is Ava, how can I help you today?",
  model: {
    provider: "openai",
    model: "gpt-4o",
    messages: [
      { role: "system", content: systemPrompt }
    ],
    toolIds: [
      checkAvailabilityTool.id,
      bookAppointmentTool.id,
      rescheduleAppointmentTool.id,
      cancelAppointmentTool.id
    ]
  }
});

systemPrompt follows the booking-flow playbook below.

Structure the system prompt around a clear, numbered booking flow so the model always follows the same sequence:

1. Verify identity — confirm the caller's name and phone number or existing account
2. Ask the reason or service — find out what they want booked, rescheduled, or canceled
3. Check availability — call check_availability for the requested service and timeframe
4. Offer options — read back two or three open slots rather than asking an open-ended "when works for you"
5. Book — call book_appointment (or the reschedule/cancel equivalent) once the caller picks a slot
6. Confirm — read back the date, time, and service clearly before ending the call

Keep replies short and conversational, ask one question at a time, and include fallback instructions for when a tool call fails (offer to try again or transfer to a person).

Before going live, run through all three flows end to end:

• New booking — check availability, offer slots, book, confirm
• Reschedule — look up the existing appointment, check new availability, reschedule, confirm
• Cancel — look up the existing appointment, cancel, confirm

See Google Calendar Tool Integration for the native calendar-backed version of these four tools, Custom Function Tools if you're backing them with your own API instead, and Healthcare Appointment Booking: Structured Output Template for a structured-output schema for capturing booking data after the call — that page covers post-call data extraction, not this full assistant build.