Overview

CallView is a predictive dialer where AI qualifies and humans only close. The system auto-dials leads. When someone answers, a Vapi AI assistant (using a cloned human voice) qualifies the lead. If buying intent is detected, a live human agent is bridged into the same call seamlessly. If an answering machine picks up, a second AI drops a personalised voicemail. Uninterested leads never consume human time.

How a call flows

1. Dialer places an outbound call via Twilio
2. Lead answers → enters a Twilio Conference room (room name: callview-{callId})
3. The qualifying AI assistant (Vapi) joins the same conference via SIP
4. AI qualifies the lead:
   • Interested → agent clicks Takeover → AI is removed from conference, agent is unmuted, talks to the lead with full context
   • Not interested → AI wraps up, call ends normally
   • Answering machine (AMD) → qualifying AI is removed, voicemail AI is dialled in, speaks a personalised message, then hangs up
5. Agent selects a disposition code → lead action fires (return to pool / schedule callback / mark complete)

Tech stack

Roles & Permissions

6 roles, from least to most access. Permissions are configurable per-org by Superadmin.

Who needs which role

When inviting team members, only these roles can be assigned: SDR, Team Lead, Operations Manager.

App Navigation

The sidebar shows different items depending on the user's role. Full list:

Home group

Campaigns / Leads group

Management group

User menu (bottom of sidebar)

Contract Signed — Now What?

A client just signed. Here's everything you need to collect from them and everything you need to set up, in order.

What to ask the client human

Internal setup sequence

After you've collected everything above:

Total setup time: ~1.5–2 hours (excluding PVC voice clone processing).

1. Create the Org

Which Supabase project?

Path A: Supabase Dashboard (recommended) human

When a user is created in Supabase Auth, a database trigger (handle_new_user) fires and automatically creates the org + user. You don't write any SQL — the trigger does it.

Path B: Direct SQL SQL

For more control (custom org ID, specific timezone, specific settings). Run this in Supabase → SQL Editor.

-- Replace the values below with the actual client details
DO $$
DECLARE
  v_org_id  UUID := gen_random_uuid();
  v_user_id UUID := '<paste-the-auth-user-uuid-here>';
BEGIN
  -- Create the organization
  INSERT INTO organizations (id, name, timezone, status, setup_step)
  VALUES (
    v_org_id,
    'ABC Solar',              -- client company name
    'America/New_York',       -- their timezone (IANA format)
    'active',
    0                         -- triggers onboarding wizard on first login
  );

  -- Create the admin user linked to the org
  INSERT INTO users (id, organization_id, email, name, role, status)
  VALUES (
    v_user_id,
    v_org_id,
    'sarah@abcsolar.com',     -- must match the auth user email
    'Sarah Johnson',          -- display name
    'BUSINESS_OWNER',         -- gives them full access (except platform admin)
    'active'
  );
END $$;

After running this, give the client their email + password → they log in → onboarding wizard appears.

Org database fields

Multi-tenancy uses Postgres Row-Level Security (RLS) on organization_id — every table is scoped to the org.

2. Onboarding Wizard

After the org is created and the user logs in for the first time, the onboarding wizard appears at /onboarding. It has 3 steps. The wizard doesn't create the org — it configures an existing one (Twilio, first campaign, team).

Required role: Business Owner, Admin, or Superadmin.

Step 1: Phone (Twilio provisioning) automatic

Step 2: Campaign human

Step 3: Invite Team human

Self-heal

If the org already has Twilio + a campaign but setup_step is stale, tryAutoComplete() idempotently advances both steps and redirects to /campaigns.

3. Twilio Setup

Most Twilio setup happens automatically during onboarding (Step 1). This section covers manual setup and what each piece does.

What gets provisioned automatically

Buying more phone numbers human

SIP trunking (connecting Vapi) human

AMD (Answering Machine Detection)

AMD is toggled per-campaign in CallView's UI (not in Twilio Console). Under the hood it uses Twilio's async AMD with DetectMessageEnd mode — waits for the beep, then fires the voicemail swap. Cost: $0.0075 per call.

Webhooks

CallView receives Twilio events via webhooks. These URLs must be publicly reachable (use Cloudflare Tunnel for dev). Key callbacks:

• StatusCallback — call state changes (initiated → ringing → answered → completed)
• StatusCallbackEvent on conferences — participant join/leave/mute/hold
• AsyncAmdStatusCallback — AMD result (human vs machine_end_beep)
• RecordingStatusCallback — recording finished

