DEVELOPER & INTEGRATOR DOCUMENTATION

API & PROTOCOL SPECIFICATION

Integrate V-SHIELD into existing SIP trunks, Asterisk/FreeSWITCH PBX cores, WebRTC gateways, and telephonic banking IVRs using standard streaming WebSockets and REST audit endpoints.

STREAMING PROTOCOLWebSocket Binary PCM1616 kHz, single-channel mono, 333ms hops

AVERAGE LATENCY< 269ms Round-TripBounded inside conversational pause

DATA PRIVACYDPDP Act 2023 Compliant0 bytes of raw audio persisted to disk

STREAMING WEBSOCKET INTAKE

ENDPOINT: /ws/audio (WSS)

The streaming pipeline communicates over a duplex WebSocket connection. Clients send initial session handshake JSON, stream continuous raw PCM16 binary chunks, and receive real-time detection telemetry JSON payloads within 269ms.

1. SESSION INITIALIZATION (CLIENT → SERVER)

{
  "type": "session.start",
  "session_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "sample_rate": 16000,
  "channels": 1,
  "chunk_ms": 333,
  "client": {
    "platform": "telephony-sip-gateway",
    "codec": "G.711u"
  }
}

2. REAL-TIME DETECTION TELEMETRY (SERVER → CLIENT)

{
  "type": "detection.result",
  "session_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "chunk_index": 42,
  "spoof_probability": 0.0412,
  "risk_level": "low",
  "suggested_action": "continue",
  "latency_ms": 23.8,
  "explainability_markers": {
    "high_frequency_anomaly": 0.03,
    "phase_discontinuity": 0.04,
    "prosody_irregularity": 0.05
  },
  "model": {
    "name": "aasist",
    "version": "0.1.0"
  }
}

REST API SPECIFICATIONS

AUDIT, HEALTH & MULTILINGUAL CHALLENGES

GET/health

Returns service status, loaded ML model name, CPU execution device, and zero audio storage verification flag.

GET/api/challenges?language=hi

Retrieves dynamic phonemic challenge phrases in English, Hindi, or Tamil designed with high stop-consonant transitions.

POST/api/challenges/verify

Verifies caller response spoof probability against the 0.35 threshold and enforces fail-closed authorization.

GET/api/sessions

Fetches audited call sessions with risk summaries, duration, chunk counts, and policy verdicts with Supabase RLS.

TELEPHONY & SIP TRUNK INTEGRATION

ASTERISK / FREESWITCH / TWILIO COMPATIBLE

V-SHIELD acts as transparent media-path middleware. It consumes the bi-directional RTP stream without terminating the call. When a spoof is detected or challenge is required, V-SHIELD returns policy action codes to the switch (e.g. SIP 603 Decline, prompt injection, or human supervisor transfer).

SAMPLE TWILIO MEDIA STREAMS TwiML CONFIGURATION

<Response>
  <Start>
    <Stream url="wss://voiceshield-sih-2026-production.up.railway.app/ws/audio" track="inbound_track">
      <Parameter name="codec" value="audio/x-mulaw" />
      <Parameter name="rate" value="8000" />
    </Stream>
  </Start>
  <Dial>+91-1800-BANKING-IVR</Dial>
</Response>