Sahl AI Listen Transcription WebSocket API

Overview

The Listen Transcription WebSocket API allows you to stream audio from medical encounters and receive live transcriptions in real-time. This API is designed for seamless integration into your healthcare applications, enabling efficient and accurate transcription of medical conversations.

Authentication

Before using the WebSocket API, you need to obtain an authentication token:

1. Call the login API to get a token (refer to the login API documentation).
2. Use this token in the WebSocket connection as described below.

WebSocket Connection

URL: wss://sau-api.sahl.ai/ws/listen

Authentication: Pass your bearer authentication token as an Authorization header when initiating the websocket:

const socket = new WebSocket('wss://sau-api.sahl.ai/ws/listen', {
  headers: {
    'Authorization': 'Bearer <YOUR_TOKEN>'
  }
});

Communication Flow

1. Open the WebSocket connection with the authentication token.
2. Send a configuration message to initialize the transcription.
3. Stream audio chunks continuously.
4. Receive transcript items in real-time.
5. Send an end message when the encounter is finished.
6. The server will finalize processing and close the connection.

Message Types

Client to Server

1. Configuration Message This should be the first message sent after establishing the connection.

{
  "object": "start"
}

1. Audio Chunk Send audio data in small chunks (recommended 100ms, max 1 second).

{
  "object": "audio_chunk",
  "sequence_id": 1,
  "audio_data": "base64_encoded_audio_data"
}

1. End Message Signal the end of the audio stream.

{
  "object": "end"
}

Server to Client

1. Transcript Item

{
  "object": "transcript_item",
  "id": "unique_id",
  "channel_id": "provider",
  "text": "Hello, how are you feeling today?",
  "is_final": true,
  "start_offset_ms": 1000,
  "end_offset_ms": 3000
}

1. Error Message

{
  "object": "error_message",
  "code": "error_code",
  "message": "Error description"
}

Best Practices

• Send audio chunks of around 100ms duration for optimal performance.
• Handle non-final transcript items by updating previously received items with the same ID.
• Sort final transcript items by start_offset_ms before further processing.
• Implement error handling for potential WebSocket disconnections.

Error Handling

The WebSocket will close with an error message if there's a fatal error. Common errors include:

• Authentication failure
• Invalid audio format
• Timeout (no audio received for 10 seconds)

Implement appropriate error handling and reconnection logic in your client application.