Key console pages

4. Voice Cloning (ElevenLabs)

Every client needs a cloned voice for their AI assistant. This is the most human-intensive part of onboarding.

Clone types

Recording the voice samples human

Account tiers

Creator ($22/mo) is the minimum for production. It's the cheapest tier with Professional Voice Cloning + commercial rights.

Creating the clone in the dashboard human

Voice settings (tune after cloning) human

In the Voice Lab, click the voice → adjust these sliders:

TTS model selection

Connect ElevenLabs to Vapi human

Legal requirements

• Written consent from the voice owner is required — keep documentation on file
• IVC: checkbox confirmation during creation. PVC: additional verification step
• 12+ US states have voice cloning laws (CA, NY, TN ELVIS Act)
• Unauthorized impersonation or cloning public figures without consent violates ElevenLabs TOS and potentially law
• Free tier: no commercial use, must attribute ElevenLabs

Key dashboard pages

5. Vapi Assistants

Each client needs two Vapi assistants:

Enter Vapi API key in CallView human

Creating an assistant human

First message modes

Writing a system prompt for the qualifying AI human

Writing a system prompt for the voicemail AI human

Variables available in prompts

CallView sends SIP headers that Vapi exposes as {{variableName}}:

Connecting the assistant to CallView human

6. Write the Prompts

This is the most time-consuming step and the most important. You're writing the words the AI will say to leads. Both prompts go into the Vapi assistant's System Prompt field.

Qualifying AI prompt template human

You are [NAME], a friendly and professional sales representative at [COMPANY].
You are calling potential customers to discuss [PRODUCT/SERVICE].

