Skip to main content

AI Scheduling

Let callers book appointments over the phone without talking to a human. DialStack handles the voice conversation — greeting, slot negotiation, callback collection — and calls your system to read availability and write the booking.

AI Scheduling is powered by the AI Agents API. Each AI agent auto-provisions a voice app and an extension, has a configurable persona and FAQ, and optionally hands off call handling to your scheduling endpoints.

What you build​

Three HTTPS endpoints under a base URL you give us:

PathPurpose
POST {base}/customers/lookupMatch the caller's phone number to an existing customer record (optional — used to personalize the greeting).
POST {base}/availability/searchReturn open slots for a requested date.
POST {base}/bookingsCreate a booking for the slot the caller picked.

DialStack relays each request synchronously: your response shape is what the AI presents to the caller. Full request / response payload definitions: Appointment Webhooks.

Create the agent​

Configure the agent once via POST /v1/ai-agents. Point scheduling.webhook_url at the base URL that hosts the three paths above.

curl -X POST https://api.dialstack.ai/v1/ai-agents \
  -H 'Authorization: Bearer sk_live_YOUR_KEY' \
  -H 'DialStack-Account: acct_01h2xcejqtf2nbrexx3vqjhp41' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Front Desk Receptionist",
    "extension_number": "200",
    "persona_name": "Tony",
    "greeting_name": "Jones Family Dental",
    "instructions": "You are the receptionist. Be warm and professional. Offer to book an appointment if the caller does not specify a reason.",
    "faq_responses": [
      { "question": "What are your business hours?", "answer": "We are open Monday through Friday, 9 AM to 5 PM." },
      { "question": "Do you take walk-ins?", "answer": "Walk-ins are welcome, but appointments are prioritized." }
    ],
    "scheduling": {
      "webhook_url": "https://api.clinic.io/dialstack"
    }
  }'

The response includes id (aia_...) and voice_app_id — the voice app is managed automatically. Extension 200 now routes callers to the agent.

How a booking call plays out​

The AI handles disambiguation ("which Tuesday?"), date math, and re-prompting. You only see the clean, resolved request.

Route calls to the agent​

Drop the agent into any dial plan via its auto-managed extension — point an internal_dial node at the agent's voice app:

{
  id: 'ai_receptionist',
  type: 'internal_dial',
  config: { target_id: 'va_01h2xcejqtf2nbrexx3vqjhp49' }, // from voice_app_id
}

Typical patterns:

  • After-hours fallback — schedule node → ring_all_users during business hours, internal_dial to the agent when closed.
  • Overflow — ring_all_users with a short timeout, next pointing at the agent when no one picks up.
  • Direct line — an inbound number routed straight at the agent for a 24/7 booking line.

The landing hero shows all three patterns in one dial plan.

Customizing the agent at call time​

Agent config (persona, instructions, FAQs, scheduling URL) can be updated via POST /v1/ai-agents/{id}. Changes take effect on the next call.

Per-call overrides (account-specific context, time-sensitive promotions) are applied on your side when the AI calls /customers/lookup — the response shape carries arbitrary metadata that the agent uses in the conversation.

See also​