Ambient Dictation

Real-time ambient dictation using WebSocket connections for live transcription during medical consultations.

WebSocket /api/v1/dictationConnect to our WebSocket endpoint to receive real-time transcription results as you speak. The service processes audio streams and returns live transcripts. Send audio data as binary WebSocket messages and receive structured JSON responses.QUERY PARAMETERS

REQUIREDproviderstring

Provider ID associated with your EHR application.

OPTIONALclinicCodestring

Clinic code or identifier of the clinic making the WebSocket connection.

OPTIONALapiKeystring

API key for authentication. Alternative to clinicCode.

OPTIONALlanguagestring

Language code for speech-to-text transcription. Supports SEA languages (en, id, ms, th, vi, tl, cmn, yue, ja, ko, hi, bn, ta, ur) and multilingual options (en_ms, cmn_en, en_ta). Note: tl (Tagalog) automatically supports English bilingual mode. Defaults to "en" if not specified.

CONNECTION FLOW

Establish WebSocket connection with authentication parameters

Optional: Specify language parameter for improved transcription accuracy

Send audio data as binary chunks (WebM recommended, other formats may work)

Receive real-time transcription results

connected

final_transcript

end_of_transcript

error

Handle connection events (open, message, error, close)

Clean up resources on disconnect

WebSocket URL

CONNECTION URL

1wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123

Browser Examples

Basic Connection

Establish WebSocket connection with authentication

Basic Connection

1const ws = new WebSocket(
2  'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123'
3);
4
5ws.onopen = () => console.log('Connected to dictation service');
6ws.onmessage = (event) => {
7  const data = JSON.parse(event.data);
8  
9  switch (data.type) {
10    case 'connected':
11      console.log('Connected with client ID:', data.clientId);
12      break;
13    case 'final_transcript':
14      console.log('Transcript:', data.transcript, 'End of sentence:', data.isEndOfSentence);
15      break;
16    case 'end_of_transcript':
17      console.log('Transcription completed');
18      break;
19    case 'error':
20      console.error('Error:', data.message, data.details);
21      break;
22  }
23};

Audio Recording & Streaming

Record audio in WebM format and stream to WebSocket using MediaRecorder

Audio Recording & Streaming

1// Get user media and start recording
2navigator.mediaDevices.getUserMedia({ audio: true })
3  .then(stream => {
4    const mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });
5    const ws = new WebSocket(
6      'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123'
7    );
8    
9    ws.onopen = () => {
10      mediaRecorder.start(250); // Send chunks every 250ms for real-time performance
11    };
12    
13    mediaRecorder.ondataavailable = (event) => {
14      if (ws.readyState === WebSocket.OPEN) {
15        ws.send(event.data); // Send audio chunk
16      }
17    };
18  });

API Key Authentication

Alternative authentication using API key instead of clinic code

API Key Authentication

1const ws = new WebSocket(
2  'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&apiKey=your_api_key_here'
3);
4
5ws.onopen = () => console.log('Connected with API key');
6ws.onerror = (error) => console.error('Connection error:', error);

Language-Specific Transcription

Connect with specific language support for better transcription accuracy

Language-Specific Transcription

1// English (default)
2const wsEnglish = new WebSocket(
3  'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123&language=en'
4);
5
6// Mandarin transcription
7const wsMandarin = new WebSocket(
8  'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123&language=cmn'
9);
10
11// Malay & English bilingual
12const wsBilingual = new WebSocket(
13  'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123&language=en_ms'
14);
15
16// Tagalog (Filipino) with automatic English support
17const wsTagalog = new WebSocket(
18  'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123&language=tl'
19);
20
21// Thai transcription
22const wsThai = new WebSocket(
23  'wss://dev-proxy.usescrubs.com/api/v1/dictation?provider=SAMPLE_EHR_1&clinicCode=00A123&language=th'
24);

Message Types

JSON

1// Connection established
2{
3  "type": "connected",
4  "clientId": "unique-client-identifier",
5  "message": "WebSocket connection established and authenticated"
6}
7
8// Final transcription results
9{
10  "type": "final_transcript",
11  "transcript": "and",
12  "isEndOfSentence": false,
13  "timestamp": "2025-08-23T16:58:26.076Z"
14}
15
16// End of transcript
17{
18  "type": "end_of_transcript",
19  "message": "Transcription completed",
20  "timestamp": "2025-08-23T16:58:26.076Z"
21}
22
23// Error messages
24{
25  "type": "error",
26  "message": "Error description",
27  "details": "Generic guidance for users"
28}