Your personality: [warm/energetic/professional/casual] and conversational. You speak
like a real person — use contractions (I'm, we've, that's), occasional filler words
(um, you know, so basically), and keep responses to 1-2 sentences.

## CONTEXT
You have this information about the lead:
- Name: {{name}}
- Phone: {{phone}}
- Additional context: {{lead_context}}

## CALL FLOW
1. Greet the lead by name: "Hi [first name], this is [NAME] from [COMPANY]."
2. Brief pitch: [ONE SENTENCE about the product/service — what's in it for them]
3. Qualify with these questions (one at a time, conversational):
   - [Question 1, e.g. "Are you the homeowner at this address?"]
   - [Question 2, e.g. "What are you currently paying for electricity each month?"]
   - [Question 3, e.g. "Have you ever looked into solar for your home?"]
4. If interested: "That's great! I'd love to connect you with one of our specialists
   who can walk you through the specifics. Can I transfer you now?"
5. If not interested: Thank them for their time, wish them a good day, end the call.

## RULES
- One question at a time. Wait for their answer before asking the next.
- Never read out field names, colons, or technical data.
- Say phone numbers digit by digit with pauses: "five one eight ... nine zero zero".
- Do not discuss pricing, contracts, or make financial commitments.
- Do not bash competitors.
- If they say "not interested", "take me off your list", or "do not call": respect it
  immediately, apologise for the interruption, and end the call.
- If they ask "is this AI?": be honest. "Yes, I'm an AI assistant for [COMPANY].
  Would you like me to connect you with a human team member?"
- Stay in character at all times.
- Maximum 8 turns before wrapping up.

## EXAMPLES

### Example 1: Happy path
AI: "Hi Salvatore, this is Roger from Mister Solar Guy. How are you doing today?"
Customer: "Good, what's this about?"
AI: "We've been running solar assessments in your area and your home at 100 Acampora
Drive came back with some really strong numbers. Are you the homeowner there?"
Customer: "Yeah, that's me."
AI: "Great. What are you paying for electric these days, roughly?"
Customer: "About three fifty a month."
AI: "Oh wow, yeah, at that level you'd see some serious savings. Have you ever
looked into solar before?"
Customer: "I've thought about it but never pulled the trigger."
AI: "Totally understand. I'd love to connect you with one of our specialists who can
walk you through what the numbers look like for your specific home. Can I transfer
you now, or would a callback work better?"

### Example 2: Not interested
AI: "Hi Maria, this is Roger from Mister Solar Guy —"
Customer: "Not interested, thanks."
AI: "No problem at all, Maria. Sorry to bother you. Have a great day!"

### Example 3: Busy
AI: "Hi James, this is Roger from Mister Solar Guy. How's it going?"
Customer: "I'm actually in the middle of something."
AI: "Oh, I'm sorry about that. Would it be alright if we gave you a call back
tomorrow, maybe in the afternoon?"
Customer: "Sure, after 2 works."
AI: "Perfect, we'll reach out after 2 tomorrow. Thanks James, talk soon!"

Voicemail AI prompt template human

You are [NAME] from [COMPANY]. You are leaving a voicemail message.

You will receive context about this lead in {{lead_context}}. Extract the values
from these fields:
- After "Vm1:" — this is your first sentence (mentions their address)
- After "Vm2:" — this is your second sentence (mentions their ranking)
- After "Vm3:" — this is your third sentence (mentions savings)

If you find those fields, speak this script exactly, substituting the values:

---
Hi {{name}}, this is [NAME], [TITLE/COMPANY] here in [REGION].
[Vm1 value]. [Vm2 value]. [Vm3 value].
Give me a call when you get a chance — [CALLBACK NUMBER SPOKEN DIGIT BY DIGIT].
Again, this is [NAME], [TITLE/COMPANY].
---

RULES:
- Speak the script exactly. Do not add extra sentences, greetings, or "sorry I
  missed you" filler.
- Do not read field names (Vm1:, Vm2:, Zip:, City:, etc.) — speak only the values.
- Say the phone number once, digit by digit with natural pauses between groups:
  "five one eight ... nine zero zero ... one four three one"
- Warm, confident, conversational tone. Not rushed, not dramatic.
- After "Again, this is [NAME], [TITLE/COMPANY]" — end the call. Do not continue.
- If Vm1/Vm2/Vm3 fields are missing from the context, speak this fallback instead:
  "Hi {{name}}, this is [NAME] from [COMPANY]. I was calling about [BRIEF PITCH].
  Give me a call back at [CALLBACK NUMBER]. Again, this is [NAME], [COMPANY]."
- Total message must be under 35 seconds spoken time.

Example: filled-in voicemail prompt (solar)

You are Roger from Mister Solar Guy. You are leaving a voicemail message.

You will receive context about this lead in {{lead_context}}. Extract the values
from these fields:
- After "Vm1:" — this is your first sentence (mentions their address)
- After "Vm2:" — this is your second sentence (mentions their ranking)
- After "Vm3:" — this is your third sentence (mentions savings)

If you find those fields, speak this script exactly, substituting the values:

---
Hi {{name}}, this is Roger, Mister Solar Guy here in the Hudson Valley.
[Vm1 value]. [Vm2 value]. [Vm3 value].
Give me a call when you get a chance — five one eight ... nine zero zero ...
one four three one.
Again, this is Roger, Mister Solar Guy.
---

RULES:
- Speak the script exactly. Do not add extra sentences, greetings, or "sorry I
  missed you" filler.
- Do not read field names (Vm1:, Vm2:, Zip:, City:, etc.) — speak only the values.
- Say the phone number once, digit by digit with natural pauses between groups.
- Warm, confident, conversational tone. Not rushed, not dramatic.
- After "Again, this is Roger, Mister Solar Guy" — end the call. Do not continue.
- If Vm1/Vm2/Vm3 fields are missing from the context, speak this fallback instead:
  "Hi {{name}}, this is Roger, Mister Solar Guy. I was calling because we ran a
  solar assessment on your home and I'd love to share the results with you.
  Give me a call back at five one eight ... nine zero zero ... one four three one.
  Again, this is Roger, Mister Solar Guy."
- Total message must be under 35 seconds spoken time.

After pasting the prompt human

7. Invite Team Members

Sending an invite human

Accepting an invite (what the invitee does) human

Invitation states

Campaign Setup

/campaigns — master-detail layout. Campaign list (with search) on the left, tabbed config on the right. Ops Manager or above.

Creating a campaign human

Campaign status flow

draft → active → paused ↔ active → completed → archived

Tab: General

Tab: Outbound

• Voicemail Drop toggle — enables/disables AMD for this campaign. Team Lead+ required. When enabled, shows the campaign's SIP whitelist.
• Disposition Codes — drag-to-reorder list. Each code has:
  • Name (e.g. "Left VM", "Interested", "Wrong Number")
  • Emoji (visual icon)
  • Color
  • Lead action: return_to_pool | schedule_callback | mark_complete
  Can copy/paste disposition sets between campaigns.
• Quick Action Buttons — configurable whisper/say/interrupt actions for the dialer. 4 categories: Objection Handling, Call Flow, Closing, General.

Tab: Inbound

3-step configuration for inbound AI: readiness check → greeting/context/closer routing config → audit log. Gated to Business Owner / Ops Manager / Superadmin. URL: /campaigns/:id/inbound-ai.

Tab: Roster

• Team assignments: which SDRs work this campaign
• Lead Lists: which lead lists are assigned
• Closers: who can receive warm transfers (used by Closer Invite)

Tab: Manager Tools

Bulk reassign leads between agents. Ops Manager / Business Owner only.

Lead Import

/leads/import — 4-step wizard. Ops Manager or above.

Step 1: Settings human

Step 2: Upload human

Step 3: Mapping human

Step 4: Review human

Lead lifecycle

Lead detail page

Click any lead in the list → detail panel shows: all custom fields (jsonb), call history, dispositions, tags, pool status, assigned SDR. Click "Edit" to modify fields, including "Sales Rep SIP" (dropdown of org SIPs).

Bulk operations

Select multiple leads → bulk actions: Tag, Assign (SDR + lead list), Delete. There is no bulk SIP assignment.

SIP & Voicemail Configuration

SIP URIs connect Twilio conferences to Vapi voicemail assistants. There are multiple layers.

SIP resolution order (when voicemail triggers)

CallView checks these in order when AMD fires:

1. User-level override (users.voicemail_sip_id) — if the SDR making the call has a personal voicemail SIP assigned, it wins. No whitelist gate — always used if present.
2. Lead-level assignment (leads.sales_rep_sip_id) — checked against the campaign's SIP whitelist (campaign_sales_rep_sips). Only used if the SIP is in the whitelist.
3. If neither is set: voicemail drop fails silently with no_sales_rep_sip. The qualifying AI keeps talking into the answering machine instead of the voicemail AI. This is the root cause of voicemail failures.

Both are resolved and cached in ui_state.voiceConfig at call creation time, not at swap time.

Sales Rep SIP library human

Assigning SIPs to users human

Assigning SIPs to leads

Per lead: Leads → click a lead → Edit → "Sales Rep SIP" dropdown.
Bulk: There is no bulk SIP assignment UI or API. For bulk writes, use SQL:

UPDATE leads SET sales_rep_sip_id = '<sip-library-id>'
WHERE organization_id = '<org-id>' AND id IN (...);

Campaign SIP whitelist human

Voicemail AI dashboard (/voicemail-ai)

Read-only overview showing:

• SDR voicemail SIP overrides (inline editable via dropdown)
• Campaign AMD whitelist summaries
• Lead SIP distribution across the org
• SIP library summary
• The 4 voicemail scenarios:
  1. Override — user SIP wins (no whitelist check)
  2. Lead SIP — lead's sales_rep_sip_id used (whitelist-gated)
  3. Blocked — lead has a SIP but it's not in the campaign whitelist
  4. Fallback — no SIP found, voicemail drop fails

The Dialer

/dialer — the main screen SDRs use. 4-column layout (desktop). All roles can access.

Layout

Mobile: collapses to single-column (MobileDialerLayout).

Conference state machine

The banner at the top of the Controls column shows the current state:

Every button in the dialer

Quick Actions panel

Configured per-campaign (Campaign → Outbound tab). 4 categories:

• Objection Handling — whisper rebuttals to the AI
• Call Flow — direct the AI's next action
• Closing — transition commands
• General — misc

Each action sends a command to the AI: whisper (AI hears, lead doesn't), say (AI says it to the lead), or interrupt (AI stops talking).

Call State Trail

Horizontal timeline below the controls showing every state transition: dialing → ringing → connected → passive → mute-ai / takeover / voicemail → ended. Each step timestamped. Labels show voice source: "Conversation voice" / "Your voicemail voice" / "Lead's voicemail voice".

Speed to Lead

Banner/strip for inbound lead notifications. Card stack, newest on top. Timer colour: green <2min, yellow 2–5min, red 5min+. Button: "Call Now" (immediate dial) or dismiss.

Call Flow (Step by Step)

What happens internally when an SDR clicks Initiate Call:

1. Validate: Check conference is configured for org (isConferenceConfiguredForOrg())
2. Resolve voice: Find the SIP for this user: user SIP assignment → default SIP → any active SIP → error if none
3. Check campaign: Status must be active, current time must be within call hours (8am–9pm in campaign timezone)
4. DNC check: checkDnc() on the lead's phone
5. Create call record: Status initiated in the database
6. Lock the lead: pool_status: 'locked', locked_by: userId
7. Create conference: Twilio REST API — outbound call to customer with conference TwiML. Room name: callview-{callId}
8. Cache voice config: SIP URI, webhook base URL, lead data, sales rep SIP for AMD — all stored in ui_state.voiceConfig
9. Customer answers: Twilio status webhook fires
10. Add AI: addAiToConference() — dials the qualifying AI via SIP with all x- headers (see SIP Headers)
11. Conference state → PASSIVE: AI is talking, SDR is listening via live transcript
12. From here:
    • SDR clicks Takeover → AI removed, SDR bridged in → state: TAKEOVER
    • AMD fires → qualifying AI swapped for voicemail AI (see Voicemail Drop)
    • AI finishes qualifying → call ends normally
13. After call: Disposition panel appears. SDR selects a code → lead action fires.

Voicemail Drop

The voicemail drop is not a recording. It's a second Vapi AI assistant dialled into the same Twilio conference the qualifying AI was just removed from.

Step-by-step swap (amd-swap.service.ts)

1. AMD detected (Twilio async webhook or Vapi detection or manual button) → handleVoicemailDetected()
2. Record amd_detected_at timestamp
3. Check campaign.amd_enabled — if disabled, return fallback, qualifying AI keeps talking
4. SIP resolution: SDR voicemail_sip_id (override, no whitelist) → lead sales_rep_sip_id (whitelist-gated) → if neither: return fallback: no_rep_assigned
5. Query sales_rep_sips table for the actual SIP URI
6. Fire-and-forget audit (auditVmDropAssistant()) — checks the Vapi assistant for problems: waits_for_user, first_message_empty, model_generated_first_message, voicemail_detection_enabled
7. Broadcast swapping status to SDR via SSE
8. Record amd_swap_started_at
9. Remove qualifying AI — Twilio REST: DELETE /Conferences/{sid}/Participants/{aiCallSid}
10. Add voicemail AI — addAiToConference() with the voicemail SIP URI + same lead data/headers
11. Record amd_swap_completed_at
12. Broadcast active status with autoHangupAt timestamp to SDR
13. Start 40-second hangup timer (VOICEMAIL_AUTO_HANGUP_MS)
14. Timer fires → executeVoicemailAutoHangup(): check guards (already ended? SDR took over?), endConference(), update call (status: completed, ended_reason: voicemail_timeout), release lead lock, broadcast SSE

Swap status values

Three trigger paths

Timing budget

Configuration checklist (new client voicemail setup) human

Closer Invite / Warm Transfer

When the AI qualifies a lead and the SDR takes over, they can invite a closer into the conference for a warm handoff.

Two modes

What the closer experiences

1. Phone rings
2. On answer: hears a whisper announcement with the lead's name and the SDR's name
3. Bridged into the conference
4. AI is removed automatically when the closer joins (remove-vapi-on-bridge.service.ts)

If no closer answers

A callback task is created (no-closer-callback-task.service.ts) so the lead doesn't fall through the cracks.

Setting up closers human

Dispositions

After every call, the SDR selects a disposition code. The code determines what happens to the lead next.

Setting up disposition codes human

After a call

Disposition panel appears in the dialer. SDR picks a code → lead action fires automatically → publishCallDispositionedEvent() broadcasts to other services → the next lead loads.

Transcript & Recordings

Live transcript

• Transport: SSE (Server-Sent Events) over HTTP
• Backend: Redis pub/sub — broadcast.service.ts publishes, sse.service.ts subscribes, sse-manager.service.ts manages client connections
• UI: TranscriptColumn.tsx → TranscriptBubble.tsx per utterance. Each bubble shows: speaker (AI / Customer), text, timestamp
• Events include: transcript updates, call status changes, voicemail detection, closer status, conference state changes

Recordings

• Calls are recorded via Twilio (per-conference or per-participant)
• Recordings are downloaded from Twilio and uploaded to Supabase Storage (bucket: call-recordings)
• Format: MP3
• Access: via signed URLs with 1-hour expiry
• Dual-channel recording available (separates caller/callee)
• Accessible in: Call History → click a call → recording player

Call History

/call-history — all calls for the org.

Layout

Split view: call list + dossier panel side-by-side (desktop), slide-over sheet (tablet), full-screen toggle (mobile). KPI bar at the top.

Filters

• Date range
• Campaign
• User (which SDR)
• Disposition
• Search (phone, name, etc.)

Per-call detail

• Status, duration, disposition
• Recording player
• AI-generated call summary
• Lead info
• Full transcript
• Call events timeline (state transitions with timestamps)

Export

CSV download of filtered call data.

Deployment Architecture

Where V1 runs

CallView V1 is a microservices architecture hosted on Railway. The GitHub repo is BenLorenzoDev/CallView-AI-MS.

Only client and gateway have public domains. All other services communicate internally via Railway’s private network (RAILWAY_PRIVATE_DOMAIN).

External services

CI/CD pipeline

Deployments use GitHub Actions → Dagger → Railway:

1. Push to master triggers the CI workflow (.github/workflows/ci.yml)
2. CI runs: lint → build all services (parallel) → unit tests
3. If CI passes and it’s a push to master, the deploy job runs
4. Dagger installs @railway/cli, links to the project, and runs railway up --detach for each service sequentially
5. Push to staging branch deploys to the staging environment instead

Railway also has auto-deploy configured: any push to master that changes files under callviewai2/** triggers a rebuild.

Supabase projects

Viewing Logs

Railway Dashboard (recommended)

1. Go to railway.app/dashboard
2. Open the CallView-AI-MS project
3. Click on the service you want to inspect (e.g. calling-service)
4. Click the Logs tab — shows live stdout/stderr in real time
5. Use the search bar to filter by keywords (e.g. “error”, a callId UUID, “vapi”)

Railway CLI

# View live logs for a specific service
railway logs --service gateway
railway logs --service calling-service
railway logs --service workflow-service

# View all services (noisy)
railway logs

Log format

All services use Pino (structured JSON logging). Each log line is a JSON object with:

{
  "level": 30,          // 10=trace 20=debug 30=info 40=warn 50=error 60=fatal
  "time": 1723456789,   // Unix epoch ms
  "service": "calling-service",
  "env": "production",
  "msg": "POST /api/calls/start 200",
  "requestId": "abc-123",
  ...context fields
}

Search for "level":50 to find errors, or "level":40 for warnings.

No external error tracking

V1 does not use Sentry, Logtail, BetterStack, or any external error tracking service. All error visibility is through Railway logs. If you need alerts, set up Railway’s built-in notification integrations (Slack, email) or add a log drain.

Health Checks

Endpoints

Every backend service exposes GET /health returning HTTP 200 when healthy. Railway pings these automatically (configured timeout: 300 seconds).

# Quick check from your machine
curl https://api.callview.ai/health
curl https://app.callview.ai

What health checks cover

• Service process is running and accepting HTTP
• Redis connection is alive (gateway checks this)
• If a health check fails, Railway marks the service as unhealthy and will restart it automatically

Checking Vapi connectivity

The calling service has an internal function checkVapiConnection() that returns 'connected', 'error', or 'not-configured'. This is used at startup — check calling-service logs for “Vapi connection check” messages.

Error Scenarios & Recovery

Vapi runs out of credits

How to detect:

• Check dashboard.vapi.ai/billing — shows current balance and usage
• Look for errors in calling-service logs: search for “Vapi” or “vapi” — you’ll see 402/403 errors from Vapi’s API
• The cost-sync.worker.ts will log: "No Vapi API key found for org" or "Vapi auth failed for cost sync"

How to fix:

1. Add credits in Vapi billing (top up immediately)
2. Once topped up, new calls will work automatically — no restart needed
3. Consider setting up Vapi’s low-balance email alert in the billing page

Twilio errors

How to detect:

• Check Twilio Voice Logs — shows every call with status and error codes
• Check Twilio Debugger — aggregated errors with explanations
• Search calling-service logs for “twilio” or “Twilio”

Common Twilio errors:

ElevenLabs quota exhausted

How to detect:

• Check ElevenLabs Usage — shows character count vs plan limit
• Calls sound “different” — the fallback voice is generic
• Vapi end-of-call-report may show TTS errors in cost breakdown

How to fix: Upgrade ElevenLabs plan or wait for monthly reset. Each plan’s character limits:

Railway deployment fails

How to detect:

• Check GitHub Actions — the CI/CD workflow will show red
• Railway Dashboard → click the service → Deployments tab shows build logs

Common causes:

Supabase issues

Connection limit reached: Supabase free tier allows ~60 direct connections. With 7 microservices, each holding a connection pool, this can be hit under load. Check the Database Settings page. Consider upgrading or using Supabase’s connection pooler (Supavisor).

RLS policy blocks a query: All tables have Row Level Security. If a query returns empty unexpectedly, check that the JWT includes the correct organization_id claim. Look for “RLS” or “permission denied” in service logs.

Redis connection lost

What happens: Services lose shared state. SSE client tracking, recording queues, and cost-sync workers will fail.

How to detect: Look for “redis” errors in any service’s logs. Gateway health check will fail (it checks Redis connectivity).

How to fix: Check the Redis plugin in Railway Dashboard. If it’s crashed, Railway auto-restarts it. If it’s persistently down, delete and re-provision the Redis plugin (data loss is acceptable — Redis is used for ephemeral state only, not persistent data).

Railway Operations

Quick command reference

# Authenticate
railway login

# Link to the CallView project
railway link

# Deploy all services
railway up

# Deploy a single service
railway up --service gateway

# View live logs
railway logs --service calling-service

# Check deployment status
railway status

# List environment variables
railway variables

# Rollback to previous deployment
railway rollback

Redeploying a single service

1. In Railway Dashboard, click the service
2. Go to Deployments tab
3. Click Redeploy on the latest deployment, or click a previous one and select Rollback

Updating environment variables

1. Railway Dashboard → click the service → Variables tab
2. Add or edit the variable
3. Railway automatically redeploys the service when a variable changes

Variables that reference other services use Railway’s template syntax:

AUTH_SERVICE_URL=http://${{auth-service.RAILWAY_PRIVATE_DOMAIN}}:3001

Scaling

Railway doesn’t support horizontal scaling (multiple instances of the same service) on the Hobby plan. On the Pro plan ($20/mo), you can configure replicas per service. For V1, a single instance of each service is sufficient for current load.

Cost monitoring

Railway bills per usage (CPU, memory, network). Check railway.app/account/billing for current spend. Typical V1 cost: $5–20/mo depending on call volume.

SIP Headers (Technical Reference)

When CallView dials a Vapi assistant into a conference, it sends these x- headers in the SIP URI:

Size limits

Budget trimming

If the total URI exceeds 1,024 chars, headers are dropped in this priority (lowest dropped first):

1. lead_context (first to go)
2. lead_status
3. email
4. now
5. company

Never dropped: callview_call_id, callview_lead_id, first_name, last_name, phone, callback_number, timezone.

How lead_context is built

Code at twilio-conference.service.ts:560-577:

1. Read the lead's custom_fields (jsonb)
2. For each key-value pair: format as Title Cased Key: value
3. Join all with ; (semicolon + space)
4. Slice to 300 characters

Postgres sorts jsonb keys by length first, then bytewise. Short keys (like vm1, 3 chars) always sort before longer keys (like homevalue, 9 chars), guaranteeing they survive the 300-char slice.

Pricing Reference

Twilio

Vapi

ElevenLabs

Per-call cost estimates

Compliance

TCPA / FCC rules

Voice cloning consent

Written consent from the voice owner required. Keep on file. 12+ US states have specific laws (CA, NY, TN ELVIS Act).

FAQ

Client wants to use their own Twilio number

This is the BYOT (Bring Your Own Twilio) flow. The client keeps their existing Twilio account and phone numbers.

Client wants to port an existing phone number to Twilio

Client wants to add more phone numbers later

No problem. Follow Twilio Setup → Buying More Numbers. Once purchased, the number appears in CallView automatically (it reads from the Twilio sub-account). Assign it to a campaign in Campaigns → General → Phone Numbers.

Client wants to change the AI voice

Client wants to pause dialing temporarily

A lead says "take me off your list" (DNC request)

A lead calls back

V1 supports Friendly Callback (inbound AI) for orgs that have it configured. The flow:

1. Lead calls the Twilio number back
2. Twilio routes it to the inbound AI assistant (configured in CallView → Settings → Inbound AI)
3. The AI greets the caller, identifies the lead by phone number, and can transfer to a closer

If inbound AI is NOT configured, the call goes to Twilio's default voicemail or plays an error. Make sure inbound routing is set up if the client expects callbacks.

Client forgot their password

Client wants a second campaign

Go to CallView → /campaigns → "New Campaign". Each campaign is independent: its own phone numbers, lead lists, call hours, roster, dispositions, and closer list. A phone number can only belong to one campaign at a time — buy additional numbers if needed.

Client wants different dispositions

Dispositions are per-campaign. Go to Campaigns → select campaign → Dispositions tab. Add, rename, or remove. Defaults: Interested / Not Interested / Callback / Wrong Number / Left VM / DNC. Dispositions already used on calls cannot be deleted (they'd break call history), but they can be renamed.

Client wants to change the AI script

Client wants to export their data

CallView has no built-in export UI. Options:

• Leads: Supabase Dashboard → Table Editor → leads → filter by organization_id → Export CSV
• Calls: Same process on the calls table
• Recordings: Recording URLs are in the calls table (recording_url column). These are Twilio-hosted and expire after the account's retention period (default: no expiry)

How many concurrent calls can we run?

Depends on the Twilio account tier:

If you hit the limit, Twilio returns error 20429 (rate limit). The dialer will see failed calls. Request a CPS increase in Twilio Console → Voice → CPS or contact Twilio support.

Can we use a different AI provider instead of Vapi?

V1: No. The calling service is tightly coupled to Vapi's API (assistant creation, SIP dialling, end-of-call reports, cost sync). Switching would require rewriting the calling service.

V2: Being built with an open framework (LiveKit/Pipecat) specifically to avoid vendor lock-in. See the V2 architecture docs.

Client wants their own Vapi account

Each org stores its own vapi_api_key. If a client has their own Vapi account:

1. They create their Vapi account at dashboard.vapi.ai
2. Copy their API key from Vapi → Org Settings → API Keys
3. Paste it in CallView → Settings → Organization → Vapi API Key
4. Create assistants in their Vapi account (not yours)
5. They manage their own Vapi billing

What happens if a service crashes?

Railway automatically restarts crashed services. The previous healthy deployment keeps running until the restart succeeds. In-progress calls may drop if calling-service crashes (conference state is lost). Check Viewing Logs for crash details and Error Scenarios for recovery steps.

Troubleshooting

Voicemail drops failing (no_sales_rep_sip)

Symptom: AMD fires but the qualifying AI keeps talking into the answering machine.

Cause: Lead's sales_rep_sip_id is NULL and the SDR has no voicemail SIP override.

Fix: Assign sales_rep_sip_id to leads (bulk via SQL) and/or set user-level voicemail SIP (Team Members → Voicemail SIP dropdown).

Voicemail cut off mid-sentence

Symptom: Lead receives a truncated voicemail.

Cause: Message exceeded 40s (the hard kill timer, VOICEMAIL_AUTO_HANGUP_MS).

Fix: Shorten the script to under 35s spoken time.

AI reads raw field names ("Vm1:", "Zip:")

Symptom: Voicemail AI says "Vm1 colon We ran a solar assessment..." instead of just the content.

Cause: firstMessageMode is wrong, or prompt doesn't instruct AI to extract field values.

Fix: Set firstMessageMode to assistant-speaks-first-with-model-generated-message. Prompt must explicitly say "extract the value after 'Vm1:' and speak only the value".

Custom fields gone after CSV import

Symptom: Existing custom fields (homevalue, zip, etc.) disappeared from leads.

Cause: Import wizard's "Update Existing" mode replaces custom_fields wholesale.

Fix: Use SQL with jsonb || to merge. Only use CSV import for new leads.

Leads not being dialled

Check these in order:

1. pool_status must be available
2. Lead must be in a lead list assigned to the campaign
3. Campaign must be active
4. Current time must be within campaign call hours (in recipient's timezone)
5. is_deleted must be false
6. Lead must not be on DNC list

Cloned voice sounds robotic

Check voice settings in ElevenLabs Voice Lab:

• Stability: 0.65–0.75 (too high = flat, too low = jittery)
• Similarity Boost: 0.82–0.88
• Style Exaggeration: must be 0
• Speaker Boost: On

If settings are correct, the recordings were likely low quality. Re-record in a treated room with proper equipment.

SDR override vs lead SIP error

Symptom: SDR's override lookup fails silently, so it falls through to lead SIP (which may also be NULL).

Cause: call.service.ts:968-973 discards the query error. A failed database lookup is indistinguishable from "no SIP set".

Workaround: Always set both user-level and lead-level SIPs as defence in depth.

Useful console links