Twilio Voice Route Map¶

Quick reference for local URLs (and the files that implement them). Use this when wiring Twilio Console webhooks, testing with ngrok, or tracing voice/SMS/billing flows.

Related docs

Conventions¶

Twilio Voice — SDK, TwiML, status & recovery¶

Example (local)

http://localhost:3035/api/twilio/voice/max-duration-preview?iso=US
http://localhost:3035/api/twilio/sync-cost-jobs?limit=50
http://localhost:3035/api/twilio/refresh-voice-pricing-csv
http://localhost:3035/api/twilio/sync-calls?days=1&limit=200&refreshDetails=true&pendingOnly=false
http://localhost:3035/api/twilio/call-holds?status=PENDING
http://localhost:3035/api/twilio/call-holds?userId=<id>&status=PENDING
http://localhost:3035/api/twilio/call-holds/cleanup?limit=500

Twilio SMS — Console webhooks vs app API¶

Configure incoming and status URLs in Twilio Console using your public base + path (same idea as voice).

Example (local)

http://localhost:3035/api/twilio/sms/inbound
http://localhost:3035/api/twilio/sms-status

SMS — multiple numbers per user¶

Inbound (processInboundSms() in lib/sms-inbound.ts):

• Twilio sends To = the Twilio number that received the SMS. Ringvoo resolves the owner with TwilioNumber where phoneNumber matches that E.164 (normalized).
• If no TwilioNumber row exists for To, the message is not stored (unknown number).
• If the row has a linked VirtualNumber, inbound is accepted only when VirtualNumber.status is active or past_due.
• One user can own many TwilioNumber rows; each phoneNumber is globally unique, so each inbound To maps to exactly one owner.

Outbound (sendUserSms() in lib/sms-send.ts, called from POST /api/sms/send):

• The client must send fromNumber (which line to use). The server checks TwilioNumber for (userId = session user, phoneNumber = fromNumber) — you cannot send from a number you do not own.
• The same VirtualNumber active/past_due rule applies as for inbound.
• Outbound destinations are restricted to US/Canada (+1) in lib/sms-send.ts.

Conversations (SmsConversation):

• Threads are keyed by (userId, twilioNumberId, remoteNumber) — one thread per owned local line and remote party. If the same user texts the same contact from two different lines, they get two separate conversations.

Dashboard (components/dashboard/sms/SmsInboxClient.tsx):

• Loads numbers via GET /api/user/twilio-numbers, defaults the compose fromNumber to the first number, and lets the user select another owned line when sending.

Dashboard — wallet, calls, numbers (authenticated)¶

Public — marketing / unauthenticated pricing helpers¶

Example (local)

http://localhost:3035/api/public/voice-rates?iso=US
http://localhost:3035/api/public/voice-rate-floor
http://localhost:3035/api/public/dialer-footer-preview?iso=US

SMS — dashboard APIs (authenticated)¶

:conversationId = Prisma SmsConversation.id.

Virtual numbers — search, checkout, subscription¶

Billing, Stripe & promos¶

Admin¶

Example (local)

http://localhost:3035/api/admin/users/role?email=user@example.com

Auth & placeholders¶

How rates are used¶

• Max duration limiter uses the highest country rate (retail):
  getMaxRetailRatePerMinuteUsdForIsoCountry() in lib/billing/twilio-voice-pricing.ts
• Inbound max duration / hold limiter uses the highest inbound country rate (retail):
  getMaxInboundRetailRatePerMinuteUsdForIsoCountry() in lib/billing/twilio-voice-pricing.ts
• Marketing preview uses the lowest country rate (retail):
  getMarketingStartingRetailRatePerMinuteUsd() in lib/billing/twilio-voice-pricing.ts
• Final customer debit uses actual Twilio call cost × multiplier:
  splitTwilioAndRetailCharge() in lib/billing/voice-pricing.ts
• “Available balance” for voice admission is the wallet gross balance (holds are legacy/no-op):
  getAvailableBalanceUsd() in lib/call-holds.ts (returns wallet.balance with activeHoldsUsd = 0)
• Client metrics can still supply fallback duration when Twilio callbacks lag (used to improve provisional rows / settlement timing), but it is not a financial “hold compression” mechanism.

Inbound ownership model¶

Inbound ownership is determined by Ringvoo's database, not by Twilio subaccounts or per-user Twilio ownership.

