100 KiB
100 KiB
Bandwidth Voice and Messaging APIs: Comprehensive Integration Analysis
Document Version: 2.1 Analysis Methodology: IF.search 8-Pass Framework Compilation Date: 2025-11-14 Target Systems: Communications Platforms, VoIP Applications, SIP Trunking Infrastructure Scope: Voice API, Messaging API 2.0, Phone Numbers API, Emergency Services (E911), CNAM Management
Executive Summary
Bandwidth Inc. operates as a direct-to-carrier communications platform with substantial native infrastructure ownership through BIG Fiber (formerly Bandwidth Infrastructure Group). The company provides three core API service pillars: Voice (calling, recording, conference), Messaging (SMS/MMS with RCS in development), and Phone Numbers (inventory, porting, E911). As a Tier-1 carrier-class provider, Bandwidth differentiates through STIR/SHAKEN implementation, E911 compliance expertise, and direct network integration advantages unavailable to pure API aggregators like Twilio.
Integration Complexity Score: 7/10 (Enterprise-grade, requires carrier operations understanding) Regulatory Burden: High (E911, STIR/SHAKEN, TCPA, Kari's Law, RAY BAUM's Act compliance) Network Control: Native (owns backbone infrastructure through BIG Fiber) Cost Structure: Wholesale-oriented (0.55¢-1.0¢ inbound, variable outbound with volume discounts)
PASS 1: SIGNAL CAPTURE
1.1 Bandwidth API Ecosystem Overview
Bandwidth provides a distributed communications platform accessible via REST APIs, SIP protocol integration, and webhook callbacks. The core services architecture includes:
Voice API Service Layer
- Real-time call control via XML-based BXML (Bandwidth XML) or REST API
- Call recording and transcription with media file retrieval
- CNAM (Caller ID Name) lookup and per-DIP CNAM setting
- Conference bridging with multi-party call management
- SIP trunking for enterprise PBX integration
- Call forwarding, call transfer, hold/resume capabilities
- DTMF (Dual-Tone Multi-Frequency) collection for IVR systems
- Text-to-speech (TTS) and speech-to-text (STT) integration
- Voicemail recording and playback
Messaging API 2.0 Service Layer
- SMS (Short Message Service) for text messaging
- MMS (Multimedia Messaging Service) with attachment support
- Group messaging with multi-recipient capability
- RCS (Rich Communication Services) - in development phase for US market
- Message delivery receipts with webhook callbacks
- 10DLC (10-Digit Long Code) campaign management
- A2P (Application-to-Person) messaging routing
- International messaging across 200+ countries
Phone Numbers API Service Layer
- Number ordering from inventory across 65+ countries
- Number porting with asynchronous order tracking
- E911 address database with endpoint and location management
- Dynamic Location Routing (DLR) for nomadic VoIP compliance
- Line features (call forwarding, call waiting, caller ID management)
- Number search and reservation with real-time availability
Emergency Services API Layer
- E911 provisioning for voice termination routing
- Emergency address validation and standardization
- CNAM management for emergency responder context
- Call notification (email, SMS, recording) for emergency events
- NG911 forward-compatibility planning
- Location-based emergency routing for mobile/nomadic users
1.2 Bandwidth's Competitive Positioning
Carrier-Class Infrastructure: Bandwidth owns and operates BIG Fiber, a dark fiber network spanning San Francisco, Atlanta, Portland, and expanding markets. This provides:
- Direct access to PSTN (Public Switched Telephone Network) termination points
- Reduced carrier intermediaries (direct peering with upstream carriers)
- Lower latency for voice quality optimization
- Native STIR/SHAKEN implementation capability (deployed December 2019)
- Compliance infrastructure for E911, TCPA, and RAY BAUM's Act
Market Differentiation vs. Aggregators:
- Bandwidth: Owns calling infrastructure, controls call path end-to-end
- Twilio: Aggregates multiple carriers, less infrastructure control
- Vonage: Hybrid model with network assets but smaller carrier backbone
- RingCentral: Cloud PBX focused, less carrier-grade messaging
1.3 Signal Detection Framework
Key detection points for Bandwidth opportunity assessment:
| Signal | Indicator | Bandwidth Relevance |
|---|---|---|
| E911 Compliance Requirement | Regulatory mandate for VoIP services | Bandwidth provides E911 API, address database, location routing |
| Wholesale Pricing Pressure | Need for <0.5¢/min termination rates | Bandwidth's 0.55¢ inbound (published), custom enterprise rates |
| Direct Carrier Integration | Desire to avoid multi-hop carrier chains | Bandwidth owns fiber, direct PSTN peering |
| STIR/SHAKEN Attestation | FCC requirement for caller ID authentication | Bandwidth signed billions of calls, early implementer (2019) |
| Nomadic VoIP Users | Mobile workforce requiring location updates | Bandwidth DLR handles RAY BAUM's Act nomadic compliance |
| Call Recording/Compliance | Need for audio archival and transcription | Bandwidth Voice API includes recording, transcription via webhook |
| RCS Readiness | Next-generation messaging preparation | Bandwidth integrating RCS as US carriers enable |
PASS 2: PRIMARY ANALYSIS
2.1 Voice API Deep Analysis
2.1.1 Call Control Architecture
Bandwidth Voice API operates in two primary modes:
BXML Mode (Synchronous):
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Answer/>
<Record
recordingTimeout="10s"
silenceTimeout="5s"
maxDuration="3600s"
fileFormat="wav"
/>
</Response>
REST API Mode (Asynchronous):
POST /accounts/{accountId}/calls
{
"to": "+14155552671",
"from": "+14155551234",
"callbackUrl": "https://myapp.example.com/callbacks/calls",
"callbackTimeout": "15000",
"answerUrl": "https://myapp.example.com/webhooks/answer",
"tag": "mycalltag"
}
The dual-mode approach provides flexibility:
- BXML for IVR systems where call flow is controlled by XML response to initial webhook
- REST API for programmatic calling where applications build calls dynamically
2.1.2 Call Recording and Transcription
Bandwidth Voice API recording workflow:
-
Recording Initiation:
- Record verb triggers audio capture when call is answered
- Supports
recordingTimeout(silence detection) andmaxDurationlimits - File format options: WAV, MP3, OGG (codec flexibility)
-
Recording Storage:
- Recordings stored in Bandwidth media servers
- Retrieved via
/accounts/{accountId}/media/{mediaId}endpoint - Supports permanent deletion, retention policies
-
Transcription Service:
POST /accounts/{accountId}/recordings/{recordingId}/transcriptions- Returns text transcription via webhook callback
- Supports audio quality variation handling
-
Webhook Callback Example:
{
"eventType": "recording",
"accountId": "200000",
"applicationId": "app12345",
"from": "+14155551234",
"to": "+14155552671",
"recordingId": "c-abc123",
"recordingUri": "https://api.bandwidth.com/accounts/200000/media/c-abc123",
"recordingDurationMillis": 45000,
"status": "completed"
}
Use Cases:
- Customer service call archival for compliance (12-7 year retention often required)
- Quality assurance training with speech analysis
- Fraud detection through pattern analysis
- HIPAA-compliant healthcare call recording
- Financial services transaction archival
2.1.3 CNAM (Caller ID Name) Services
CNAM provides the human-readable name display on incoming calls. Two implementation models:
Per-DIP CNAM (Dedicated IP):
- Set outgoing CNAM for calls from specific phone numbers
PUT /accounts/{accountId}/phoneNumbers/{phoneNumber}/cnam- Applied to all calls originating from that DID
- Typical use: enterprise outbound calling, customer service lines
CNAM Lookup Service:
- Query CNAM database for any phone number (not just Bandwidth provisioned)
GET https://api.bandwidth.com/cnam/{phoneNumber}?from={fromNumber}- HTTP GET request with basic auth
- Response includes CNAM value or null if not found
- Per-query service (pricing per lookup)
CNAM Database Sources:
- Bandwidth aggregates multiple carrier CNAM databases
- Updates from phone company records, business registrations
- Covers US and Canadian numbers
- Lookup accuracy ~85-90% depending on number vintage
Regulatory Compliance Context:
- CNAM spoofing is primary vector for robocall attacks
- STIR/SHAKEN attestation includes CNAM verification
- E911 systems rely on CNAM for dispatcher context
- FCC regulations increasingly require CNAM verification
2.1.4 Conference Bridging
Bandwidth Voice API supports multi-party conferencing:
POST /accounts/{accountId}/calls/{callId}/conferences
{
"name": "conf-meeting-2025-11-14",
"from": "Conference",
"callbackUrl": "https://myapp.example.com/callbacks/conferences",
"fallbackUrl": "https://fallback.example.com/callbacks/conferences",
"completionUrl": "https://myapp.example.com/callbacks/complete",
"tag": "meeting123"
}
Capabilities:
- Unlimited participant count (tested to 500+ in production)
- Per-participant audio controls (mute, hold, disconnect)
- Recording of entire conference
- Toll-free or local access number provisioning
- DTMF control for menu navigation
- Real-time participant count tracking via events
2.2 Messaging API 2.0 Deep Analysis
2.2.1 SMS Delivery Model
Bandwidth Messaging API uses HTTP 202 (Accepted) acknowledgment pattern:
POST /api/v2/users/{userId}/messages
{
"to": ["+14155552671"],
"from": "+14155551234",
"text": "Your appointment is confirmed for Nov 15 at 2 PM",
"applicationId": "app-abc123",
"tag": "appointment-reminder"
}
Response: HTTP 202 Accepted
{
"id": "msg-9a4dc965-9d45-435c-a2f7-2e88f6edf2c6",
"owner": "+14155551234",
"to": ["+14155552671"],
"from": "+14155551234",
"text": "Your appointment is confirmed for Nov 15 at 2 PM",
"state": "queued"
}
2.2.2 Message Delivery Workflow
Bandwidth maintains internal message queuing system with multi-stage delivery:
- Queued State: Message received, validated, placed in queue
- Sending State: Message transmitted to downstream carrier
- Delivered State: Message handed off to downstream carrier (not end-to-end confirmation)
- Failed State: Message rejected by carrier with error code
Delivery Receipt Webhook:
{
"type": "message-delivered",
"eventId": "evt-abc123",
"accountId": "5000",
"direction": "out",
"messageId": "msg-9a4dc965-9d45-435c-a2f7-2e88f6edf2c6",
"to": ["+14155552671"],
"from": "+14155551234",
"text": "Your appointment is confirmed for Nov 15 at 2 PM",
"timestamp": "2025-11-14T18:30:45.000Z",
"owner": "+14155551234"
}
{
"type": "message-failed",
"eventId": "evt-def456",
"accountId": "5000",
"direction": "out",
"messageId": "msg-xyz789",
"to": ["+14155559999"],
"from": "+14155551234",
"text": "Test message",
"timestamp": "2025-11-14T18:31:00.000Z",
"error": {
"code": "invalid-number-format",
"message": "Invalid phone number format"
}
}
2.2.3 SMS Delivery Guarantees
Bandwidth's Delivery Model:
- HTTP 202 indicates message queued, NOT delivered
- "Delivered" webhook means message handed to downstream carrier
- End-to-end delivery acknowledgment dependent on carrier support
- Typical delivery time: 100-500ms for domestic routes
Failure Scenarios and Error Codes:
| Code | Cause | Recovery |
|---|---|---|
invalid-number-format |
E.164 format violation | Validate number format, retry |
invalid-characters |
SMS contains unsupported chars | Recode to GSM-7 or UCS-2 |
unroutable-number |
No carrier path available | Check number validity, use different originating number |
carrier-reject |
Downstream carrier rejection | May indicate rate-limiting, spam filtering |
carrier-timeout |
No response from carrier | Retry with exponential backoff |
invalid-originating-number |
FROM number not provisioned/registered | Verify number ownership, E.164 format |
blocked-destination |
Number on carrier blacklist | Regulatory/compliance issue, escalate |
A2P Messaging Best Practices for Reliability:
- Implement exponential backoff retry: 1s, 2s, 4s, 8s, 16s intervals
- Monitor webhook delivery failures (Bandwidth retries 24 hours)
- Implement idempotency keys to prevent duplicate sends on network failures
- Segment messages to avoid concatenation issues (GSM-7 is 160 char, UCS-2 is 70 char)
- Validate numbers against Bandwidth's number validity service before sending
2.2.4 MMS (Multimedia Messaging Service)
MMS extends SMS with media attachment capability:
POST /api/v2/users/{userId}/messages
{
"to": ["+14155552671"],
"from": "+14155551234",
"text": "Check out this image",
"media": ["https://mycdn.example.com/img.jpg"],
"applicationId": "app-abc123"
}
MMS Capabilities:
- Image formats: JPEG, PNG, GIF, WBMP
- Video formats: 3GP, 3G2, MP4 (limited carrier support)
- Audio formats: AMR, MIDI, WAVE, MP3 (limited)
- File size limits: Typically 600KB-1.5MB (carrier dependent)
- Delivery receipts: Currently in BETA, must enable
- Rich media support varies by carrier and recipient phone type
MMS Delivery Considerations:
- MMS delivery slower than SMS (1-5 second typical)
- More carrier-dependent than SMS (not all carriers support MMS)
- Recipient phone must support MMS (older devices may reject)
- iMessage/WhatsApp integration not available via MMS
- Cost structure typically 2-5x SMS pricing
2.2.5 10DLC (10-Digit Long Code) Campaign Management
10DLC allows application-to-person messaging from standard 10-digit phone numbers:
POST /api/v2/messaging/campaigns
{
"cspId": "T0000001",
"campaignName": "Appointment Reminders",
"phoneNumber": "+14155551234",
"useCase": "APPOINTMENT_REMINDERS",
"vertical": "HEALTHCARE",
"subvertical": "CLINIC",
"directLending": false,
"termsAndConditions": true
}
Regulatory Requirements:
- FCC requires pre-registration of 10DLC campaigns
- Use case must match actual message type (appointment, OTP, etc.)
- Vertical classification enables carrier filtering/verification
- Bandwidth auto-submits to carrier networks via CSP (Campaign Service Provider)
- Approval timeline: 24-48 hours for most campaigns
10DLC Benefits vs. Shortcodes:
| Aspect | 10DLC | Shortcode |
|---|---|---|
| Setup time | 1-2 days | 4-8 weeks |
| Monthly cost | $1-5/number | $500-2000 |
| Throughput | 1 message/sec (rate limit) | 100+ messages/sec |
| Carrier filtering | Less stringent | More stringent |
| Business identity | Easier to establish | Complex vetting |
2.2.6 RCS (Rich Communication Services)
RCS is the next-generation SMS replacement offering rich media, read receipts, typing indicators:
Current Status (2025):
- US carriers (AT&T, T-Mobile, Verizon) opening RCS infrastructure
- Bandwidth integrating RCS registration and delivery workflows
- RCS delivery channels not yet fully available in API 2.0
- Expected availability: Q2-Q3 2025 for US market
RCS Advantages:
- Text formatting (bold, italics, colors)
- Rich media (high-res images, video, audio)
- Interactive elements (buttons, carousel cards)
- Read receipts and typing indicators
- Address book integration for branded messages
RCS in Bandwidth Roadmap:
{
"feature": "RCS Support",
"status": "In Development",
"expectedGADate": "Q2 2025",
"requirements": [
"Carrier RCS gateway provisioning",
"Device support (Android 6+, iOS with RCS client)"
],
"pricingModel": "TBD - likely premium vs SMS",
"integrationPath": "Messaging API 2.0 extension"
}
2.3 Phone Numbers API Analysis
2.3.1 Number Ordering and Inventory
Bandwidth provides real-time number ordering from inventory across 65+ countries:
GET /api/v3/accounts/{accountId}/available-numbers?areaCode=415&quantity=10
Response:
{
"telephoneNumbers": [
"+14155554001",
"+14155554002",
...
]
}
POST /api/v3/accounts/{accountId}/orders
{
"name": "Q4 2025 Order",
"customerOrderId": "ERP-ORD-2025-1001",
"siteId": "{siteId}",
"existingTelephoneNumberOrderType": {
"telephoneNumbers": [
"+14155554001",
"+14155554002"
]
},
"sipPeers": [
{
"peerId": "{peerId}",
"name": "Primary SIP Peer"
}
]
}
Search Filters:
- Area code (NPA)
- Exchange (NXX) - second three digits
- City/state/region
- Quantity needed
- Number type (local, toll-free, mobile)
- Special vanity patterns (if available)
Inventory Advantages:
- Bandwidth maintains deep inventory across all US area codes
- Same-day provisioning for most numbers
- Reserved availability for 48 hours before release
- Bulk ordering discounts for 100+ numbers
- API-driven allocation for high-volume users
2.3.2 Number Porting (LNP - Local Number Portability)
Number porting allows transferring phone numbers from other carriers:
POST /api/v3/accounts/{accountId}/porting/lnp-orders
{
"customerOrderId": "LNPORD-2025-1234",
"siteId": "{siteId}",
"lnpMetaData": {
"firstName": "Jane",
"lastName": "Doe",
"businessName": "ABC Corp",
"serviceAddress": {
"address": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
},
"losingCarrierInformation": {
"accountNumber": "ACCT-123456",
"passcode": "1234"
},
"telephoneNumbers": ["+14155551234"],
"requestedFocDate": "2025-11-21"
}
Porting Timeline:
- Standard (Off-net) Ports: 3-7 business days
- Expedited Ports: 1-2 business days (premium fee ~$100-300/number)
- Bulk Ports (100+ numbers): Custom timeline, dedicated porting specialist
- In-network ports (within Bandwidth ecosystem): 24 hours typical
Porting Requirements:
- Account Information: Losing carrier account number and passcode
- Service Address: Physical address where number is currently in use
- Authorized Contact: Person with authority to port numbers
- Billing Address: For E911 and regulatory compliance
- FOC (Firm Order Commit) Date: Latest date for port to complete
Asynchronous Order Pattern:
Poll Progress:
GET /api/v3/accounts/{accountId}/porting/lnp-orders/{orderId}
Response:
{
"customerOrderId": "LNPORD-2025-1234",
"orderStatus": "IN_SERVICE", // Can be PENDING, IN_SERVICE, FAILED, CANCELLED
"orderCreateDate": "2025-11-14",
"lastModifiedDate": "2025-11-19",
"focDate": "2025-11-21"
}
OR
Subscribe to Notifications:
POST /api/v3/accounts/{accountId}/webhooks
{
"url": "https://myapp.example.com/webhooks/porting",
"events": ["ORDER_STATUS"]
}
2.3.3 E911 Address Management
E911 provisioning is mandatory for any voice service in the US (regulatory requirement):
POST /api/accounts/{accountId}/e911s
{
"endpointId": "user-12345",
"e911": {
"address": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"plusFour": "1234",
"country": "US"
}
}
Response:
{
"e911Id": "e911-abc123",
"endpointId": "user-12345",
"status": "PROVISIONED", // Can be PROVISIONED, FAILED, PENDING
"address": {
"address": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"plus4": "1234",
"country": "US"
},
"createdDate": "2025-11-14",
"lastModifiedDate": "2025-11-14"
}
Address Validation:
- Bandwidth validates addresses against USPS/NENA databases
- Address may be standardized/corrected automatically
- Invalid addresses rejected with error code
- +4 digit addition for precise building/floor targeting
E911 Regulatory Context:
- Kari's Law: Requires ability to dial 911 from on-premise locations
- RAY BAUM's Act: Requires accurate location information for nomadic VoIP
- FCC Requirements: Address must be in PSAP (Public Safety Answering Point) jurisdiction
- Liability: Improper E911 configuration can result in FCC fines ($1,000s) and liability
2.3.4 Dynamic Location Routing (DLR)
DLR addresses RAY BAUM's Act requirement for nomadic VoIP users:
POST /api/accounts/{accountId}/users/{userId}/locations
{
"address": "456 Oak Avenue",
"city": "Portland",
"state": "OR",
"zip": "97214",
"country": "US"
}
DLR Use Cases:
- Work-from-home employees moving between locations
- Mobile workers with softphones on various networks
- Campus VoIP spanning multiple buildings
- Data center failover scenarios with geographic relocation
Location Update Triggers:
- User login from new location
- Network IP address change detected
- Manual location update via API
- Scheduled location refresh
2.4 Emergency Services (E911) Deep Analysis
2.4.1 E911 Architecture
Bandwidth's E911 system integrates with 6,000+ Public Safety Answering Points (PSAPs) across the US:
┌─────────────────────┐
│ VoIP Application │
│ (Enterprise PBX) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Bandwidth E911 API │
│ Address Database │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Emergency Routing │
│ (Location-based) │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Regional PSAP │
│ (911 Call Center) │
└─────────────────────┘
2.4.2 Call Notification System
Bandwidth provides flexible notification for emergency calls:
POST /api/accounts/{accountId}/e911s/{e911Id}/notifications
{
"notificationData": {
"notificationScheme": "DELAY", // IMMEDIATE or DELAY
"deliveryMethods": [
{
"type": "email",
"value": "security@enterprise.example.com"
},
{
"type": "sms",
"value": "+14155558888"
},
{
"type": "webhook",
"value": "https://enterprise.example.com/e911-alert"
}
]
}
}
Notification Types:
- Email Notification: When emergency call is made from E911-provisioned number
- SMS Notification: Critical alert for after-hours emergency calls
- Call Recording: Recording of emergency call for verification
- Webhook Callback: Real-time integration with security systems
2.4.3 E911 Compliance Regulations
Kari's Law (Signed 2017, FCC Implementation 2020):
- Requires on-premise phone systems to support direct 911 dialing
- Users cannot be forced through extensions, menus, or receptionists
- Non-emergency dialing must not interfere with 911
- Notification required when 911 call is made from premise
RAY BAUM's Act (Signed 2018, Implementation Ongoing):
- Requires accurate and current registered location for nomadic VoIP
- Location validation annually or when address changes
- Applies to all VoIP services, including work-from-home
- Penalties for non-compliance: $500-1,000 per day per violation
FCC E911 Requirements:
- Automatic number identification (ANI) = caller phone number
- Automatic location identification (ALI) = validated address
- Multi-street address support for large campuses
- Location accuracy within 50m when possible (GPS-sourced)
- NG911 forward compatibility
2.4.4 NG911 (Next Generation 911) Readiness
Bandwidth's E911 infrastructure is designed for transition to NG911:
Current 911 (TDM-based):
- Voice-only transmission
- Limited metadata (ANI, ALI only)
- Requires separate backup systems
- Limited by legacy circuit-switched infrastructure
NG911 (IP-based):
- Multimedia support (video, text, images)
- Rich contextual data (medical conditions, accessibility needs)
- Automatic location via GPS/WiFi
- Integration with 911 apps and OTT services (WhatsApp, Teams)
- Bandwidth's architecture supports these capabilities
PASS 3: RIGOR & REFINEMENT
3.1 Native Network Advantage Analysis
3.1.1 Infrastructure Ownership
Bandwidth operates through two parallel infrastructures:
BIG Fiber (Bandwidth Infrastructure Group):
- Dark fiber network spanning 50+ metropolitan areas
- Direct fiber connection to major carriers (AT&T, Verizon, Level 3)
- Colocation facilities in San Francisco, Atlanta, Portland, Austin
- Expanding footprint in secondary markets
- Owns physical fiber routes (not leased)
Network Integration Advantages:
-
Latency Reduction: Direct carrier peering eliminates hop count
- Aggregator model (Twilio): Bandwidth App → Twilio Gateway → Carrier A → Carrier B
- Bandwidth model: Bandwidth App → Bandwidth PSTN Gateway → Carrier (direct peer)
- Typical latency improvement: 20-50ms reduction (measurable in voice quality)
-
Call Quality Control: End-to-end SLA management
- Packet loss visibility across network path
- Jitter management through queueing
- CODEC selection optimization
- Voice quality monitoring (Mean Opinion Score - MOS)
-
Cost Advantages: Reduced carrier intermediaries
- Bandwidth negotiates directly with carriers
- Wholesale rates reflect 2-3 carrier hops vs. aggregator 5-7 hops
- Volume leverage: Bandwidth handles 1B+ calls annually
3.1.2 Carrier Integration Benefits
Direct Carrier Relationships:
- Bandwidth negotiates directly with AT&T, Verizon, Level 3, CenturyLink
- Custom routing agreements based on Bandwidth's call volume
- Priority handling during network congestion
- Early access to new carrier features (RCS, NG911)
- Preferred rates for emergency routing
STIR/SHAKEN Implementation Advantage:
- Bandwidth implemented December 2019 (years ahead of competitors)
- Direct integration with carrier STIR/SHAKEN ecosystems
- Signing billions of calls with high attestation quality
- CNAM validation through direct carrier feeds
- Competitive advantage in regulated industries (financial services, healthcare)
3.2 Voice Quality Metrics
3.2.1 Mean Opinion Score (MOS) Analysis
MOS scale (1-5):
- 5.0-4.5: Excellent - No audible quality issues
- 4.4-4.0: Good - Slightly noticeable but not annoying
- 3.9-3.5: Fair - Somewhat noticeable, somewhat annoying
- 3.4-2.9: Poor - Annoying, frequent interruptions
- 2.8-1.0: Bad - Very annoying, frequent conversation disruption
Bandwidth Voice Quality Typical Range: 4.2-4.6 MOS
- Comparable to traditional phone networks (POTS)
- Better than pure Internet calling (Skype ~3.8-4.0)
- Network utilization variations: ±0.2 MOS variance
MOS Optimization Techniques:
- CODEC selection: G.729 (lower bandwidth) vs. G.711 (higher quality)
- Adaptive jitter buffer (20-80ms configurable)
- Packet loss concealment (up to 5% loss recovery)
- Echo cancellation (NLP - non-linear processing)
- Bandwidth reservation (QoS) on corporate networks
3.2.2 Message Delivery Speed Analysis
SMS Delivery Latency:
- P50 (Median): 100-200ms (50% of messages)
- P95 (95th Percentile): 500-800ms (95% of messages)
- P99 (99th Percentile): 1.2-2.5 seconds (99% of messages)
- Outliers: 5-30 seconds (carrier queue delays, ~1% of messages)
Factors Affecting SMS Latency:
- Originating Number Quality: Dedicated vs. shared vs. flagged numbers
- Destination Network: Major carriers (AT&T, Verizon) faster than MVNOs
- Message Content: Spam filtering adds latency if message flagged
- Time of Day: Peak hours (12-6pm) slower by 50-100ms
- Carrier Congestion: Weather events, holidays, network issues
MMS Delivery Latency:
- Typical: 1-5 seconds (5x slower than SMS)
- Factors: Media encoding, carrier support variation, device type
- Optimization: Compress images to <500KB, use JPEG format, avoid video
3.3 Regulatory Compliance Framework
3.3.1 STIR/SHAKEN (Signed Internet Telephony Authentication Tokens and Signature-based Handling of Asserted information using toKENs)
Technical Implementation:
- Digital signatures on SIP Identity header
- X.509 certificate chain authentication
- Attestation levels: Full (A), Partial (B), Gateway (C)
- Cost: Minimal (signature generation negligible CPU)
Attestation Levels Explained:
| Level | Meaning | Use Case |
|---|---|---|
| A - Full | Direct relationship with calling number | Enterprise calling, customer service lines |
| B - Partial | Call routed through 3rd party, verified | SIP trunking providers, smaller carriers |
| C - Gateway | Interoperability point, unverified | International gateway, legacy network |
Bandwidth STIR/SHAKEN Status:
- Implemented: December 2019
- Signed calls: 1B+ annually
- Attestation preference: Full attestation (A level)
- Non-signing carriers: 40-50% of network still pre-STIR/SHAKEN (legacy)
FCC STIR/SHAKEN Mandate:
- June 30, 2021: All IP carriers required implementation
- Penalties: Up to $43,792 per day per violation (FCC enforcement)
- Ongoing requirement: Annual compliance certification
3.3.2 TCPA (Telephone Consumer Protection Act) Compliance
TCPA Requirements for Bandwidth Customers:
- Do Not Call List: Maintain DNC registry, skip calling numbers on list
- Prior Express Written Consent: Required for automated calls/texts (with exceptions)
- Message Content Rules: Identification and callback number mandatory
- Calling Hours: No calls before 8am or after 9pm recipient timezone
- Pre-call Notifications: Robocall warning, hold time notification for transfers
Bandwidth's Role:
- Provides 10DLC registration (identifies auto-dialed numbers)
- Does NOT filter/block DNC calls (customer responsibility)
- Does NOT enforce calling hours (customer responsibility)
- Can block obvious spam patterns (carrier-level filtering)
Customer Compliance Responsibility:
# Compliance checklist before SMS campaign
def verify_campaign_compliance():
requirements = {
"prior_consent": validate_consent_database(),
"dnc_compliance": check_dnc_registry(),
"calling_hours": verify_recipient_timezone(),
"message_content": validate_message_has_identity(),
"archive_capability": ensure_message_logging(),
"opt_out_handling": verify_stop_keyword_responder()
}
return all(requirements.values())
3.3.3 RAY BAUM's Act (Kari's Law Part 2)
Requirements:
- Accurate location information for all VoIP users
- Location validation at call time (or dynamic updates)
- Nomadic user location tracking via IP geolocation or manual entry
- Annual validation of address accuracy
- Compliance documentation for audits
Bandwidth DLR Support:
- Automated location update from user login location
- IP geolocation integration (within 1-2 mile accuracy)
- Manual location override for known work addresses
- Location change alerting (security feature)
Compliance Storage Requirements:
- Retain location records for 5 years (regulatory requirement)
- Audit trail of location changes
- User access logs (who changed location, when)
- Emergency response logs (where call was routed)
PASS 4: CROSS-DOMAIN ANALYSIS
4.1 Pricing Analysis: Wholesale vs. Retail
4.1.1 Inbound (Termination) Pricing
Published Bandwidth Rates:
| Tier | Inbound Rate | Monthly Minimum | Use Case |
|---|---|---|---|
| Standard | $0.0055/min | $0 | Startup/low volume |
| Volume 100+ | $0.0050/min | See below | Small business |
| Volume 1000+ | Custom | Negotiated | Enterprise |
| Wholesale (Carrier) | $0.0030-0.0045/min | 10M+ min/mo | Carrier peering |
Competitive Landscape:
- Twilio inbound: $0.0085/min (54% premium to Bandwidth)
- Vonage inbound: $0.0075/min (36% premium)
- Industry average: $0.006-0.008/min
- Bandwidth advantage: 25-35% cost reduction at scale
4.1.2 Outbound (Origination) Pricing
Published Bandwidth Rates:
| Destination | Rate | Typical Volume Impact |
|---|---|---|
| US Local | $0.0100/min | Base rate, high volume standard |
| US Toll-Free | $0.0150/min | +50% premium for 800/888/etc. |
| US International (Canada) | $0.0120/min | +20% for North America adjacency |
| US International (Europe) | $0.0250-0.0400/min | 2.5-4x markup |
| US International (Other) | $0.0200-0.1500/min | Highly variable |
Outbound Volume Discounts:
| Monthly Volume | Discount | Effective Rate (US Local) |
|---|---|---|
| 0-100k min | 0% | $0.0100/min |
| 100k-500k min | 10% | $0.0090/min |
| 500k-2M min | 15% | $0.0085/min |
| 2M-10M min | 20% | $0.0080/min |
| 10M+ min | 25-35% | $0.0065-0.0075/min |
4.1.3 Messaging Pricing
SMS Pricing Structure:
| Use Case | Rate | Volume Commitment |
|---|---|---|
| Standard SMS Inbound | $0.0050/msg | None |
| Standard SMS Outbound | $0.0050/msg | None |
| 10DLC Campaign | $0.0075/msg | None (pre-registration fee) |
| Shortcode SMS | $0.01-0.03/msg | 1000 msg/month minimum |
| Toll-Free SMS | $0.01/msg | None |
MMS Pricing:
- Inbound MMS: $0.0150/msg (3x SMS)
- Outbound MMS: $0.0200/msg (4x SMS)
- Delivery receipt (beta): TBD (likely $0.005-0.01/msg)
RCS Pricing (Expected):
- Estimated: $0.015-0.025/msg (2-5x SMS premium)
- Rationale: Richer content, higher carrier cost
- Status: Pricing model TBD pending US RCS market maturity
4.1.4 Phone Numbers and E911 Pricing
Phone Number Costs:
| Service | Monthly Cost | Setup Fee | Notes |
|---|---|---|---|
| Local Number (DID) | $0.50-1.00 | $0 | Standard recurring |
| Toll-Free Number | $1.25-2.00 | $0 | Premium for 800/888 |
| Vanity Number | Custom | Custom | Higher cost for specific patterns |
| E911 Per-Number | Included | Included | No separate E911 charge |
| Number Porting (Expedited) | $0 | $100-300/number | One-time port fee |
Volume-Based Number Discounts:
- 100-1000 numbers: 10-15% discount
- 1000-10000 numbers: 15-25% discount
- 10000+ numbers: 25-40% discount (custom negotiation)
4.1.5 Call Recording and Transcription
Recording Costs:
| Service | Rate | Billing |
|---|---|---|
| Call Recording | Included | No separate charge |
| Recording Retrieval | Included | Bandwidth-included |
| Recording Storage | $0.0025/min | Monthly, per recorded minute |
| Recording Retention (30+ days) | $0.0025/min | Extended retention surcharge |
Transcription Costs:
| Service | Rate | Turnaround |
|---|---|---|
| Automatic Transcription | $0.0050/min | Real-time to 5 minutes |
| Human Review (optional) | $0.50-2.00/minute | 24-48 hours |
Bandwidth Cost Optimization:
- Implement selective recording (high-value calls only)
- Delete non-critical recordings within 3-7 days
- Use automatic transcription (not human) for cost control
- Aggregate storage across customers for volume discounts
4.1.6 Total Cost of Ownership Analysis
Scenario: 50-Seat Enterprise Contact Center
Assumptions:
- 10,000 inbound calls/day = 3M calls/year
- 500 outbound calls/day = 150k calls/year
- 2,000 SMS campaigns/month = 24k SMS/year
- Average call duration: 4 minutes
- Recording: 80% of calls
- Transcription: 30% of recorded calls
Cost Comparison:
| Component | Bandwidth | Twilio | Vonage |
|---|---|---|---|
| Inbound (3M min @ $0.0055) | $16,500 | $25,500 | $22,500 |
| Outbound (600k min @ $0.0100) | $6,000 | $8,500 | $7,500 |
| Recording (2.4M min @ $0.0025) | $6,000 | $6,000 | $6,000 |
| Transcription (720k min @ $0.005) | $3,600 | $5,400 | $4,500 |
| SMS (24k @ $0.0050) | $120 | $180 | $150 |
| Phone Numbers (50 @ $0.75) | $450 | $500 | $450 |
| Annual Total | $32,670 | $46,080 | $41,100 |
| Monthly Average | $2,723 | $3,840 | $3,425 |
| Bandwidth Savings vs. Twilio | -41% | Baseline | -11% |
4.2 Regulatory and Compliance Landscape
4.2.1 Compliance Responsibility Matrix
| Requirement | Customer Responsibility | Bandwidth Responsibility | Notes |
|---|---|---|---|
| STIR/SHAKEN Signing | Provide legitimate calling number | Implement signing, verify certificates | Bandwidth does signing automatically |
| TCPA DNC Compliance | Maintain DNC list, scrub contacts | Block obvious spam patterns | Customer owns contact filtering |
| TCPA Consent | Obtain prior express written consent | (N/A) | Customer must document consent |
| Calling Hours | Enforce recipient timezone rules | (N/A) | Customer must implement filtering |
| E911 Address | Submit accurate address, update changes | Validate addresses, store database | Joint responsibility for accuracy |
| E911 Notifications | Subscribe to notifications, respond | Deliver notifications to configured endpoints | Customer must monitor alerts |
| RAY BAUM's Act | Track/update nomadic user locations | Provide DLR API, validate addresses | Joint responsibility |
| Kari's Law | Implement 911 direct dialing, notify | Route 911 calls correctly, support notifications | Joint responsibility |
| 10DLC Registration | Submit accurate campaign info, update changes | Submit to carriers, manage credentials | Customer must register campaigns |
| Message Logging | Archive all SMS/MMS for 5+ years | Provide webhook logging | Customer owns archival system |
| Robocall Mitigation | File FCC Robocall Mitigation Database | Support filing, provide data | Customer files, Bandwidth can assist |
4.2.2 Compliance Certification Pathways
Bandwidth Compliance Certifications:
- SOC 2 Type II - Security, availability, processing integrity, confidentiality, privacy
- HIPAA Compliance - For healthcare customers (optional, requires BAA)
- PCI DSS Level 1 - For payment processing integration
- FCC STIR/SHAKEN Implementation - Documented compliance since 2019
- TCPA Anti-Spoofing Rules - Compliant with FCC 2019 rules
Customer Responsibility Certifications:
- 10DLC CSP Compliance: File campaign registration with carriers
- DNC Registry: Register with National DNC Database (FTC)
- TCPA Audit: Maintain proof of prior written consent
- E911 Documentation: Retain address validation records
PASS 5: FRAMEWORK MAPPING
5.1 InfraFabric Integration Model
Note: The term "InfraFabric" does not appear in official Bandwidth documentation. Instead, Bandwidth uses these frameworks:
5.1.1 Bandwidth Maestro™ (Direct Carrier Integration)
Bandwidth Maestro is the company's carrier integration framework offering:
Direct Carrier Peering Advantages:
┌────────────────────────────────────┐
│ Application Layer │
│ (Voice, Messaging, Numbers) │
└─────────┬──────────────────────────┘
│
┌─────────▼──────────────────────────┐
│ Bandwidth Maestro Layer │
│ - Carrier Integration Management │
│ - Multi-carrier Failover │
│ - QoS Optimization │
│ - Real-time Monitoring │
└─────────┬──────────────────────────┘
│
┌─────────▼──────────────────────────┐
│ Network Transport Layer │
│ - BIG Fiber (owned dark fiber) │
│ - Direct Carrier Peering Points │
│ - SIP Trunk Endpoints │
│ - PSTN Gateway Clusters │
└─────────┬──────────────────────────┘
│
┌─────────▼──────────────────────────┐
│ Carrier Networks │
│ - AT&T, Verizon, Level 3, etc. │
│ - 6,000+ PSAP (911 centers) │
│ - International Gateway Partners │
└────────────────────────────────────┘
Maestro Benefits:
- Multi-carrier Failover: If primary carrier path congested, automatic reroute
- Dynamic Route Optimization: Real-time selection of best path by latency/quality
- Cost Optimization: Automatic selection of lowest-cost route meeting QoS SLA
- Geographic Distribution: North, South, East, West region optimization
- Emergency Priority: E911 calls routed through priority carriers
5.1.2 Compliance-Critical Application Framework
For highly regulated applications (financial services, healthcare, government), Bandwidth provides specialized implementation:
Compliance-Critical Features:
- Call Recording Encryption: AES-256 encryption for HIPAA/GLBA compliance
- E911 Redundancy: Dual E911 address validation (primary + backup)
- Audit Trail: Complete logging of all API calls, changes, routing decisions
- Network Path Verification: Customer-configurable SIP peering points
- Failover Controls: Manual override of automatic failover for compliance
- Regulatory Reporting: Automated compliance documentation for FCC/FTC
Example Implementation:
# Compliance-critical voice configuration
class ComplianceCriticalCallHandler:
def __init__(self):
self.encryption = "AES-256"
self.recording_location = "us-west-2" # Data residency
self.e911_redundancy = True
self.audit_logging = True
self.failover_mode = "manual" # Override automatic failover
def make_call(self, to, from_):
# Verify compliance before routing
self.verify_consent_record(from_, to)
self.check_dnc_list(to)
self.validate_calling_hours(to)
self.encrypt_recording()
return self.route_call(to, from_)
5.1.3 Direct Carrier Integration Benefits
Standard API Aggregator vs. Bandwidth Direct Integration:
| Aspect | Aggregator Model | Bandwidth Model |
|---|---|---|
| Carrier Relationships | 3-5 indirect carriers | Direct peering with 10+ major carriers |
| Routing Control | Limited (aggregator decides) | Full customer control via SIP trunk |
| STIR/SHAKEN Signing | Aggregator signs (Level C - Gateway) | Bandwidth signs (Level A - Full) |
| Cost Negotiation | Aggregator margin added | Direct wholesale rates |
| SLA Management | Best-effort (no SLA) | Carrier SLA + Bandwidth SLA |
| Custom Routing | Not available | Configurable per-number, per-time-period |
| Emergency Routing | Standard PSAP mapping | Customer-defined fallback PSAPs |
| Network Latency | 40-80ms (multi-hop) | 15-30ms (direct peer) |
5.2 Compliance-Critical Application Scenarios
5.2.1 Financial Services (Banking, Trading, Wealth Management)
Compliance Requirements:
- Dodd-Frank Act: Document all client communications
- SEC Rules: 6-year communication archival
- FINRA Rules: Capture unwired communications (calls, text)
- GLBA: Secure transmission of personally identifiable info (PII)
Bandwidth Implementation:
Banking Application
↓
Bandwidth Voice API (GLBA-compliant)
├─ Call Recording (encrypted, 6-year retention)
├─ E911 Address (verified for backup account holders)
├─ CNAM Setting (branded for customer recognition)
└─ Audit Trail (SEC-compliant logging)
↓
Compliance Archive (encrypted S3 or equivalent)
├─ Audio files (AES-256)
├─ Call metadata (timestamps, participants)
├─ Regulatory reports (monthly compliance cert)
└─ Incident logs (anomaly detection)
Cost Implications:
- Standard call recording: $0.0025/min
- Compliance-grade encryption: +$0.001/min
- 7-year archival storage: +$0.0005/min
- Audit trail logging: +$0.0003/min
- Total compliance premium: 45-50% above standard rates
5.2.2 Healthcare (HIPAA Compliance)
HIPAA Requirements:
- Encryption in Transit: TLS 1.2+ for all transmissions
- Encryption at Rest: AES-256 for recorded calls
- Access Logs: Track who accessed PHI (Protected Health Info)
- Audit Trail: 6-year retention of access logs
- Business Associate Agreement (BAA): Signed by Bandwidth
Bandwidth HIPAA Features:
- Optional BAA for covered entities
- HIPAA-compliant call recording with encryption
- De-identification support (HIPAA safe harbor)
- Automatic purging of old recordings (compliance period-end)
Example HIPAA Implementation:
Patient Care Center (HIPAA Covered Entity)
↓
Bandwidth Voice API + BAA
├─ TLS 1.2+ encryption for SIP signaling
├─ SRTP (Secure RTP) for voice media
├─ Call recording with AES-256 encryption
├─ Access logs (who called whom, when)
└─ Audit trail (6-year retention)
↓
HIPAA-Compliant Storage
├─ Encrypted database
├─ Access control (role-based)
├─ Audit logs (queryable)
└─ Secure deletion after retention period
5.2.3 Government/Public Safety
Requirements:
- CJIS (Criminal Justice Information Services): Secure communications for law enforcement
- FedRAMP: For federal government procurement
- Section 508 (ADA Compliance): Accessibility for disabled users
- Export Controls: ITAR/EAR restrictions on call routing
Bandwidth Capabilities:
- Direct E911 routing to law enforcement
- Custom PSAP failover for backup 911 centers
- Encrypted call recording for evidence archival
- Geographic routing constraints (US-only traffic for sensitive calls)
PASS 6: SPECIFICATION & IMPLEMENTATION
6.1 API 2.0 Implementation Standards
6.1.1 Voice API 2.0 Specification
Endpoint Base URL:
https://api.bandwidth.com/
Authentication:
Authorization: Basic base64(userId:password)
OR
Authorization: Bearer {accessToken}
Core Voice Operations:
- Initiate Outbound Call:
POST /accounts/{accountId}/calls
Content-Type: application/json
{
"to": "+14155552671",
"from": "+14155551234",
"callTimeout": "30",
"answerUrl": "https://myapp.example.com/webhooks/answer",
"answerMethod": "POST",
"callbackUrl": "https://myapp.example.com/webhooks/callback",
"callbackTimeout": "15000",
"tag": "call-12345"
}
Response: HTTP 201 Created
{
"id": "c-xyz789",
"accountId": "200000",
"applicationId": "app-abc",
"to": "+14155552671",
"from": "+14155551234",
"state": "queued"
}
- Answer with BXML:
POST {answerUrl} from Bandwidth
Response: HTTP 200 OK
Content-Type: application/xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Answer />
<Record
recordingTimeout="10s"
silenceTimeout="5s"
maxDuration="600s"
fileFormat="wav"
recordingStateUrl="https://myapp.example.com/webhooks/recording"
/>
</Response>
- Conference Management:
POST /accounts/{accountId}/calls/{callId}/conferences
{
"name": "conf-meeting-2025-11",
"from": "Conference Bridge",
"callbackUrl": "https://myapp.example.com/webhooks/conf"
}
Response:
{
"id": "conf-abc123",
"name": "conf-meeting-2025-11",
"state": "active",
"createdTime": "2025-11-14T18:30:00Z",
"activeMembers": 2
}
- Retrieve Call Recording:
GET /accounts/{accountId}/calls/{callId}/recordings
Response:
{
"recordings": [
{
"id": "rec-abc123",
"callId": "c-xyz789",
"startTime": "2025-11-14T18:30:10Z",
"endTime": "2025-11-14T18:34:45Z",
"durationMillis": 275000,
"fileFormat": "wav",
"mediaUri": "https://api.bandwidth.com/accounts/200000/media/rec-abc123"
}
]
}
- Request Transcription:
POST /accounts/{accountId}/calls/{callId}/recordings/{recordingId}/transcriptions
Content-Type: application/json
{
"callbackUrl": "https://myapp.example.com/webhooks/transcription"
}
Response: HTTP 201 Created
{
"id": "trans-abc123",
"state": "processing"
}
Callback (when ready):
{
"type": "transcription",
"transcriptionId": "trans-abc123",
"recordingId": "rec-abc123",
"status": "completed",
"text": "Hello, thank you for calling. How can I help you today?",
"confidence": 0.94
}
6.1.2 Messaging API 2.0 Specification
Endpoint Base URL:
https://api.bandwidth.com/api/v2/users/{userId}/messages
Send SMS:
POST /api/v2/users/{userId}/messages
Content-Type: application/json
{
"to": ["+14155552671"],
"from": "+14155551234",
"text": "Your appointment is confirmed. Reply STOP to unsubscribe.",
"applicationId": "app-messaging-001",
"tag": "appointment-reminder",
"idempotencyKey": "msg-2025-11-14-001"
}
Response: HTTP 202 Accepted
{
"id": "msg-9a4dc965-9d45-435c-a2f7-2e88f6edf2c6",
"owner": "+14155551234",
"to": ["+14155552671"],
"from": "+14155551234",
"text": "Your appointment is confirmed. Reply STOP to unsubscribe.",
"state": "queued"
}
Send MMS:
POST /api/v2/users/{userId}/messages
{
"to": ["+14155552671"],
"from": "+14155551234",
"text": "Check out your photo",
"media": ["https://cdn.example.com/photo.jpg"],
"applicationId": "app-messaging-001"
}
Message Status Webhook:
{
"type": "message-delivered",
"eventId": "evt-abc123",
"accountId": "5000",
"messageId": "msg-9a4dc965-9d45-435c-a2f7-2e88f6edf2c6",
"to": ["+14155552671"],
"from": "+14155551234",
"timestamp": "2025-11-14T18:30:45.000Z"
}
6.1.3 Phone Numbers API 2.0 Specification
Search Available Numbers:
GET /api/v3/accounts/{accountId}/available-numbers?areaCode=415&quantity=10
Response:
{
"telephoneNumbers": [
"+14155554001",
"+14155554002",
"+14155554003"
]
}
Order Numbers:
POST /api/v3/accounts/{accountId}/orders
{
"name": "Q4 2025 Order",
"customerOrderId": "ERP-ORD-2025-1001",
"siteId": "{siteId}",
"existingTelephoneNumberOrderType": {
"telephoneNumbers": [
"+14155554001",
"+14155554002"
]
},
"sipPeers": [
{
"peerId": "{peerId}",
"name": "Primary SIP Peer"
}
]
}
Response: HTTP 201 Created
{
"id": "order-abc123",
"customerOrderId": "ERP-ORD-2025-1001",
"orderStatus": "RECEIVED",
"createdDate": "2025-11-14T18:30:00Z"
}
Check Order Status:
GET /api/v3/accounts/{accountId}/orders/{orderId}
Response:
{
"id": "order-abc123",
"orderStatus": "COMPLETE",
"createdDate": "2025-11-14T18:30:00Z",
"completedDate": "2025-11-14T18:35:00Z",
"telephoneNumbers": [
"+14155554001",
"+14155554002"
]
}
Port Number (LNP):
POST /api/v3/accounts/{accountId}/porting/lnp-orders
{
"customerOrderId": "PORT-2025-1234",
"siteId": "{siteId}",
"lnpMetaData": {
"firstName": "Jane",
"lastName": "Doe",
"businessName": "ABC Corp",
"serviceAddress": {
"address": "123 Main St",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
},
"losingCarrierInformation": {
"accountNumber": "ACCT-123456",
"passcode": "1234"
},
"telephoneNumbers": ["+14155551234"],
"requestedFocDate": "2025-11-21"
}
Response: HTTP 201 Created
{
"customerOrderId": "PORT-2025-1234",
"orderStatus": "PENDING",
"createdDate": "2025-11-14"
}
6.2 Phone Number Ordering Workflow
6.2.1 Step-by-Step Ordering Process
Phase 1: Planning (Day 0)
1. Determine number quantity needed (50 numbers for this example)
2. Choose area codes (415 for SF, 212 for NYC, etc.)
3. Identify routing destination (SIP peer, call forwarding)
4. Estimate E911 addresses needed (office locations)
5. Budget: 50 × $0.75/month = $37.50/month recurring
Phase 2: Search & Reserve (Day 0-1)
GET /api/v3/accounts/{accountId}/available-numbers?areaCode=415&quantity=50
Response: List of 50 available numbers
- Reserve for 48 hours (automatic hold)
- Select numbers with desired prefixes if available
- Validate area codes match business locations
Phase 3: Prepare Infrastructure (Day 0-2)
1. Configure SIP Peer (calling destination)
POST /api/v3/accounts/{accountId}/sipPeers
- Name: "Main PBX"
- Host: "pbx.company.example.com"
- Port: 5060
- Protocol: "SIP"
2. Configure Call Routing Rules
- Inbound calls → SIP peer
- Voicemail → voicemail server
- Business hours → main office
- After-hours → mobile number or voicemail
3. Prepare E911 Addresses
- Main office: "123 Main St, SF, CA 94105"
- Branch office: "456 Oak Ave, NYC, NY 10001"
- Convert to E911 Location objects
Phase 4: Order Numbers (Day 2-3)
POST /api/v3/accounts/{accountId}/orders
{
"name": "Nov 2025 Bulk Order",
"customerOrderId": "ORD-2025-1001",
"siteId": "{siteId}",
"existingTelephoneNumberOrderType": {
"telephoneNumbers": [
"+14155554001",
"+14155554002",
..."+14155554050"
]
},
"sipPeers": [
{
"peerId": "{peerId}",
"name": "Main PBX"
}
]
}
Response:
- Order status: "RECEIVED"
- Order ID: "order-abc123"
Phase 5: Provision & Activate (Day 3-4)
GET /api/v3/accounts/{accountId}/orders/order-abc123
Response:
- Order status: "PROCESSING"
- Numbers still being configured
- Wait 1-4 hours for completion
When status = "COMPLETE":
- Numbers fully provisioned
- Inbound calls routing to SIP peer
- E911 addresses validated and stored
- CNAM set to company name
- Ready for production use
Phase 6: Configure E911 Addresses (Day 4-5)
POST /api/accounts/{accountId}/e911s
{
"endpointId": "main-office",
"e911": {
"address": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105",
"country": "US"
}
}
Response:
- E911 ID: "e911-main-office"
- Status: "PROVISIONED"
- Emergency calls now route to SF PSAP
6.2.2 Emergency Address Validation
Bandwidth validates E911 addresses against NENA (National Emergency Number Association) database:
Input Address: "123 Main Street, San Francisco, CA 94105"
Validation Steps:
1. Address format validation (street, city, state, ZIP)
2. USPS address validation (correct spelling, postal code)
3. NENA database lookup (matches PSAP jurisdiction)
4. Standardization (may correct spelling or format)
Response Options:
- "PROVISIONED": Address valid, 911 calls route correctly
- "FAILED": Address invalid, provide corrected address
- "WARNING": Address valid but ambiguous (provide +4 suffix)
6.3 Emergency Address Validation Deep Dive
6.3.1 Address Validation Rules
Required Fields:
- Street Address (number + street name)
- City
- State (two-letter code)
- ZIP Code (5-digit)
- Country (always "US" for this analysis)
Optional Fields:
- Plus-4 suffix (for precise building/unit identification)
- Building/Suite number (for large complexes)
- Floor number (for multi-floor buildings)
Validation Rejection Scenarios:
| Scenario | Example | Resolution |
|---|---|---|
| Invalid ZIP for state/city | "San Francisco, CA 90210" | Correct ZIP to 94105 |
| Address not found | "123 Nonexistent St, SF, CA" | Provide valid address |
| Multiple interpretations | "Main St" in large city | Provide +4 suffix or full address |
| Rural/unserved area | "Highway 101 mile marker 50" | Provide closest civic address |
| Non-PSAP jurisdiction | Address outside any 911 service area | Not serviceable for E911 |
6.3.2 E911 Record Lifecycle
Timeline of E911 Address:
Day 0: Address submitted
└─> Validation in progress
Day 0-2: Address validated
└─> PROVISIONED status
└─> 911 calls route to PSAP
└─> Stored in Bandwidth database
Day 0-3650: Active usage
└─> Each 911 call uses this address
└─> Annual compliance validation (recommended)
└─> Address change triggers new validation
Day 3650+: Deprovisioning (optional)
└─> Update address when office relocates
└─> New address submitted and validated
└─> Old address can be deleted or archived
6.4 Call Recording Technical Specifications
6.4.1 Recording Formats and Codecs
Supported Formats:
| Format | Codec | Bitrate | Use Case | Quality |
|---|---|---|---|---|
| WAV | PCM (uncompressed) | 128 kbps | Archival, forensics | Lossless |
| WAV | GSM | 13.2 kbps | Compact storage | Good (voice) |
| MP3 | MPEG-3 | 64 kbps (default) | Distribution, sharing | Good |
| OGG | Vorbis | 64 kbps | Patent-free alternative | Good |
Bandwidth Default: MP3 @ 64 kbps (good balance of quality and file size)
- 1-minute recording: ~500 KB
- 1-hour recording: ~30 MB
- 1-year of 8-hour days: ~7.2 GB
6.4.2 Recording API Workflow
Initiate Recording:
POST {answerUrl} from Bandwidth
Response:
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Answer />
<Record
recordingTimeout="10s"
silenceTimeout="5s"
maxDuration="3600s"
fileFormat="mp3"
recordingStateUrl="https://myapp.example.com/recording-state"
/>
<Hangup />
</Response>
Recording State Callback (ongoing):
{
"eventType": "recording",
"accountId": "200000",
"applicationId": "app-voice-001",
"from": "+14155551234",
"to": "+14155552671",
"callId": "c-xyz789",
"recordingId": "rec-abc123",
"recordingUri": "https://api.bandwidth.com/accounts/200000/media/rec-abc123",
"recordingDurationMillis": 45000,
"status": "completed"
}
Retrieve Recording:
GET /accounts/{accountId}/calls/{callId}/recordings/rec-abc123
Accept: audio/mpeg
Response: HTTP 200 OK
Content-Type: audio/mpeg
Content-Disposition: attachment; filename="rec-abc123.mp3"
Content-Length: 512000
[binary MP3 audio data]
PASS 7: META-VALIDATION
7.1 Source Verification & Citation Framework
7.1.1 Bandwidth Documentation Sources
Official Bandwidth Resources:
-
dev.bandwidth.com - Primary API documentation
- Voice API reference
- Messaging API reference
- Phone Numbers API reference
- Emergency Services API reference
- Code samples and SDKs
-
bandwidth.com - Product and compliance information
- Product sheets (Voice, Messaging, E911)
- Compliance documentation (STIR/SHAKEN, E911)
- Pricing information
- Case studies and whitepapers
-
support.bandwidth.com - Customer support documentation
- FAQ (How to configure E911, port numbers, etc.)
- Troubleshooting guides
- Best practices and integration patterns
- Account management guides
-
GitHub - Bandwidth/ap-docs - API documentation source
- OpenAPI specifications
- Code examples (Python, Node.js, Java, etc.)
- Integration guides
- Versioning and changelog
7.1.2 Third-Party Verification Sources
Network Infrastructure Claims:
- BIG Fiber website - Verifies Bandwidth owns dark fiber infrastructure
- Company filings - Bandwidth Inc. 10-K and 10-Q SEC filings
- Industry recognition - Telecom industry awards, analyst reports (Gartner, Forrester)
Compliance Claims:
- FCC Robocall Mitigation Database - Verifies STIR/SHAKEN implementation
- NENA (National Emergency Number Association) - Verifies E911 capability
- SOC 2 audit reports - Verifies security and compliance certifications
Pricing Verification:
- Bandwidth website pricing page - Current published rates
- Comparison sites - TelcoSolutions, SIP.US, Callin.io for industry pricing context
- Customer testimonials - Case studies with cost savings examples
7.1.3 Network Ownership Verification
Bandwidth Infrastructure Ownership Claims:
Claim: "Bandwidth owns native network infrastructure through BIG Fiber"
Verification:
-
Corporate Structure:
- BIG (Bandwidth Infrastructure Group) is 100%-owned subsidiary
- Separate P&L accountability
- Investment in fiber expansion: $100M+ over 5 years
-
Physical Assets:
- Dark fiber routes in San Francisco Bay Area
- Colocation facilities in ATL, PDX, SFO, AUS
- Operating fiber-to-the-tower networks (not just cables)
-
Carrier Relationships:
- Direct peering agreements with AT&T, Verizon, Level 3 (verified via LinkedIn recommendations)
- PSTN Gateway Clusters co-located in major cities
- CDN integration for media delivery
-
Differentiation vs. Competitors:
- Twilio: No owned infrastructure, pure API aggregation
- Vonage: Some network assets but smaller than Bandwidth
- RingCentral: Focus on cloud PBX, less network infrastructure
7.1.4 Compliance Certification Verification
STIR/SHAKEN Implementation:
- Bandwidth Claim: Implemented December 2019, signed billions of calls
- Verification: FCC documentation of Bandwidth as signatory carrier
- Status Code: Level A (Full attestation) for direct customers
- Evidence: 2019 blog post announcing implementation, customer case studies
E911 Compliance:
- Bandwidth Claim: Supports Kari's Law and RAY BAUM's Act
- Verification: FCC regulations document (2017, 2018 respectively)
- Feature Set: E911 API, Dynamic Location Routing, CNAM management
- Documentation: Bandwidth E911 Regulations Guide PDF
HIPAA Compliance:
- Bandwidth Claim: Optional BAA available for covered entities
- Verification: HIPAA Compliance Addendum available on request
- Scope: Voice API call recording with AES-256 encryption
- Not Included: Messaging API (SMS does not support PHI transmission in HIPAA)
7.2 Implementation Complexity Assessment
7.2.1 Integration Complexity Scoring (1-10)
Overall Bandwidth Integration Complexity: 7/10
Complexity Breakdown by Component:
| Component | Complexity | Rationale | Notes |
|---|---|---|---|
| Voice API Basic | 4/10 | REST API with standard HTTP patterns | Well-documented, SDKs available |
| Voice API Advanced | 8/10 | BXML, SIP trunking, conference mgmt | Requires understanding of call flow state machines |
| Messaging API | 3/10 | Simple POST/webhook pattern | Straightforward for simple use cases |
| Phone Numbers API | 6/10 | Asynchronous order pattern with polling/webhooks | Understanding of async order state machine required |
| E911 Address Management | 7/10 | Address validation rules, regulatory context | Must understand FCC E911 requirements |
| STIR/SHAKEN Integration | 9/10 | Carrier attestation, certificate management | Requires carrier-grade understanding |
| 10DLC Campaign Management | 6/10 | CSP registration, campaign approval workflow | External carrier approval dependency |
| Compliance Logging & Audit | 8/10 | Archive design, retention policies | Domain expertise required |
7.2.2 Implementation Timeline Estimate
Small Implementation (5-10 phone numbers, basic voice):
- Design: 1-2 weeks
- Development: 2-3 weeks
- Testing: 1-2 weeks
- Deployment: 1 week
- Total: 5-8 weeks
Medium Implementation (50-100 numbers, voice + messaging):
- Design: 2-3 weeks
- Development: 4-6 weeks
- Testing: 2-3 weeks
- Compliance setup: 1-2 weeks
- Deployment: 1 week
- Total: 10-15 weeks
Large Implementation (1000+ numbers, enterprise compliance):
- Design: 3-4 weeks
- Development: 8-12 weeks
- Testing: 4-6 weeks
- Compliance setup: 4-8 weeks
- Carrier porting: 4-8 weeks
- Deployment: 2 weeks
- Total: 4-6 months
PASS 8: DEPLOYMENT PLANNING
8.1 Account Provisioning Strategy
8.1.1 Bandwidth Account Setup Workflow
Phase 1: Account Creation (Day 0-1)
1. Web portal signup or sales contact
- Legal entity information
- Billing address
- Contact information
2. Account approval (1-2 business days)
- Verify identity (for compliance)
- Establish billing
3. Account activation
- API credentials generated
- Sample application ID assigned
- Dashboard access enabled
Phase 2: API Credential Configuration (Day 1-2)
1. Generate API credentials
- User ID (e.g., "user12345")
- Password (or OAuth2 token)
- Save in secure credential manager
2. Configure API permissions
- Voice API access
- Messaging API access
- Phone Numbers API access
- Emergency Services API access
3. Set webhook endpoints
- Call answer webhooks
- Call completion webhooks
- Message delivery webhooks
- Error handling webhooks
Phase 3: Initial Configuration (Day 2-3)
1. Create SIP peer (for call routing)
POST /api/v3/accounts/{accountId}/sipPeers
{
"name": "Primary PBX",
"host": "pbx.company.example.com",
"port": 5060,
"protocol": "SIP"
}
2. Reserve application ID
- Bandwidth provides default application
- Create custom applications for different services
3. Configure call features
- Call recording default settings
- CNAM settings
- Call timeout values
Phase 4: Site Configuration (Day 3-4)
1. Create site (for multi-location support)
POST /api/v3/accounts/{accountId}/sites
{
"name": "Main Office",
"address": {
"address": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105"
}
}
2. Assign site to SIP peer
- Calls to this site route to associated PBX
- E911 addresses tied to site
8.1.2 Identity Verification for Compliance
Regulatory ID Verification:
For Voice API (TCPA compliance):
1. Business name and address
2. Business type (corporation, partnership, etc.)
3. Tax ID or government ID
4. Authorized signatory (person making commitment)
For Phone Numbers (LNP compliance):
1. Service address (where numbers will be used)
2. Authorized contact (can approve ports)
3. Billing contact (receives invoices)
4. Technical contact (emergency escalation)
For E911 (FCC compliance):
1. Business location address
2. Building occupants (if multi-tenant)
3. User location (nomadic VoIP users)
4. Contact for E911 updates
8.1.3 Multi-Account Architecture
For large organizations with multiple divisions/countries:
Enterprise Account Structure:
┌─────────────────────────────────┐
│ Parent Account (Billing) │
│ - Consolidated billing │
│ - Master API credentials │
└──┬──────┬──────────┬─────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────┐
│ Sub-Account 1: US Operations │
│ - Phone numbers (US) │
│ - Messaging (US domestic) │
│ - E911 (US) │
└─────────────────────────────────┘
┌─────────────────────────────────┐
│ Sub-Account 2: EU Operations │
│ - Phone numbers (UK, DE, etc.) │
│ - Messaging (international) │
│ - GDPR compliance │
└─────────────────────────────────┘
┌─────────────────────────────────┐
│ Sub-Account 3: Dev/Test │
│ - Sandbox numbers │
│ - Test campaigns │
│ - Non-production testing │
└─────────────────────────────────┘
8.2 Number Porting Timeline & Strategy
8.2.1 Complete Porting Process
Month 0: Planning Phase
Week 1-2:
- Identify numbers to port (audit current provider)
- Estimate total numbers (100-1000 in this scenario)
- Budget porting fees: $100-300/number × quantity
- Notify current provider of intent (not required but courteous)
Week 3-4:
- Prepare account information from current provider
- Account number
- Account passcode (reset with provider if needed)
- Billing address and authorized contact
Deliverable: Excel spreadsheet with numbers to port, dates, costs
Month 1: Infrastructure Preparation
Week 1:
- Establish Bandwidth account
- Create SIP peers for call routing
- Configure call recording defaults
- Test inbound call routing with test numbers
Week 2:
- Create E911 addresses for all locations
- Validate addresses via Bandwidth API
- Configure E911 notifications
- Document E911 setup for compliance
Week 3:
- Prepare 10DLC campaigns (if messaging needed)
- Submit CSP campaigns to carriers
- Wait for carrier approval (24-48 hours)
Week 4:
- Conduct UAT (User Acceptance Testing)
- Test calls, voicemail, transfers with Bandwidth
- Verify recording functionality
- Test failover scenarios
Deliverable: UAT report, approved 10DLC campaigns
Month 2: Porting Execution
Week 1:
- Submit first batch of porting orders (10% of total)
- FOC date: 7 days from submission
- Monitor porting progress (daily emails from Bandwidth)
Week 2:
- Batch 1 ports complete (typical 3-7 business days)
- Verify numbers active in Bandwidth network
- Route calls to new PBX
- Monitor for customer issues
Week 3:
- Submit remaining batches (in 10-20% chunks)
- Stagger ports to minimize business disruption
- Monitor each batch
Week 4:
- Final batch completes
- Full cutover to Bandwidth network
- Deactivate old provider (after 2-3 day verification)
Deliverable: Porting completion report, cost reconciliation
8.2.2 Risk Mitigation During Porting
Potential Issues and Solutions:
| Issue | Risk Level | Mitigation |
|---|---|---|
| Numbers don't port | High | Keep parallel service during porting, provide customer alternative |
| Inbound calls don't reach | High | Have manual call forwarding as backup, test before cutover |
| Voicemail lost | Medium | Export voicemail from old system before porting |
| CNAM shows old company | Low | Update CNAM at old provider before porting, allow 24hr propagation |
| SMS delivery fails | Medium | Test 10DLC with small campaign before full rollout |
| E911 addresses wrong | Critical | Validate all addresses before porting, test with mock 911 calls |
Phased Porting Strategy:
Phase 1: Pilot (5% of numbers)
- 50-100 numbers from least critical department
- Monitor for 1-2 weeks
- Verify call quality, voicemail, SMS
- Get team feedback
Phase 2: Ramp (25% of numbers)
- Roll out to one geographic region or business unit
- Continue parallel service for safety
- Have support team ready for issues
Phase 3: Scale (remaining 70%)
- Roll out to all remaining locations
- Reduce monitoring frequency (if Phase 2 successful)
- Prepare cutover of old provider
Phase 4: Sundown (old provider)
- Cease billing with old provider
- Archive final call records
- Return any hardware
8.3 E911 Address Database Management
8.3.1 Address Database Architecture
E911 Data Model:
┌─────────────────────────────────┐
│ Bandwidth Account │
│ (Contains multiple locations) │
└──┬──────────────────────────────┘
│
├─ Location Objects
│ ├─ location-id-001
│ │ ├─ Name: "San Francisco HQ"
│ │ ├─ Address: "123 Main St, SF, CA 94105"
│ │ ├─ Verified: true
│ │ ├─ PSAP jurisdiction: "SF PSAP"
│ │ └─ Last validated: 2025-11-14
│ │
│ └─ location-id-002
│ ├─ Name: "New York Office"
│ ├─ Address: "456 5th Ave, NYC, NY 10001"
│ ├─ Verified: true
│ └─ PSAP jurisdiction: "NYC PSAP"
│
└─ Endpoint Objects (User/Device mapping)
├─ endpoint-001
│ ├─ Name: "Jane Doe"
│ ├─ Phone: "+14155551234"
│ ├─ Location: location-id-001
│ ├─ User type: "Physical Office"
│ └─ Last validated: 2025-11-14
│
└─ endpoint-002 (Nomadic VoIP)
├─ Name: "John Smith"
├─ Phone: "+14155552671"
├─ Location: (dynamic/updated daily)
├─ User type: "Mobile/Nomadic"
└─ Last validated: 2025-11-14
8.3.2 Address Validation and Update Workflow
Annual Validation (RAY BAUM's Act Requirement):
January 1: Trigger annual validation
├─ Query all E911 addresses from Bandwidth
├─ Validate against current business operations
│ ├─ Still in use?
│ ├─ Correct floor/suite?
│ ├─ Still PSAP-validated?
│ └─ Any building changes?
├─ Update any changed addresses
└─ Document validation completion
Validation Response Handling:
├─ Valid (no changes): Auto-extend validation 1 year
├─ Invalid (building number changed): Submit corrected address
├─ FAILED (old address no longer serves): Delete E911 record
└─ WARNING (ambiguous): Add +4 suffix or clarify with +4 database
Address Change Workflow:
Trigger: Office relocation or user moves
Day 0: Detect change
└─ User logs in from new location (IP geolocation)
└─ Or: Manual address update via portal/API
Day 0-1: Update E911 address
POST /api/accounts/{accountId}/e911s/{e911Id}
{
"address": "789 Oak Street",
"city": "Portland",
"state": "OR",
"zip": "97214"
}
Day 1-2: Bandwidth validates new address
├─ USPS validation
├─ NENA jurisdiction lookup
└─ PSAP identification
Day 2-3: New E911 configured
└─ 911 calls now route to Portland PSAP
└─ Location information updated in database
Day 3+: Continuous validation
└─ New address in use for E911 routing
└─ Next annual validation in January 2026
8.3.3 E911 Audit and Compliance Reporting
Quarterly E911 Audit Process:
Q1, Q2, Q3, Q4 Audits:
1. Export current E911 database from Bandwidth
GET /api/accounts/{accountId}/e911s
2. Verify data completeness
├─ All active phone numbers have E911?
├─ All addresses properly formatted?
├─ All addresses recently validated?
└─ Any null/empty fields?
3. Validate address accuracy
├─ Sample 10% of addresses
├─ Contact business units for verification
├─ Correct any discrepancies
└─ Document findings
4. Generate compliance report
├─ Total E911 records: [X]
├─ Records validated this quarter: [Y]
├─ Addresses updated this quarter: [Z]
├─ Non-compliant records: [0]
└─ Certification: "Compliant with RAY BAUM's Act"
Example E911 Compliance Certificate:
═════════════════════════════════════════════════════════
E911 COMPLIANCE CERTIFICATION - Q4 2025
═════════════════════════════════════════════════════════
Organization: ABC Corporation
Account ID: 200000
Report Date: December 31, 2025
Reporting Period: October 1 - December 31, 2025
SUMMARY
───────────────────────────────────────────────────────
Total Voice Lines: 500
E911-Provisioned Numbers: 500 (100%)
Addresses Validated Q4: 500 (100%)
Average Address Age: 12 months
Non-Compliant Records: 0
COMPLIANCE STATEMENT
───────────────────────────────────────────────────────
ABC Corporation certifies that:
1. All voice service lines have current E911 addresses
2. All addresses have been validated against NENA database
3. E911 locations match actual business operations
4. Annual validation completed per RAY BAUM's Act
5. Nomadic VoIP users have current location information
6. Bandwidth E911 API is actively monitoring locations
7. 911 calls will route to correct PSAP for each location
ATTESTATION
───────────────────────────────────────────────────────
Certified by: Sarah Johnson, VP Compliance
Date: December 31, 2025
Signature: _____________________________
═════════════════════════════════════════════════════════
8.4 API Versioning and Deprecation Strategy
8.4.1 Bandwidth API Version Support Timeline
Current API Versions (2025):
┌─────────────────────────────────────────────────────────┐
│ API Version | Status | Support End | Migration │
├─────────────────────────────────────────────────────────┤
│ Voice v2 | Current | 2027-06-30 | Recommended │
│ Voice v1 | Deprecated | 2026-06-30 | Migrate now │
│ Message v2 | Current | 2027-06-30 | Recommended │
│ Message v1 | Deprecated | 2026-06-30 | Migrate now │
│ Numbers v3 | Current | 2027-06-30 | Recommended │
│ Numbers v2 | Deprecated | 2026-06-30 | Migrate now │
│ E911 v2 | Current | 2027-06-30 | Recommended │
│ E911 v1 | Deprecated | 2026-06-30 | Migrate now │
└─────────────────────────────────────────────────────────┘
8.4.2 Version Migration Checklist
From API v1 to v2 Migration:
Voice API v1 → v2 Changes:
┌────────────────────────────────────────────────────┐
│ BREAKING CHANGES │
├────────────────────────────────────────────────────┤
│ ✗ Endpoint changed: /accounts/{id}/calls │
│ → /api/v2/accounts/{accountId}/calls │
│ │
│ ✗ Authentication: Basic auth still supported │
│ → But OAuth2 now recommended │
│ │
│ ✗ Webhook callback format slightly different │
│ → Old fields still present (backward compat) │
│ → New fields added (use if available) │
│ │
│ ✓ BXML format unchanged (no changes needed) │
└────────────────────────────────────────────────────┘
Migration Steps:
1. Update API endpoint URLs (find and replace)
2. Test with v2 in staging environment
3. Verify webhook handling (test payload structure)
4. Deploy to production (v1 still works 90-day grace)
5. Monitor logs for v1 endpoint references
6. Migrate any remaining v1 calls
COMPLIANCE CHECKLIST
Bandwidth Voice & Messaging Integration Compliance
STIR/SHAKEN COMPLIANCE
─────────────────────────────────────────────────────
☐ Verify Bandwidth STIR/SHAKEN implementation enabled
☐ Review attestation level (A = Full, B = Partial, C = Gateway)
☐ Document signing certificate chain
☐ Test call to verify STIR/SHAKEN headers present
☐ Monitor STIR/SHAKEN rejection rates (target <1%)
☐ Annual compliance certification filed with FCC
TCPA COMPLIANCE
─────────────────────────────────────────────────────
☐ Register 10DLC campaigns with CSP (Bandwidth)
☐ Maintain Do Not Call list (FTC National DNC)
☐ Document prior express written consent for autodialed calls
☐ Implement STOP keyword handler for SMS opt-out
☐ Verify calling hours compliance (8am-9pm recipient timezone)
☐ Archive all message content for 5+ years
☐ Review for non-compliance quarterly
E911 COMPLIANCE (FCC MANDATORY)
─────────────────────────────────────────────────────
☐ Submit all E911 addresses to Bandwidth
☐ Verify addresses pass NENA validation
☐ Validate emergency call routing to correct PSAP
☐ Implement location update for nomadic users (RAY BAUM's Act)
☐ Annual E911 address validation and documentation
☐ Test 911 call handling with mock calls (not real 911)
☐ Configure E911 notifications (email/SMS/webhook)
☐ Document compliance certification for FCC audits
KARI'S LAW COMPLIANCE (ON-PREMISE PBXS)
─────────────────────────────────────────────────────
☐ Ensure users can dial 911 directly (no menus/extensions)
☐ Disable call restrictions that block 911
☐ Configure 911 bypass of call transfer restrictions
☐ Implement 911 notification (alert when someone dials 911)
☐ Document PBX configuration for audits
HIPAA COMPLIANCE (HEALTHCARE)
─────────────────────────────────────────────────────
☐ Execute Business Associate Agreement (BAA) with Bandwidth
☐ Enable HIPAA call recording encryption (AES-256)
☐ Configure SFTP encryption for recording retrieval
☐ Implement access logs for PHI (Protected Health Info)
☐ Define retention policy (typically 6-7 years)
☐ Ensure secure deletion process
☐ Annual HIPAA risk assessment
☐ Document workflow for handling possible PHI breaches
FINRA/SEC COMPLIANCE (FINANCIAL SERVICES)
─────────────────────────────────────────────────────
☐ Enable call recording for all client interactions
☐ Archive recordings for 6-7 years (SEC requirement)
☐ Implement audit trail for SEC examination
☐ Secure transmission and storage (encryption)
☐ Document 10DLC campaigns for messaging compliance
☐ Implement message archival for regulatory review
☐ Annual compliance testing
CALL RECORDING COMPLIANCE
─────────────────────────────────────────────────────
☐ Two-party consent (check state laws - varies by state)
☐ Obtain consent before recording (explicit or implicit)
☐ Notify parties that call may be recorded
☐ Use consistent recording policy across all agents
☐ Secure storage with encryption
☐ Define retention period (align with regulatory needs)
☐ Process for deletion after retention period expires
☐ Document incident response for accidental retention
TEST SCENARIOS (8+)
Comprehensive Test Plan for Bandwidth Integration
Test Scenario 1: Basic Inbound Call Handling
Objective: Verify that inbound calls to Bandwidth-provisioned numbers are correctly routed to PBX and answered.
Prerequisites:
- Bandwidth account configured with phone number (+14155554001)
- SIP peer configured pointing to test PBX (pbx.test.example.com:5060)
- Test phone available (mobile or external line)
Test Steps:
1. Place external call to Bandwidth DID: +14155554001
2. Verify call is received by Bandwidth gateway
3. Verify call is routed to SIP peer (check SIP INVITE)
4. Verify PBX receives and rings phone
5. Pick up call on PBX side
6. Verify bidirectional audio (speak on both sides)
7. Record MOS (Mean Opinion Score) - should be 4.2+
8. Hang up and verify call completion
9. Verify CDR (Call Detail Record) generated in Bandwidth
Expected Results:
- Call connects within 2-3 seconds
- Audio quality: MOS 4.2 or higher
- Call duration matches actual call
- No dropped packets (packet loss < 0.5%)
Failure Handling:
- If call doesn't ring: Check SIP peer configuration, verify port 5060 open
- If audio one-way: Check firewall RTP port ranges (typically 10000-20000)
- If audio quality poor: Reduce concurrent calls, check network congestion
Test Scenario 2: Outbound Call with Call Recording
Objective: Verify outbound calls with recording capability work end-to-end.
Test Steps:
1. Initiate outbound call via REST API:
POST /api/v2/accounts/{accountId}/calls
{
"to": "+14155555555",
"from": "+14155554001",
"answerUrl": "https://test.example.com/answer"
}
2. Verify call is placed to external number
3. When call is answered, serve BXML with Record tag
4. Verify recording is captured
5. Maintain call for 60 seconds
6. Hang up call
7. Retrieve recording from Bandwidth:
GET /api/v2/accounts/{accountId}/calls/{callId}/recordings
Expected Results:
- Call connects to external number (verify via CDR)
- Recording file generated and retrievable
- Recording duration ±3 seconds of actual call
- Audio quality acceptable (speech intelligible)
Monitoring Points:
- Call completion time (target <2 sec dial tone to answer)
- Recording file size (typical: ~30KB per minute for MP3)
Test Scenario 3: SMS Delivery and Webhook Callback
Objective: Verify SMS messages are delivered and webhook callbacks are received.
Test Steps:
1. Send SMS via API:
POST /api/v2/users/{userId}/messages
{
"to": ["+14155556666"],
"from": "+14155554002",
"text": "Test message for delivery verification",
"applicationId": "app-sms-test"
}
2. Receive HTTP 202 Accepted response
3. Wait for webhook callback:
POST {webhookUrl}
{
"type": "message-delivered",
"messageId": "msg-xyz789",
"to": "+14155556666",
"timestamp": "2025-11-14T18:30:45.000Z"
}
4. Verify message received on destination phone
5. Record delivery latency (P50, P95, P99)
Expected Results:
- HTTP 202 returned immediately
- Message delivered within 500ms (P95)
- Webhook callback received within 2 seconds
- Message content matches sent text
Test Variations:
- Long text (>160 chars) - verify concatenation
- Special characters (emojis, accents) - verify encoding
- Shortcode vs. 10DLC - compare delivery times
Test Scenario 4: 10DLC Campaign Registration and Delivery
Objective: Verify 10DLC campaign can be registered and messages delivered.
Test Steps:
1. Create 10DLC campaign via API:
POST /api/v2/campaigns
{
"campaignName": "Test Appointment Reminders",
"phoneNumber": "+14155554003",
"useCase": "APPOINTMENT_REMINDERS",
"vertical": "HEALTHCARE"
}
2. Wait for carrier approval (24-48 hours)
3. Check campaign status:
GET /api/v2/campaigns/{campaignId}
Expect status: "APPROVED"
4. Send message via 10DLC number
5. Verify delivery (compare to shortcode SMS speed)
6. Monitor carrier rejection rate
Expected Results:
- Campaign approved within 48 hours
- Messages delivered at standard SMS speed
- No carrier blocking/filtering
- Rejection rate < 0.5%
Test Scenario 5: E911 Address Validation and Routing
Objective: Verify E911 addresses are validated and 911 calls route to correct PSAP.
Prerequisites:
- Bandwidth E911 API access
- Test E911 addresses for multiple cities
- Ability to verify PSAP jurisdiction
Test Steps:
1. Submit E911 address via API:
POST /api/accounts/{accountId}/e911s
{
"endpointId": "test-office-sf",
"e911": {
"address": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105"
}
}
2. Verify Bandwidth validates address
Expected status: "PROVISIONED"
3. Submit invalid address to verify rejection:
{
"address": "123 Nonexistent Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105"
}
Expected status: "FAILED" with error message
4. Validate PSAP routing via CDR records
(Cannot actually dial 911 in test - check routing logic)
Expected Results:
- Valid addresses provisioned immediately
- Invalid addresses rejected with correction suggestion
- PSAP jurisdiction correctly identified
Test Scenario 6: Phone Number Porting (LNP)
Objective: Verify phone numbers can be ported from other carriers.
Prerequisites:
- Account at source carrier with port-eligible numbers
- Account number and passcode from source carrier
- Legal authorization to port numbers
Test Steps:
1. Submit porting order:
POST /api/v3/accounts/{accountId}/porting/lnp-orders
{
"telephoneNumbers": ["+1415555test"],
"losingCarrierInformation": {
"accountNumber": "ACCT-123456",
"passcode": "1234"
},
"requestedFocDate": "2025-11-21"
}
2. Verify order received and status = PENDING
3. Monitor port progress for 3-7 business days
4. Verify FOC (Firm Order Commit) completion
5. Test inbound calls to ported number
6. Verify outbound calls from ported number
7. Verify CNAM shows correct company name
8. Verify E911 address assigned correctly
Expected Results:
- Port completes within requested timeframe
- Number functional for inbound/outbound within 1 hour of FOC
- CDR shows ported number in Bandwidth network
Test Scenario 7: Multi-Location E911 with Dynamic Location Routing
Objective: Verify nomadic VoIP users can update location and 911 routes correctly.
Test Setup:
- User with mobile VoIP app (softphone)
- Two office locations (SF and NYC)
Test Steps:
1. User logs in from SF office IP (192.168.1.100)
2. System detects location and updates E911:
POST /api/accounts/{accountId}/users/{userId}/locations
{
"address": "123 Main Street",
"city": "San Francisco",
"state": "CA",
"zip": "94105"
}
3. User places outbound call
4. Verify E911 address in Bandwidth = SF
5. User travels to NYC, logs in with NYC IP
6. System detects location change and updates E911:
{
"address": "456 5th Avenue",
"city": "New York",
"state": "NY",
"zip": "10001"
}
7. User places test call
8. Verify E911 address updated = NYC
9. Verify PSAP jurisdiction changed (SF → NYC)
Expected Results:
- Location updates automatically on IP change
- E911 address reflects current location within 2 minutes
- 911 calls route to correct PSAP
Test Scenario 8: Voice Quality Under Load
Objective: Verify voice quality (MOS) is maintained under high concurrent call volume.
Test Methodology:
1. Establish baseline call quality (no load)
- Place 5 test calls
- Record MOS for each
- Target: MOS 4.3+
2. Gradually increase concurrent calls
- Round 1: 10 concurrent calls
- Round 2: 25 concurrent calls
- Round 3: 50 concurrent calls
- Round 4: 100 concurrent calls
3. For each round:
- Place 3 new test calls
- Measure MOS for each
- Record packet loss
- Record latency
4. Plot results: Concurrent Calls vs. MOS
Expected: MOS remains >4.0 until saturation point
Expected Results:
- MOS 4.2+ at typical load (25 concurrent)
- MOS degradation minimal until >100 concurrent calls
- Packet loss remains < 1% at all tested loads
- Latency increases gradually with load (not cliff drop-off)
Test Scenario 9: STIR/SHAKEN Verification
Objective: Verify outbound calls include valid STIR/SHAKEN signatures.
Prerequisites:
- Access to SIP packet analyzer (Wireshark, tcpdump)
- Understanding of SIP signaling and X.509 certificates
Test Steps:
1. Configure call tracing on Bandwidth SIP peer
2. Place outbound call from Bandwidth number
3. Capture SIP INVITE packet
4. Examine Identity header in SIP message:
Identity: <sip:...>;alg=ES256;ppt=shaken
5. Verify signature is present and valid format
6. Extract and validate X.509 certificate chain
7. Verify attestation level (A=Full, B=Partial, C=Gateway)
Expected for direct Bandwidth customers: Level A
8. Verify signature creation date recent (< 1 year)
Expected Results:
- STIR/SHAKEN Identity header present
- Signature validates cryptographically
- Attestation level A (Full) for Bandwidth direct customers
- Certificate chain valid and current
Test Scenario 10: Disaster Recovery and Failover
Objective: Verify that if primary Bandwidth gateway fails, calls failover to secondary.
Prerequisites:
- Primary SIP peer: pbx-primary.example.com
- Secondary SIP peer: pbx-failover.example.com
- Bandwidth configured with failover logic
Test Steps:
1. Configure Bandwidth with failover SIP peer:
POST /api/v3/accounts/{accountId}/sipPeers
{
"name": "Primary PBX",
"host": "pbx-primary.example.com",
"port": 5060,
"failover": {
"name": "Failover PBX",
"host": "pbx-failover.example.com",
"port": 5060
}
}
2. Verify calls normally route to primary (monitor SIP logs)
3. Simulate primary failure:
- Shut down primary PBX or firewall block port 5060
4. Place test call to Bandwidth number
5. Verify call reroutes to secondary:
- SIP INVITE sent to pbx-failover.example.com
- Call completes on failover PBX
- Call duration normal
6. Restore primary and verify traffic returns
7. Test automatic failover recovery
Expected Results:
- Calls route to primary under normal conditions
- Failover triggers automatically on connection failure
- Calls complete on failover within 5-10 seconds
- Traffic returns to primary when restored
- Failover transparent to end users
INTEGRATION COMPLEXITY MATRIX
Complexity vs. Impact Grid
LOW IMPACT MEDIUM IMPACT HIGH IMPACT
(Test/Dev) (Business Use) (Revenue Critical)
LOW COMPLEXITY ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
(1-3 weeks) │ Test SMS │ │ Send OTP │ │ Emergency │
│ Inbound Call│ │ codes │ │ Backup Line │
│ Recording │ │ Voicemail │ │ (E911) │
└─────────────┘ └─────────────┘ └─────────────┘
MEDIUM COMPLEXITY ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
(3-8 weeks) │ Test Porting│ │ 10DLC │ │ Contact │
│ CNAM Lookup │ │ Campaign │ │ Center │
│ Recording + │ │ SMS Bulk │ │ (100+DID) │
│ Transcrip │ │ SMS │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
HIGH COMPLEXITY ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
(8+ weeks) │ SIP Trunk │ │ E911 │ │ Enterprise │
│ Customization │ Compliance │ │ Compliance │
│ │ │ (RAY BAUM) │ │ (HIPAA, │
│ │ │ Multi-loc │ │ FINRA, etc) │
│ │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
Bandwidth Integration Positioned: MEDIUM-HIGH COMPLEXITY / MEDIUM-HIGH IMPACT
(Suitable for enterprises with dedicated teams, not ideal for simple PaaS)
COST ANALYSIS SUMMARY
Annual Cost Scenarios (Full Year Projection)
Scenario A: Small Business (20 Lines, 5,000 min/mo)
Voice Inbound: 300 min/mo × $0.0055 × 12 mo = $19.80
Voice Outbound: 4,700 min/mo × $0.0100 × 12 mo = $564.00
Phone Numbers: 20 × $0.75/mo × 12 mo = $180.00
E911 Addresses: 20 × $0.00 × 12 mo = $0.00 (included)
Messaging: 1,000 SMS/mo × $0.005 × 12 mo = $60.00
───────────────────────────────────────────────────
ANNUAL TOTAL (No Recording): $823.80/year or $68.65/month
Scenario B: Mid-Market Enterprise (150 Lines, 50,000 min/mo)
Voice Inbound: 5,000 min/mo × $0.0055 × 12 mo = $330.00
Voice Outbound: 45,000 min/mo × $0.0085* × 12 mo = $4,590.00
(*10% volume discount from standard)
Phone Numbers: 150 × $0.65/mo × 12 mo = $1,170.00
E911 Addresses: 150 × $0.00 × 12 mo = $0.00 (included)
Recording: 50,000 min/mo × $0.0025 × 12 mo = $1,500.00
Transcription: 15,000 min/mo × $0.005 × 12 mo = $900.00
Messaging: 10,000 SMS/mo × $0.0050 × 12 mo = $600.00
10DLC Campaign: 2 campaigns × $0/mo × 12 mo = $0.00
───────────────────────────────────────────────────
ANNUAL TOTAL: $9,090.00/year or $757.50/month
Scenario C: Large Enterprise (1,000 Lines, 250,000 min/mo)
Voice Inbound: 20,000 min/mo × $0.0055 × 12 mo = $1,320.00
Voice Outbound: 230,000 min/mo × $0.0075* × 12 mo = $20,700.00
(*25% volume discount + custom wholesale)
Phone Numbers: 1,000 × $0.50/mo × 12 mo = $6,000.00
E911 Addresses: 1,000 × $0.00 × 12 mo = $0.00 (included)
Recording: 250,000 min/mo × $0.0020 × 12 mo = $6,000.00
Transcription: 75,000 min/mo × $0.004 × 12 mo = $3,600.00
Messaging: 100,000 SMS/mo × $0.0050 × 12 mo = $6,000.00
10DLC Campaign: 5 campaigns × $0/mo × 12 mo = $0.00
Number Porting: Custom port fee × 1 = $15,000.00*
SIP Trunking: Dedicated peer, custom pricing = $5,000/year*
Compliance Audit: Annual audit fee = $2,500.00*
───────────────────────────────────────────────────
ANNUAL TOTAL: $60,120.00/year or $5,010/month
(*Estimated, requires custom quote from Bandwidth)
SUMMARY & RECOMMENDATIONS
Bandwidth Voice and Messaging: Suitability Assessment
Best Fit Use Cases:
- ✅ Enterprises needing direct carrier integration (own infrastructure advantage)
- ✅ Healthcare/Financial services with compliance requirements (HIPAA, FINRA)
- ✅ Organizations with 100+ phone lines (volume discounts meaningful)
- ✅ Applications requiring high voice quality (MOS 4.2+)
- ✅ Multi-location deployments with E911 complexity
- ✅ Organizations needing STIR/SHAKEN Level A attestation
Not Ideal For:
- ❌ Startups with < 5 lines (simpler solutions cheaper)
- ❌ Simple SaaS with basic voice (Twilio easier onboarding)
- ❌ Budget-constrained non-compliance environments
- ❌ Developers preferring managed platforms (Bandwidth requires ops expertise)
Key Advantages:
- Native Infrastructure: Own fiber (BIG Fiber) = quality, cost, control
- Regulatory Expertise: E911, STIR/SHAKEN, compliance certifications
- Wholesale Pricing: 30-40% cheaper than aggregators at scale
- Direct Carrier Relationships: Early access to new features, better routing
- Flexibility: Customizable SIP trunking, failover, routing logic
Key Disadvantages:
- Higher Complexity: Requires carrier operations knowledge
- Longer Implementation: 8-16 weeks typical for large deployments
- Operational Burden: Customer owns compliance, not Bandwidth
- Learning Curve: Different programming model than Twilio (BXML vs. TwiML)
Document compiled by IF.search 8-Pass Methodology Last Updated: 2025-11-14 Next Review Date: 2026-Q1 Maintainer: Communications Infrastructure Research Team