Connect the AI Chat Receptionist with ServiceTitan

By connecting the AI Chat Receptionist with ServiceTitan, your AI Receptionist can access customer information, schedule appointments, and manage service requests in your ServiceTitan account.

In this guide, you will set up your AI Receptionist to be able to:

• Look up customer information and service history;
• Schedule new appointments and service calls;
• Check technician availability and capacity;
• Create and update jobs in ServiceTitan;
• Retrieve real-time job status and updates; and
• Access customer billing and invoice information.

Why is connecting the AI Receptionist with ServiceTitan important?

ServiceTitan is a software platform used by many trades businesses (HVAC, plumbing, electrical, and other home services). When customers contact your business, they often need help with scheduling, job updates, or service history. This integration lets your AI Receptionist read and update data in ServiceTitan, such as customers, jobs, appointments, and related records.

Prerequisites & Setup

Before you connect your AI Receptionist to ServiceTitan, gather the following from your ServiceTitan account. You’ll only need to do this once.

ServiceTitan Help Resources

• Setting up API access (ServiceTitan Developer Portal)
• Managing integrations (API Application Access Guide)
• Understanding API permissions (ServiceTitan API Documentation)

Capability 1: Customer Lookup and Service History

This capability allows your AI Receptionist to search for customers and retrieve their service history, providing instant access to past jobs, upcoming appointments, and customer preferences.

Step 1: Add a ServiceTitan Customer Lookup Capability

1. In Command Hub, navigate to AI → AI Workforce
2. Select your AI Employee and click Configure.
3. Under Custom Capabilities, click Add a capability.

Name: ServiceTitan Customer Lookup
Description: Searches ServiceTitan for customer information, service history, and account details to provide personalized support and context for customer inquiries.

Step 2: Configure ServiceTitan Customer API Tools

ServiceTitan Tool: searchCustomers

searchCustomers allows your AI Receptionist to find customers by name, phone number, or email address and retrieve basic customer information.

Required headers

Query parameters

ServiceTitan Tool: getCustomerJobs

getCustomerJobs retrieves the complete job history for a specific customer.

Required headers

Query parameters

ServiceTitan Tool: createCustomer

createCustomer creates a new customer record in ServiceTitan when they don't already exist.

Required headers

Body parameters

Step 3: Write the Customer Lookup Prompt

Customer Information Lookup Instructions

When to Search Customer Information

• When customer provides name/phone/email and asks about their account
• When asking about service history, past appointments, upcoming services, billing/invoices
• When identity verification is needed before sharing account details

Do not search for general questions about services, pricing, or policies.

Customer Search Process

1. Search for Customer: Use most specific identifier (phone best). If multiple matches, ask for more info.
2. Handle Status: If found, retrieve job history & upcoming appointments; if not, prepare to create new record.
3. Retrieve Service History: With customer ID, get job history, note patterns and upcoming work.

Response Guidelines

When found: Greet by name, share relevant history/appointments, offer scheduling help.

When not found: Welcome as new, explain creation during booking, gather name/phone/email/address, then use createCustomer.

Collect for new customer: Full name, phone, email, service address, special instructions.

Security: Verify identity; never share sensitive info.

Example Responses

Existing: “Hi [Customer Name]! I found your account… How can I help you today?”
New: “Welcome! I don’t see an existing account… I can set up your account and schedule your service.”

Capability 2: Appointment Scheduling and Job Creation

This capability enables your AI Receptionist to schedule new appointments, create service jobs in ServiceTitan, and manage the booking process end-to-end.

Step 1: Add a ServiceTitan Appointment Scheduling Capability

Name: ServiceTitan Appointment Scheduling
Description: Creates new appointments and service jobs in ServiceTitan, checks technician availability, and manages the complete booking workflow.

Step 2: Configure ServiceTitan Scheduling API Tools

ServiceTitan Tool: getAvailableTimeSlots

Checks technician availability and capacity to find open appointment slots.

Required headers

Query parameters

ServiceTitan Tool: createAppointment

Creates a new appointment and job in ServiceTitan.

Required headers

Body parameters

Step 3: Write the Appointment Scheduling Prompt

Appointment Scheduling Instructions

When to Schedule Appointments

