Telephony

TelephonyProvider abstraction, inbound call flow, and Twilio→Telnyx migration.

Overview

All voice and SMS carrier operations go through the TelephonyProvider interface in src/services/telephony/. Never import Twilio or Telnyx SDKs directly in route handlers.

Deep runbooks: TELNYX_MIGRATION.md, docs/TELNYX_TELEPHONY_DEPLOYMENT_SETUP.md.

Provider selection

Scope	Source
Per virtual number	`VirtualNumber.telephonyProvider` (`twilio` \| `telnyx`) — canonical for voice
Property override	`Property.telephonyProviderOverride` for new number purchases
Global fallback	`TELEPHONY_PROVIDER` env (SMS/comms fallback; deprecated for VNMS)

TELEPHONY_PROVIDER=twilio   # or: telnyx

Inbound call flow

Callbox dials unit's virtual number (E.164).
Carrier webhook → POST /twilio/inbound-call or POST /telnyx/inbound-call.
Core looks up VirtualNumber → Unit → residents.
IVR plays; Knock notifies resident devices.
Approve/deny → DTMF or TeXML redirect → door release.
Call + Approval rows persisted.

Routes are mirrored via createVoiceGatewayRouter() in src/routes/voiceGatewayRouter.ts.

Webhook paths (selected)

Purpose	Twilio	Telnyx
Gate inbound	`/twilio/inbound-call`	`/telnyx/inbound-call`
Call status	`/twilio/call-status`	`/telnyx/call-status`
Approve DTMF	TwiML update	`/telnyx/access-approved-dtmf`
10DLC events	—	`/webhooks/10dlc/events`

Virtual numbers (ADR-001)

Assigned per unit, not per property.
Tenant cap: unitCount + 5 numbers.
Pool management: /api/admin/virtual-numbers/* (see Virtual numbers API).
After release, numbers may enter quarantine before reuse.

Migration status (IN-189)

Phase	Status
TelephonyProvider + TeXML adapter	Complete
Parallel `/telnyx/*` routes	Complete
Per-number provider field	Complete
Production cutover	In progress — see `tools/intry-core-telnyx/CUTOVER.md`

OTP verification still uses Twilio Verify regardless of voice provider.

Virtual numbers API
Webhooks
Support: Virtual number pool (help center)

Last verified: 2026-06-21 (commit 293c4a7)