• Twilio knows only that the purchased phone number belongs to the Ringvoo Twilio account.
• Ringvoo decides which app user owns that number by storing a mapping in TwilioNumber.
• The canonical ownership lookup is getUserFromTwilioNumber() in lib/twilio.ts.
• That lookup reads TwilioNumber.phoneNumber -> TwilioNumber.userId.
• TwilioNumber.phoneNumber is unique globally, so each inbound To number resolves to exactly one owner.
• A user can own multiple numbers (multiple TwilioNumber rows sharing the same userId).
• If a TwilioNumber row is linked to a VirtualNumber, inbound routing is allowed only when VirtualNumber.status is active or past_due.
• If no TwilioNumber row exists for the inbound To number, Ringvoo does not route that inbound call to a browser client.

Example:

{
  "phoneNumber": "+18153678725",
  "userId": "cmne9lz3i0000z27wovrrqhgs",
  "friendlyName": "Main Twilio number"
}

Meaning:

• the Twilio number is owned at Twilio-account level by Ringvoo
• Ringvoo routes inbound calls for that number to the user cmne9lz3i0000z27wovrrqhgs
• Ringvoo also bills inbound usage for that number to that same user

This is the expected SaaS model for future number purchase as well:

1. Ringvoo buys the number using the shared Twilio account
2. Ringvoo inserts a TwilioNumber row for the purchasing user
3. inbound calls to that number resolve back to that user via TwilioNumber

Development/testing note:

• Manually inserting TWILIO_PHONE_NUMBER into TwilioNumber is a valid local test setup for inbound routing.
• In production flow, numbers are expected to be created through virtual-number provisioning, which also creates/links VirtualNumber status used by inbound eligibility checks.

Inbound billing flow¶

Main files:

• app/api/twilio/voice/inbound/route.ts
• app/api/twilio/call-status/route.ts
• lib/call-billing.ts
• lib/voice-call-validation.ts, lib/voice-call-sessions.ts, lib/voice-dial-time-limit.ts
• lib/call-holds.ts (legacy API surface; holds are no-op in current schema)
• lib/call-cost-sync.ts
• components/dashboard/TwilioProvider.tsx

Lifecycle:

1. Twilio sends inbound webhook to POST /api/twilio/voice/inbound (local: http://localhost:3035/api/twilio/voice/inbound)
2. Ringvoo resolves the called Twilio number in TwilioNumber
3. Ringvoo runs the same wallet admission path as outbound (validateVoiceCallStart) using an inbound max retail estimate (getInboundVoiceEstimateForIso)
4. On success, Ringvoo creates a CallSession and sets <Dial timeLimit> from computeVoiceDialTimeLimitSeconds (includes low-balance stepping when applicable)
5. Ringvoo returns TwiML to dial the browser client for that user
6. Twilio emits callbacks for the browser/client leg and terminal completion
7. Ringvoo resolves the correct billable leg and settles the call through upsertCallAndSettleWallet()
8. Ringvoo debits the wallet (estimated-first when Twilio price is late) and ends/binds matching CallSession rows (no CallHold settlement)

Parent and child Twilio legs¶

Inbound browser-connected calls usually have 2 Twilio call legs:

• Parent leg: PSTN caller → Twilio number
• Child leg: Twilio → client:<userId>

For inbound settlement, the canonical persisted/billed call is the child billed leg:

• Call.twilioCallSid = child billable leg
• Call.twilioParentCallSid = parent inbound leg
• CallSession.twilioParentCallSid / optional billableCallSid track the parent→child relationship for estimated settlement + duration fallbacks

Why:

• Twilio's final priced/completed browser-connected call is the leg used for actual settlement
• the parent leg is still important for correlation and session binding

Outbound: dashboard dialer (browser → PSTN)¶

When a user calls a normal phone number from the WebRTC dialer, Twilio still uses two conceptual legs:

1. Parent leg (browser → your TwiML App)
   Twilio’s From on webhooks for this leg is client:<userId> — the Voice SDK identity from /api/twilio/token (same as User.id in Prisma). This is not the caller ID the callee sees.

2. Child leg (Twilio → callee’s number)
   The PSTN leg uses callerId from TwiML (<Dial callerId="…">) in POST /api/twilio/voice/outbound. That value is the Ringvoo public number, an owned virtual number, or a verified custom caller ID, depending on the user’s “Call from” selection.

Reading it in Twilio Console

1. Open Monitor → Logs → Calls (or Develop → Monitor → Call logs, depending on Console layout).
2. Paste the CallSid from Ringvoo server logs (or search by destination number / time).
3. Open the call; if Twilio shows related calls or a child call, open the leg whose To is the destination country number (e.g. +971…). On that leg, From should match the PSTN caller ID you chose (e.g. +1507…), not client:….
4. The leg where From is client:… is the browser leg; use it only to correlate with the user session, not as “what number was displayed.”

Ringvoo logs

With TWILIO_VOICE_LOG_OUTBOUND=true, outbound TwiML generation logs twilioDeviceFrom (always client:… on the SDK leg), pstnCallerId (the E.164 used on <Dial>), and twilioAccountAuthorizesCallerId when “Call from” is owned/custom: true only if that E.164 is an Incoming Phone Number or Verified Caller ID on the same Twilio Account SID. Ringvoo’s in-app OTP does not by itself register the number with Twilio; if this flag is false, add the number under Twilio Console → Phone Numbers → Verified Caller IDs (or use a Twilio-purchased number). Billing-related logs may still show From as client:… because they follow Twilio’s parent-leg fields; for display and accounting, prefer the persisted Call.fromNumber / Call.toNumber once upsertCallAndSettleWallet has normalized the billable leg.

Optional: TWILIO_FALLBACK_CALLER_ID_IF_NOT_TWILIO_AUTHORIZED=true forces fallback to TWILIO_PHONE_NUMBER when Twilio would not honor the selected PSTN caller ID (connectivity over custom CLI).

Caller-ID source of truth and API usage¶

Ringvoo intentionally uses two checks for custom caller IDs:

1. Product permission (Ringvoo DB)
   UserCallerId.verified=true means the user can choose that number in the dialer.
2. Twilio account authorization (Twilio REST)
   isTwilioDialCallerIdAllowed(e164) checks Twilio Incoming Numbers + Outgoing Caller IDs on this Account SID.

Important:

• DB verification and Twilio authorization are related but not identical states.
• Outbound TwiML still sets <Dial callerId="..."> from selected mode; Twilio then decides network-level presentation behavior.
• If Twilio authorization is false and fallback env is off, Ringvoo logs a warning and still sends the selected callerId.

API/route usage in this flow:

• POST /api/user/caller-ids:
  • normalizes E.164
  • enforces cooldown
  • calls Twilio validationRequests.create when needed
  • stores verificationCode, verificationCallSid, expiresAt, and status metadata
• POST /api/twilio/outgoing-caller-id/validation-status:
  • Twilio webhook with VerificationStatus
  • marks verified on success
• GET /api/user/caller-ids:
  • returns caller IDs for modal/dropdown
  • syncs pending rows against Twilio authorization
  • normalizes stale in-flight verification statuses after expiry
• POST /api/twilio/voice/outbound:
  • applies CallFromMode (public, phone, custom)
  • sets <Dial callerId>
  • optionally falls back to TWILIO_PHONE_NUMBER

CallFromMode reference (dialer → TwiML)¶

CallFromMode is sent from DialerPreview to POST /api/twilio/voice/outbound and controls caller ID source:

• public → use TWILIO_PHONE_NUMBER
• phone → use selected owned number (CallFromNumber)
• custom → use selected verified custom caller ID (CallFromNumber)

Server log fields for each outbound attempt:

• callFromMode
• pstnCallerId
• twilioAccountAuthorizesCallerId (for phone/custom)

Practical debugging rule:

• If the callee sees unexpected caller ID, first confirm callFromMode + pstnCallerId in [Twilio Voice] Outbound call TwiML generated.
• If callFromMode: 'public', the dialer sent public mode; this is not Twilio fallback logic.
• If callFromMode: 'custom' and twilioAccountAuthorizesCallerId: false, behavior depends on fallback env and Twilio/carrier handling.

Recent bug note (fixed):

• A UI state desync could occasionally show a selected number label while sending CallFromMode='public'.
• Dialer now performs a pre-connect consistency check:
  • if label matches an owned number, force phone
  • if label matches a verified custom number, force custom
  • else keep public

Custom caller-ID behavior matrix (outbound PSTN)¶

Scenario: custom caller ID removed from Twilio Console¶

Observed in testing: after removing a custom caller ID from Twilio Console, some calls still showed that number to the callee while logs reported twilioAccountAuthorizesCallerId=false.

How to interpret this correctly:

• Treat this as runtime/network carrier behavior, not a guarantee.
• Ringvoo did its part by detecting unauthorized state via Twilio REST.
• Without fallback env, Ringvoo still sends selected custom callerId in TwiML.
• Twilio/carrier may still present that caller ID on some attempts/routes, or may substitute/reject on others.

Operational recommendation:

• If you want deterministic behavior after de-authorization, set
  TWILIO_FALLBACK_CALLER_ID_IF_NOT_TWILIO_AUTHORIZED=true.
• If you want strict policy, keep custom IDs synchronized between Ringvoo and Twilio account state.

Verification modal lifecycle scenarios (custom caller ID)¶

Settlement scenarios for custom caller ID calls¶

Custom caller ID can affect ownership resolution on billing webhooks:

• from may be a custom E.164 that is not mapped in TwilioNumber.
• Owner resolution falls back through Twilio client identities (client:<userId>) and/or parent/child SID correlation paths in lib/call-billing.ts (not CallHold).

Settlement outcomes:

• terminal failed-like statuses (busy, failed, no-answer, canceled) settle as zero-charge
• if Twilio price is delayed, cost-sync job may be required in rare cases (/api/twilio/sync-cost-jobs)

Inbound charging rules¶

Inbound charging is intentionally simple:

• ringing only: no charge
• rejected: no charge
• no-answer: no charge
• busy: no charge
• failed: no charge
• caller hangs up before answer: no charge
• answered inbound call: billable

For a successful answered inbound call:

• answeredAt is stored
• billableDurationSeconds is set from the final/fallback duration
• isBillable = true
• billingStatus = settled after final settlement

Inbound admission + <Dial timeLimit>¶

Inbound TwiML uses the same admission + max talk time approach as outbound, but priced with inbound max retail:

At call start:

• Ringvoo checks wallet.balance > 0 (validateVoiceCallStart)
• Ringvoo estimates inbound max retail $/min (getInboundVoiceEstimateForIso)
• Ringvoo creates a CallSession row for settlement/idempotency
• Ringvoo sets <Dial timeLimit> from computeVoiceDialTimeLimitSeconds (includes low-balance stepping when applicable)

For the currently intended product scope, inbound numbers are expected to be US/Canada numbers purchased inside Ringvoo.

Important distinction:

• <Dial timeLimit> uses a conservative highest inbound retail estimate for the owning number’s country
• Final charge uses the actual Twilio call price for the completed billed leg, then applies the Ringvoo multiplier (CallSettlement reconciles estimated vs final when needed)

Custom caller-ID verification billing note¶

• Verification calls are currently free for users (no wallet debit).
• Twilio verification call cost is currently platform-paid.
• To inspect Twilio cost/duration in terminal for these calls, enable:
  • TWILIO_LOG_CUSTOM_CALLER_ID_COST=true

Inbound settlement and idempotency¶

Final settlement happens in upsertCallAndSettleWallet() in lib/call-billing.ts.

Protection layers:

• one wallet debit per logical call via Transaction.referenceId + source
• inbound wallet debits use source = "inbound_call"
• CallSettlement.callSid is the idempotency anchor for the billed leg; CallSession binds parent/child SIDs for estimated settlement paths
• serializable Prisma transactions are used for settlement
• pg_advisory_xact_lock(hashtext(callSid)) serializes settlement work for the same call SID
• delayed price sync uses CallCostSyncJob.callSid unique retry jobs

This means duplicated or delayed Twilio callbacks should not create:

• duplicate Call rows for the same child billed leg
• duplicate wallet deductions
• duplicate settlement rows for the same priced leg

Client fallback metrics¶

POST /api/twilio/client-call-metrics is best-effort fallback metadata, not the primary source of financial truth.

It helps Ringvoo recover:

• acceptedAt
• endedAt
• fallback duration
• parent/child relation when client-side timing is available earlier than Twilio's final priced callback

Primary use:

• improve answeredAt
• improve fallback duration
• improve settlement recovery if Twilio callback timing is delayed

Expected final DB shape for a good answered inbound call¶

Call:

• direction = 'inbound'
• twilioCallSid = child billed leg
• twilioParentCallSid = parent inbound leg
• status = 'completed'
• answeredAt populated
• duration populated
• billableDurationSeconds > 0
• isBillable = true
• twilioCost > 0
• cost > 0
• billingStatus = 'settled'

CallSession:

• twilioParentCallSid = parent inbound leg
• billableCallSid eventually matches the child billed leg
• status = 'ENDED' after terminal processing

CallSettlement:

• callSid = child billed leg
• amountUsd = Call.cost (retail charged)
• twilioCarrierCostUsd populated when Twilio price is known (may be filled after an estimated-first path)

Transaction:

• type = 'CALL'
• source = 'inbound_call'
• referenceId = Call.twilioCallSid
• amount = Call.cost

Frontend components involved¶

• Dialer UI (toast/audio gates + a few modals like end-of-limit / contacts / caller-id flows):
  • components/marketing/DialerPreview.tsx
• Twilio client lifecycle (online/offline, register, incoming/outgoing wiring):
  • components/dashboard/TwilioProvider.tsx

Voice UX env knobs¶

Full policy + audio map: docs/RINGVOO_SYSTEM_NOTES.md.

Voice log env knobs¶