• Customer requests service (HVAC/plumbing/electrical/etc.)
• Maintenance/inspection/consultation
• Emergency that can wait for next available
• Follow-up or warranty work

Scheduling Process

1. Identify Customer: Search; create new if not found.
2. Gather Info: Contact info, service address, job type, problem, preferred time/date, urgency.
3. Check Availability: Find slots by job type/skills; offer options.
4. Create Appointment: Create job, set priority, add summary, link customer ID.

Service Type Guidelines

• HVAC: Repairs, tune-ups, installs, emergency no-heat/no-cool
• Plumbing: Leaks, drains, fixtures, emergency issues
• Electrical: Outlets, panels, lighting, emergencies
• General Maintenance: Inspections, preventive, warranty, follow-ups

Appointment Confirmation

• Provide job number, date/time, duration, technician (if known), contact for changes, prep instructions

Example

“I’ve scheduled your HVAC maintenance for [Date] at [Time]. Job #[Job#]… You’ll receive a confirmation call the day before.”

Capability 3: Job Status and Updates

This capability allows your AI Receptionist to provide real-time updates on job status, technician location, and estimated arrival times.

Step 1: Add a ServiceTitan Job Status Capability

Name: ServiceTitan Job Status Updates
Description: Retrieves real-time job status, technician location, and appointment updates from ServiceTitan.

Step 2: Configure ServiceTitan Job Status API Tools

ServiceTitan Tool: getJobStatus

Required headers

Path parameters

ServiceTitan Tool: getTechnicianLocation

Provides technician location and ETA (requires ServiceTitan Mobile).

Step 3: Write the Job Status Prompt

Job Status and Updates Instructions

When to Check

• Customer asks about scheduled appointment, ETA, progress, delays, or references job number

Status Update Process

1. Identify job: Ask for job #, date, or address; verify correct appointment.
2. Retrieve current status: Check latest updates and technician assignment.
3. Provide clear updates: Translate to customer-friendly language and next steps.

Job Status Translations

• Scheduled → “Your appointment is confirmed and scheduled.”
• Dispatched → “A technician has been assigned and is on the way.”
• InProgress → “Your technician has arrived and is working.”
• Completed → “Your service has been completed.”
• OnHold → “Your appointment is temporarily on hold.”
• Cancelled → “Your appointment has been cancelled.”

Providing Helpful Context

• Scheduled: Mention window, technician (if assigned), prep instructions.
• Active: Estimated completion, discovered issues, technician contact.
• Completed: Confirm completion, follow-up, invoice/billing on request.

Example Status Updates

Scheduled: “Your HVAC maintenance is confirmed for tomorrow 9–11 AM… John Smith will call ~30 minutes prior.”
In Progress: “Technician arrived at 2:15 PM and expects to finish within the hour.”
Completed: “Your electrical repair was completed at 11:30 AM… invoice sent via email.”

Example conversations with AI Receptionist connected to ServiceTitan

Example 1: Existing Customer Scheduling Maintenance

User: “Schedule HVAC maintenance next week?”
AI: “Happy to help—what’s your name and phone?” … (lookup) … “Found your account. Available: Tue 9–11 or 2–4; Wed 10–12 or 1–3; Fri 8–10. Which works?”
User: “Tue 2 PM.”
AI: “Booked Tue, Mar 14, 2–4 PM. Job #ST-847392… Tech Mike Rodriguez… You’ll get a confirmation email and reminder.”

Example 2: New Customer Requesting Service

User: “Kitchen sink is leaking—need a plumber this week.”
AI gathers name/phone, doesn’t find account → creates customer, checks availability, proposes slots.
User selects Wed 10 AM → AI books: Job #ST-847401, service details, prep instructions, confirmation email.

Testing & Troubleshooting

This section helps diagnose common issues (authentication, permissions, limits, empty results).

Authentication Error (401)

What is this? 401 Unauthorized — e.g. {"error":"invalid_token","error_description":"The access token is invalid"}

Fix: Verify Client ID/Secret, ensure token not expired, correct tenant ID, test in Postman with same credentials.

FAQ: Connecting the AI Receptionist with ServiceTitan

© Command Local — Command Hub Docs