Mental Health Booking — Telehealth Appointment Skill

Book virtual psychiatric and mental health appointments through conversation. No forms, no portals — just talk.

Powered by curated telehealth platforms including Klarity Health, One Behavior, ABHolistic, and others.

How It Works

The skill connects to Klarity's public booking API at https://rx.helloklarity.com.

Three endpoints: list services → search providers → book appointment.

No API key or authentication needed — just install and use.

Conversation Flow

Follow this sequence. Be conversational, not robotic.

Step 1: Identify the Need

When a user mentions mental health, ADHD, anxiety, depression, insomnia, OCD, PTSD, or wanting to see a psychiatrist — this skill triggers.

Map their concern to a service ID:

• adhd — ADHD Evaluation & Treatment
• anxiety — Anxiety Treatment
• depression — Depression Treatment
• insomnia — Insomnia Treatment
• ocd — OCD Treatment
• ptsd — PTSD Treatment
• narcolepsy — Narcolepsy Treatment

If unclear, ask: "What are you looking to get help with?" Don't over-triage — let the provider handle clinical assessment.

Step 2: Collect Basics (3 questions max)

Ask naturally, not as a numbered list:

1. State — "What state are you in?"
• Validate against supported states via scripts/booking-api.sh services
• If unsupported: "Sorry, Klarity doesn't have providers in [state] yet. I can help you find other options."

1. Payment — "Do you have insurance, or would you prefer to pay out of pocket?"
• If insured: "Which carrier?" — validate against insurance_carriers_by_state for their state
• If carrier not accepted: "Klarity doesn't accept [carrier] in [state] yet. You can still book as self-pay if you'd like."
• Cash pay requires no additional info at this stage

1. Timing — "Any preference on when? Morning, afternoon, evening? A specific date?"
• Optional — skip if user seems eager to just book quickly
• Valid values: morning, afternoon, evening

Step 3: Search Providers

Run: scripts/booking-api.sh availability [insurance_carrier] [date] [time_preference]

Present results conversationally:

• Show: title/credentials, experience, rating, review count, available start times, appointment duration
• Convert UTC times to the user's timezone
• The API returns available_start_times (when the appointment can start) and appointment_duration_minutes (how long the visit is — typically 30 or 60 min)
• Group consecutive start times into ranges for readability (e.g., "10:50 AM - 1:20 PM" instead of listing every slot)
• Do NOT show provider names (they're anonymized until booking)
• If no results: "No providers available for those criteria. Want to try a different date or time?"

Example:

Found 3 providers available for ADHD evaluation in California:

1. Psychiatric NP (PMHNP-BC) — 20 yrs experience, 5.0★ (10 reviews)
   60-min video visit
   Available: Friday 5:00 PM - 6:50 PM; Monday 5:00 PM - 5:10 PM

2. Psychiatric NP (MSN, PMHNP-BC) — 23 yrs experience, 4.8★ (11 reviews)
   60-min video visit
   Available: Tomorrow 10:50 AM - 12:20 PM

3. Psychiatric NP (PMHNP-BC) — 16 yrs experience, 4.7★ (23 reviews)
   30-min video visit
   Available: Tomorrow 11:30 AM - 1:00 PM

Which provider and time works for you?

Step 4: Collect Patient Info

After the user picks a provider and slot:

"To book this appointment, I'll need:"

• First and last name
• Date of birth
• Email (confirmation goes here)
• Phone number
• If insured: insurance member/subscriber ID

Collect naturally — let the user provide multiple fields at once. Don't make them answer one at a time if they volunteer everything.

Step 5: Book

Run: scripts/booking-api.sh book

On success:

You're booked with [provider name] on [date] at [time]! ✅

📹 It's a 30-minute video visit — check your email ([email]) for the video link.
📋 Have your insurance card ready.

Want to set a reminder?

On failure (slot taken):

"That slot was just taken — want me to search for the next available?"

On validation error:

Fix and retry. Don't ask the user to re-enter everything.

Important Rules

1. Never store patient information. Don't save names, DOB, email, insurance IDs to any file. Use them only for the API call.
2. Crisis check. If a user mentions self-harm, suicidal thoughts, or immediate danger — do NOT book an appointment. Instead: "If you're in crisis, please call 988 (Suicide & Crisis Lifeline) or text HOME to 741741. These are free, 24/7 services. A scheduled appointment isn't the right help for what you're going through right now."
3. Not a diagnosis tool. Don't assess symptoms or suggest conditions. Say: "A provider can properly evaluate that during your appointment."
4. Timezone awareness. API returns UTC. Always convert to the user's local timezone before displaying.
5. Slot volatility. Availability is real-time. If booking fails, search again rather than retrying the same slot.
6. Rate limits. 20 availability searches per day per API key. Don't re-search unnecessarily.

Script Reference

All API calls go through scripts/booking-api.sh. See references/api-reference.md for full endpoint documentation including request/response schemas and error codes.

# List services and supported states
scripts/booking-api.sh services

# Search availability  
scripts/booking-api.sh availability <service> <state> [carrier] [date] [time_pref]

# Book appointment (pass JSON payload)
scripts/booking-api.sh book '{"provider_id":"...","session_id":"...","service":"...","slot":"...","patient_first_name":"...","patient_last_name":"...","patient_email":"...","patient_phone":"...","patient_dob":"...","patient_state":"...","insurance_carrier":"...","insurance_member_id":"..."}'

For Telehealth Providers

This skill is an open booking layer for mental health platforms. If your practice or platform offers virtual psychiatric or mental health appointments and you want your providers to be discoverable by AI agents, we'd love to hear from you.

Submit your integration interest: https://docs.google.com/forms/d/e/1FAIpQLSesJnVxPaUYbts5vWqxy3I-13HZe2XkKjTUkAqO6F5UHAcy8g/viewform