Verbai - AI Phone Receptionist

MVP1 Checklist & Testing Guide for Plumbing Companies

Complete Needs Testing Configuration Required

Live URL: https://verbai.forwardai.dev | Health: /health | Phone: +1 (606) 806-7965

Live System Status

Checking status...

1 Initial Configuration

⚙ Twilio Account Setup
▶

Setup Steps

  1. Go to Twilio Console
  2. Copy your Account SID from the dashboard
  3. Copy your Auth Token (click to reveal)
  4. Go to Phone Numbers → Buy a Number (or use existing)
  5. Ensure number has Voice and SMS capabilities

Update .env File

TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_PHONE_NUMBER=+15551234567

Current .env Location

/Users/sanju/Projects/verbai/.env
⚙ OpenAI API Setup
▶

Setup Steps

  1. Go to OpenAI API Keys
  2. Create a new API key
  3. Ensure your account has Realtime API access

Update .env File

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ Important

OpenAI Realtime API may require special access. If you get errors, check your OpenAI dashboard to ensure realtime features are enabled for your account.

⚙ ngrok Setup (Local Testing)
▶

Setup Steps

  1. Install ngrok: Download ngrok
  2. Run in a separate terminal:
ngrok http 3002

Configure Twilio Webhooks

In Twilio Console → Phone Numbers → Your Number:

Voice Webhookhttps://YOUR-NGROK-URL/webhook/voice
Voice MethodPOST
SMS Webhookhttps://YOUR-NGROK-URL/webhook/sms
SMS MethodPOST

2 Authentication System

✓ User Registration
▶

How to Test

curl -X POST http://localhost:3002/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "plumber@example.com",
    "password": "password123",
    "name": "John Plumber",
    "companyName": "Johns Plumbing Co"
  }'

Expected Response

{
  "user": { "id": "...", "email": "plumber@example.com", "name": "John Plumber" },
  "account": { "id": "...", "companyName": "Johns Plumbing Co" },
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

What to Confirm

  • Returns JWT token
  • User record created in database
  • Account record created with company name
  • Duplicate email returns error
✓ User Login
▶

How to Test

curl -X POST http://localhost:3002/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "plumber@example.com",
    "password": "password123"
  }'

What to Confirm

  • Returns JWT token on success
  • Invalid credentials return 401 error
  • Token can be used for authenticated endpoints

💡 Save Your Token

Copy the token from the response - you'll need it for testing other endpoints.

✓ Get Current User
▶

How to Test

curl http://localhost:3002/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

3 AI Voice Call System

✓ 1. AI Call Answering (English + Spanish)
▶

How to Test

  1. Ensure ngrok is running and Twilio webhooks are configured
  2. Call your Twilio phone number
  3. You should hear the recording disclaimer
  4. AI receptionist should greet you
  5. Have a conversation about a plumbing issue

What to Confirm

  • Recording disclaimer plays first
  • AI responds naturally to questions
  • Server logs show "New WebSocket connection"
  • Server logs show "Connected to OpenAI Realtime API"

Key Files

  • src/core/call-processor/index.ts - WebSocket bridge
  • src/lib/openai-realtime.ts - OpenAI client
  • src/modules/voice/twiml.builder.ts - TwiML responses
✓ 2. Call Recording Disclaimer
▶

How to Test

  1. Call your Twilio number
  2. Listen for: "This call may be recorded for quality assurance"
  3. This should play BEFORE the AI greeting
✓ 3. Emergency Detection + Safety Script
▶

How to Test

  1. Call your Twilio number
  2. Say: "I smell gas in my house"
  3. AI should immediately respond with safety instructions
  4. AI should tell you to evacuate and call 911

Emergency Keywords

Gas Leak"gas smell", "smell gas", "gas leak"
Flooding"flooding", "water everywhere", "burst pipe"
Sewage"sewage", "sewage backup", "toilet overflow"
No Water"no water", "water stopped"

What to Confirm

  • AI delivers safety instructions immediately
  • Call record shows isEmergency: true
  • Plumber receives SMS with "EMERGENCY" prefix

⚠️ Critical Safety Feature

Gas leak detection instructs callers to evacuate and call 911. This is critical safety behavior that must work correctly.

✓ 4. Standard Intake (Name, Phone, Address, Issue)
▶

How to Test

  1. Call your Twilio number
  2. Describe a non-emergency issue: "My faucet is leaking"
  3. AI should ask for your name
  4. AI should ask for callback number
  5. AI should ask for service address
  6. AI should confirm the details

