aionboarding/ai-patient-onboarding/docs/VOICE_ONBOARDING_API.md

Voice Onboarding & Audio API Reference

Implementation Sources: app/api/voice_onboarding.py, app/services/voice_service.py

---

1. POST /v1/voice-onboarding/start

Starts a voice-first onboarding session with Sarvam AI multilingual speech engine.

Request Body (StartVoiceOnboardingRequest):

{
  "patient": {
    "id": "PAT-VOICE-1",
    "name": "Ramesh G",
    "age": 34,
    "gender": "male"
  },
  "category": {
    "type": "general",
    "code": "general_medicine",
    "name": "General Medicine"
  },
  "language": "ta-IN"
}

Supported Language Codes:

• en-IN (Indian English)
• ta-IN (Tamil)
• hi-IN (Hindi)
• te-IN (Telugu)
• kn-IN (Kannada)
• ml-IN (Malayalam)
• mr-IN (Marathi)

Successful Response (200 OK - StartVoiceOnboardingResponse):

{
  "success": true,
  "session_id": "VOICE-D3CAEA5C",
  "patient_id": "PAT-VOICE-1",
  "category": {
    "type": "general",
    "code": "general_medicine",
    "name": "General Medicine"
  },
  "language": "ta-IN",
  "status": "in_progress",
  "stage": "greeting",
  "greeting_text": "வணக்கம் Ramesh G, CureSelect மருத்துவமனைக்கு வரவேற்கிறோம். இன்று உங்களுக்கு என்ன சுகவீனம் உள்ளது?",
  "audio_url": "/v1/voice-onboarding/audio/aud_a1b2c3d4e5f6",
  "response_time_ms": 78.32,
  "response_time_sec": 0.08
}

---

2. POST /v1/voice-onboarding/{session_id}/turn

Processes a conversational voice turn using audio recording or text fallback.

Request Headers:

Content-Type: multipart/form-data
Authorization: Bearer test_token_PAT-VOICE-1

Multipart Form Data Parameters:

• audio: Binary audio recording file (WAV, WEBM, MP3, OGG up to 10MB).
• text_fallback: String text transcript (used if WebSpeech STT processed client-side or audio is unprovided).

Note: At least one of audio or text_fallback must be provided.

Successful Response (200 OK - VoiceTurnResponse):

{
  "success": true,
  "session_id": "VOICE-D3CAEA5C",
  "patient_transcript": "எனக்கு கடந்த 3 நாளா நெஞ்சு பாரமா இருக்குங்க.",
  "ai_text": "நன்றி. இந்த நெஞ்சு பாரம் உடற்பயிற்சி செய்யும் போது அதிகமாகிறதா?",
  "stage": "symptoms",
  "completed": false,
  "audio_url": "/v1/voice-onboarding/audio/aud_f9e8d7c6b5a4",
  "audio_base64": null,
  "suggested_specialty": {
    "specialty": "Cardiology",
    "reason": "Chest tightness reported"
  },
  "response_time_ms": 1412.37,
  "response_time_sec": 1.41
}

---

3. GET /v1/voice-onboarding/audio/{audio_id}

Streams generated TTS audio for browser or mobile playback.

Request Headers:

No authentication required for audio file streaming.

Response Headers:

HTTP/1.1 200 OK
Content-Type: audio/wav (or audio/mpeg)
Accept-Ranges: bytes
Content-Length: 48290

Frontend Audio Playback snippet:

const audio = new Audio(`${BASE_URL}/v1/voice-onboarding/audio/${audioId}`);
await audio.play();

---

4. POST /v1/voice-onboarding/{session_id}/complete

Finalizes a voice onboarding session.

Request Body:

{
  "confirmed": true
}

Successful Response (200 OK):

{
  "success": true,
  "session_id": "VOICE-D3CAEA5C",
  "status": "completed",
  "result": {
    "patient_id": "PAT-VOICE-1",
    "chief_complaint": "Chest tightness for 3 days",
    "language": "ta-IN",
    "onboarding_completed": true
  },
  "message": "Voice onboarding successfully saved to patient record.",
  "response_time_ms": 4121.79,
  "response_time_sec": 4.12
}