Hum Rahi

────────────────────────────────────────────────────────────
US-033.INFRA.1 — Telephony Provider Integration & Outbound Call
Infrastructure for SOS Fallback
────────────────────────────────────────────────────────────

Role
As an infrastructure engineer on Ham Rahi,
I need to provision and configure a programmable telephony integration
capable of placing reliable outbound calls to Indian mobile numbers
from the Ham Rahi backend,
So that the phone call fallback mechanism in US-033.BE.1 has a
dependable, low-latency voice channel available the moment it is
needed during a live SOS emergency.

User Story
As Priya,
I want the system's fallback phone call to connect quickly and
reliably when WebRTC fails,
So that network or WebRTC problems never leave me without a voice
channel to the police operator in an emergency.

In-Scope

• Selection and provisioning of a programmable voice / IVR telephony
  provider with coverage and reliability for Indian mobile networks
  (TRAI-compliant outbound calling)
• Provisioning of a dedicated outbound caller ID number or
  alphanumeric sender ID recognisable to citizens as an official
  Ham Rahi emergency line, to reduce call rejection
• Configuring the provider API integration: authentication,
  outbound call placement, call status webhooks (ringing, answered,
  failed, ended), and call detail record retrieval
• Defining and provisioning call routing configuration: citizen
  leg and operator leg of the voice bridge, including hold and
  transfer behaviour if the primary operator does not answer
• Ensuring call initiation latency from API request to first ring
  on the citizen device is within an acceptable threshold for
  emergency use (target: under 3 seconds from API call)
• Configuring secure credential storage for telephony provider API
  keys; credentials must not be hardcoded or stored in version
  control
• Provisioning a staging / sandbox telephony environment for
  integration testing by US-033.BE.1 without incurring live
  call costs or reaching real citizen numbers
• Defining and documenting the provider fallback posture: what
  happens if the primary telephony provider API is unreachable
  (secondary provider or alert escalation)
• Health monitoring and alerting for telephony provider API
  availability; automated alert if the provider endpoint becomes
  unreachable or call success rate drops below threshold
• All telephony infrastructure configuration defined in
  version-controlled infrastructure-as-code

Out-of-Scope

• WebRTC or STUN/TURN infrastructure (US-030.INFRA.1)
• Call script, IVR menu, or recorded message content
• SMS gateway provisioning (separate infra story if SMS fallback
  is added in a future phase)
• Inbound call handling from citizens (SOS is outbound-initiated
  by the system only in this flow)
• Telephony billing reconciliation or cost monitoring tooling
  (operational concern, post-launch)

Acceptance Criteria

AC1 A programmable telephony provider is provisioned with verified
outbound call capability to Indian mobile numbers across
major operators (Jio, Airtel, Vi, BSNL) confirmed by test
calls in staging.

AC2 The outbound caller ID or sender ID is configured and displays
a recognisable Ham Rahi emergency identity on the citizen's
device; test confirms the caller ID is not masked or shown
as unknown on the target networks.

AC3 The provider API integration supports call status webhooks
delivering ringing, answered, failed, and ended events to
the Ham Rahi backend in real time; webhook delivery latency
is under 2 seconds from call state change in staging tests.

AC4 Call initiation latency — from API request to first ring on
a test Indian mobile number — is under 3 seconds in the
staging environment across a minimum of 20 test calls with
no more than 10% of calls exceeding this threshold.

AC5 A dedicated staging / sandbox environment is provisioned and
accessible to the US-033.BE.1 development team for
integration testing; sandbox calls do not reach real citizen
numbers or incur live call charges.

AC6 Telephony provider API credentials are stored in the
project secrets management system; no credentials appear
in version-controlled configuration files or application
logs.

AC7 A secondary provider failover posture is documented: if the
primary provider API is unreachable, the backend receives
a clear error response within a defined timeout and the
supervisor escalation path defined in US-033.BE.1 AC6 is
triggered; automatic retry to a secondary provider is
documented as a Phase 2 enhancement.

AC8 A health monitoring alert fires within 2 minutes of the
telephony provider API becoming unreachable or call success
rate in production dropping below 90% over a 5-minute window;
the alert reaches the designated infrastructure on-call
channel.

AC9 All telephony provider configuration — API integration
parameters, routing rules, webhook endpoints — is defined
in version-controlled infrastructure-as-code and can be
reproduced in a new environment without manual steps beyond
secrets injection.

Definition of Done

• Outbound calls to all four major Indian mobile operators
  confirmed in staging
• Caller ID display confirmed on test devices across operators
• Call status webhook latency under 2 seconds confirmed across
  20 test events
• Call initiation latency under 3 seconds confirmed across
  20 test calls with pass rate of 90% or above
• Sandbox environment accessible and confirmed usable by
  BE development team
• Credential storage in secrets manager confirmed; absence
  from version control confirmed by repo scan
• Secondary provider failover posture documented and reviewed
• Health monitoring alert tested via deliberate API endpoint
  shutdown
• Infrastructure-as-code committed and peer-reviewed
• No open P1 or P2 infrastructure issues