What to Confirm

  • AI collects all required information
  • Call record contains customerName, customerPhone, customerAddress
  • Issue description is captured
✓ 9. Mid-Call Spanish Switching
▶

How to Test

  1. Call your Twilio number
  2. Start speaking in English
  3. Say: "Hola, ¿puedo hablar en español?"
  4. AI should switch to Spanish
  5. Continue conversation in Spanish

What to Confirm

  • AI responds in Spanish after trigger
  • Conversation continues smoothly
  • No call interruption during switch

4 Scheduling System

✓ 5. Scheduling with AM/PM Windows
▶

Time Windows

Morning (AM)8:00 AM - 12:00 PM
Afternoon (PM)12:00 PM - 5:00 PM
Max per Window5 appointments

Check Availability (API)

curl "http://localhost:3002/api/v1/appointments/availability?date=2024-12-28" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Appointment (API)

curl -X POST http://localhost:3002/api/v1/appointments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2024-12-28",
    "window": "AM",
    "customerName": "Jane Doe",
    "customerPhone": "+15551234567",
    "customerAddress": "123 Main St",
    "issueDescription": "Leaky faucet"
  }'

Via Phone Call

  1. Complete the intake process
  2. AI offers: "Would you prefer morning or afternoon?"
  3. Choose a time window
  4. AI confirms the appointment
✓ Block Dates
▶

Block a Date (API)

curl -X POST http://localhost:3002/api/v1/appointments/block \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"date": "2024-12-25", "reason": "Christmas"}'

5 SMS Coordination System

✓ 6. SMS Coordination with Plumber
▶

SMS Triggers

  • New Appointment: Plumber receives job details
  • Emergency: Immediate alert with "EMERGENCY" prefix
  • VIP Caller: Notes that caller is priority customer

How to Test

  1. Set plumber phone number in account settings
  2. Make a test call and complete intake
  3. Plumber should receive SMS with job details
✓ 8. Plumber SMS Commands
▶

Available Commands

CONFIRMAccept a pending job
BUSYMark as busy (pause new jobs)
AVAILABLEReady for new jobs
CLOSEDClosed for the day
STATUSGet current status & pending jobs
HELPList all commands

How to Test

  1. Ensure ngrok is running and SMS webhook configured
  2. Text HELP to your Twilio number
  3. You should receive a response listing commands
  4. Text STATUS to get current status

6 Priority Callers (VIP)

✓ 7. Priority Caller Behavior
▶

Add Priority Caller (API)

curl -X POST http://localhost:3002/api/v1/account/priority-callers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+15551234567",
    "name": "John Smith",
    "notes": "Regular customer, commercial account"
  }'

List Priority Callers

curl http://localhost:3002/api/v1/account/priority-callers \
  -H "Authorization: Bearer YOUR_TOKEN"

What to Confirm

  • Call from priority number → AI greets by name
  • Some intake questions skipped (info on file)
  • SMS to plumber notes "VIP Customer"

7 Admin Dashboard APIs

✓ Dashboard Summary
▶

Get Dashboard Data

curl http://localhost:3002/api/v1/account/dashboard \
  -H "Authorization: Bearer YOUR_TOKEN"
✓ Call Logs
▶

List Calls

curl http://localhost:3002/api/v1/calls \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Call Statistics

curl http://localhost:3002/api/v1/calls/stats \
  -H "Authorization: Bearer YOUR_TOKEN"
✓ Account Settings
▶

Get Account

curl http://localhost:3002/api/v1/account \
  -H "Authorization: Bearer YOUR_TOKEN"

Update Settings

curl -X PATCH http://localhost:3002/api/v1/account/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "businessHoursStart": "08:00",
    "businessHoursEnd": "17:00",
    "timezone": "America/Denver"
  }'

8 Database (PostgreSQL + Prisma)

✓ View Database
▶

Tables

AccountCompany accounts
AccountUserUsers linked to accounts
CallCall records with transcriptions
AppointmentScheduled appointments
PriorityCallerVIP phone numbers
SmsMessageSMS history
BlockedDateBlocked scheduling dates

View with Prisma Studio

cd /Users/sanju/Projects/verbai
npx prisma studio

Opens browser at http://localhost:5555

Quick Links

Verbai Dashboard
http://localhost:3002
Twilio Console
Phone & Webhooks
OpenAI Platform
API Keys & Usage

Current Environment

Serverhttp://localhost:3002
DatabasePostgreSQL (local, port 5432)
Redislocalhost:6379
Project Path/Users/sanju/Projects/verbai
.env File/Users/sanju/Projects/verbai/.env