Eka Care Ekascribe Typescript SDK Integration
This guide explains how to integrate the Eka Care Ekascribe Typescript SDK into your application.Overview
The Eka Care Ekascribe SDK allows you to capture and process audio, generating structured medical documentation using Eka Care’s voice transcription API.Prerequisites
Before getting started, ensure you have:- Node 14 or higher
npmoryarnfor dependency management- Access and refresh tokens from Eka Care (optional for some methods)
- Microphone access via browser permissions
- Stable network connectivity
Installation
Install the SDK usingnpm or yarn:
Usage
1. Get Ekascribe Instance
Get the SDK instance once and use it everywhere in your application to call all methods.ekascribe instance for all SDK method calls.
2. Fetch configurations list
Get supported input languages, output formats, and consultation modes.-
Sample Response:
3. Init transaction
Initialize a transaction before starting recording. This sets up the session with your configuration.-
input_language: Language code array (e.g.,['en-IN']) -
output_format_template: Array withtemplate_id- depends on your end user’s template selection -
system_info: Optional - Pass your system configuration to backend -
patient_details: Optional - Patient information -
version: SDK version -
additional_data: Optional - Pass any data you want to receive unchanged in the response -
transfer: Audio mode. Usevadedfor audio already processed with Voice Activity Detection (SDK does this by default); usenon-vadedonly if you are sending raw audio without VAD. -
model_type: Transcription model choice.pro= most accurate;lite= lower latency, more performant. -
Sample Response:
error_code:
txn_limit_exceeded: Maximum number of transactions exceededtxn_init_failed: Something went wrong. Retry with the same method call
status_code: 401, update the tokens in your config and reinitialize the instance:
4. Start recording
Start recording audio after initializing the transaction.-
Sample Response:
5. Pause recording
Pause the ongoing voice recording.-
Sample Response:
6. Resume recording
Resume a paused recording.-
Sample Response:
7. End recording
End the recording session. This method:- Stops the recording
- Uploads all audio chunks to the server
- Automatically retries failed uploads once
- Calls the commit API to finalize the transaction
-
Sample Response:
error_code:
txn_stop_failed: CallendRecordingagain.audio_upload_failed: UseretryUploadRecording(step 9).txn_commit_failed: CallcommitTransactionCall(step 11).
status_code: 401, update the tokens in your config and retry:
8. Get output recorded prescription
You can fetch output in two ways:getTemplateOutput({ txn_id }): polling is your responsibility; call repeatedly until processing finishes.pollSessionOutput({ txn_id, max_polling_time }): SDK polls for you and resolves when processing finishes (default max wait: 2 minutes; override viamax_polling_time, pass time in milliseconds).
-
200: Success; all templates processed. -
202: Templates are still processing; poll again (or letpollSessionOutputcontinue). -
206: Partial success; some templates not processed fully. -
500: All template processing failed, or internal server error; stop and surface error. -
Response type:
-
Example Response:
9. Retry upload recording
Retry uploading failed audio files afterendRecording.
-
Sample Response:
force_commit behavior:
force_commit: true- Model will initiate the processing if some files still fail after retryforce_commit: false- It will waits until all files are uploaded successfully before processing.
status_code: 401, update the tokens in your config and retry:
10. Patch recording session status
Cancel or update the status of a recording session.-
Sample Response:
code: 401, update the tokens in your config and retry:
11. Commit transaction
Call this ifendRecording returns error_code: 'txn_commit_failed' or the transaction is not yet committed.
-
Response type:
status_code: 401, update the tokens in your config and retry:
12. Stop transaction
Use this method to stop a transaction that has not yet been stopped or returned atxn_stop_failed error in a previous step.
-
Response type:
status_code: 401, update the tokens in your config and retry:
13. Get previous sessions
Fetch previous sessions.txn_count controls how many sessions the API returns.
-
Response type:
Templates SDK Methods
1. Get All Templates
Use this method to retrieve all available templates for the current user.-
Response type:
2. Create Template
Use this method to create a new custom template.-
Response type:
3. Edit Template
Use this method to update an existing template.-
Response type:
4. Delete Template
Use this method to delete an existing template.-
Response type:
5. Generate Template with AI by giving a prompt
Use this method to generate a template using AI with a text prompt.-
Response type:
6. Add templates to list
Use this method to mark templates as favourite templates.-
Response type:
7. Get All Sections
Use this method to retrieve all available template sections.-
Response type:
8. Create Section in a template
Use this method to create a new section that can be used in templates.-
Response type:
9. Edit Section in a template
Use this method to update an existing template section.-
Response type:
10. Delete Section from a template
Use this method to delete a template section.-
Response type:
Non-vaded flow: Upload raw audio to get output summary
Use this method to upload pre-recorded audio files directly and get transcription output without real-time recording. This is useful when you have existing audio files and want to process them. What this method does:- Gets a presigned URL from the server
- Uploads audio files to S3 via presigned URL
- Initializes a transaction with the uploaded files
- Returns the transaction details
-
action: Passekascribe-v2exactly as shown -
audioFiles: Array of File or Blob objects -
audioFileNames: Array of file names corresponding to audio files -
transfer: Usenon-vadedfor raw audio files (not processed with VAD) -
Other parameters: Same as
initTransaction(see step 3) -
Sample Response:
error_code:
get_presigned_url_failed: Failed to get presigned URL from server, retry with the same methodaudio_upload_failed: Failed to upload audio files to S3, retry with the same methodtxn_limit_exceeded: Maximum number of transactions exceededtxn_init_failed: Failed to initialize transaction after upload, retry with the same method
status_code: 401, update the tokens in your config and retry:
Utility Methods
1. Get total uploaded files
Use this method to retrieve all the audio files generated for a specific session.-
Response type:
2. Get successfully uploaded files
Use this method to retrieve all the audio files that were uploaded successfully.-
Response type:
3. Get failed audio files
Use this method to retrieve all the audio files that failed to upload.-
Response type:
4. Reset Class Instance
Use this method to reset the EkaScribe instance and clear all stored data.5. Reinitialise VAD Instance
Use this method to reinitialize the Voice Activity Detection (VAD) instance.6. Pause VAD Instance
Use this method to pause the Voice Activity Detection without stopping the recording session.7. Destroy VAD Instance
Use this method to completely destroy the VAD instance and free up resources.8. Update Authentication Tokens
Use this method to update the access token when it expires (e.g., when you receive a 401 error).- When any API method returns
status_code: 401 - When
eventCallbackreturnserror.code: 401infile_upload_status - Before token expiration to prevent upload failures
Generic Callbacks
1. Event callback
This callback provides information about SDK operations. Use it to monitor file uploads, transaction status, AWS configuration, and authentication errors.-
Callback Structure:
-
Callback Types Explained:
file_upload_status - Track audio chunk upload progress
Use this to monitor upload progress of audio chunks:
-
status: 'info'- Audio chunk infodata.success: Count of successfully uploaded chunksdata.total: Total chunks generateddata.fileName: Current chunk file namedata.chunkData: Audio data for current chunk
-
status: 'success'- Chunk uploaded successfullydata.success: Updated successful upload countdata.total: Total chunksdata.is_uploaded: true
-
status: 'error'- Chunk upload failederror.code: HTTP error codeerror.msg: Error messageerror.details: Additional error details
-
Status codes to handle:
If
error.code === 401, it means your access token has expired. Update tokens immediately:
2. User speech callback
Triggered by Voice Activity Detection (VAD) when user starts or stops speaking.Error codes
| Error Code | Description |
|---|---|
microphone | Microphone access error (permission denied or unavailable) |
txn_init_failed | Failed to initialize transaction |
txn_limit_exceeded | Maximum number of concurrent transactions exceeded |
unknown_error | An unknown or unclassified error occurred |
txn_stop_failed | Error occurred while stopping the transaction |
audio_upload_failed | Audio file upload to server failed |
txn_commit_failed | Commit call failed for the current transaction |
invalid_request | Request to SDK was malformed or missing required parameters |
vad_not_initialized | Voice activity detection engine was not initialized |
no_audio_capture | No audio was captured during the recording session |
txn_status_mismatch | Invalid operation due to mismatched transaction status |

