# Setup Guide

## 1. Create accounts

You need:

- Twilio account
- OpenAI API key
- Email provider: SMTP or SendGrid
- Hosting provider: Render, Railway, Fly.io, DigitalOcean, VPS, or local ngrok for testing

## 2. Buy or configure a Twilio phone number

Buy a Twilio number that supports Voice and SMS.

In Twilio Console, configure:

### Voice webhook

When a call comes in:

```text
POST https://YOUR_PUBLIC_URL/voice/incoming
```

### Messaging webhook

When a message comes in:

```text
POST https://YOUR_PUBLIC_URL/sms/incoming
```

## 3. Configure `.env`

Copy `.env.example` to `.env` and fill out:

- `CLIENT_BUSINESS_NAME`
- `OWNER_PHONE`
- `OWNER_EMAIL`
- `BUSINESS_PHONE`
- `TWILIO_ACCOUNT_SID`
- `TWILIO_AUTH_TOKEN`
- `TWILIO_PHONE_NUMBER`
- `OPENAI_API_KEY`
- Email settings

## 4. Choose call behavior

### Mode A: missed-call only

```text
AFTER_HOURS_MODE=missed_only
```

This forwards every call to the business phone first. If no one answers, it sends the recovery SMS.

### Mode B: instant after-hours

```text
AFTER_HOURS_MODE=instant_after_hours
```

During business hours, calls forward to the business. After hours, the system immediately sends the recovery SMS and tells the caller to check their phone.

## 5. Initialize database

```bash
npm install
npm run init-db
npm start
```

## 6. Test with ngrok

```bash
ngrok http 3000
```

Use the ngrok HTTPS URL for Twilio webhooks.

## 7. Test call flow

Call the Twilio number.

Expected flow:

1. Twilio receives the call.
2. App forwards the call to `BUSINESS_PHONE`.
3. If unanswered, caller receives a text.
4. Caller replies with pest problem.
5. AI asks only for missing details.
6. Owner receives lead alert when the lead is qualified.

## 8. Client handoff checklist

Before going live:

- Confirm business name and service areas.
- Confirm office phone and owner phone.
- Confirm business hours.
- Confirm booking link or quote process.
- Confirm SMS opt-out language.
- Confirm who receives lead alerts.
- Run 3 test calls and 3 test text conversations.

## HostKoala / cPanel deployment

For HostKoala cPanel deployment, use the included guide:

```text
docs/HOSTKOALA_CPANEL_DEPLOY.md
```

Use `app.js` as the startup file in cPanel's Node.js application tool.