TS sdk

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
• npm or yarn for 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 using npm or yarn:

npm install @eka-care/ekascribe-ts-sdk
# or
yarn add @eka-care/ekascribe-ts-sdk

Usage

1. Get Ekascribe Instance

It will give you the main class instance, use this instance to access all methods

getEkaScribeInstance({
  access_token: '<your_access_token>',
});

const ekaScribe = getEkaScribeInstance({ access_token: 'old_token' });

2. Fetch configurations list

Get supported input languages, output formats, and consultation modes.

ekascribe.getEkascribeConfig();

• Sample Response:

{
  "data": {
    "supported_languages": [
      { "id": "en", "name": "English" },
      { "id": "hi", "name": "Hindi" }
    ],
    "supported_output_formats": [{ "id": "clinical-notes-template", "name": "Clinical Notes" }],
    "consultation_modes": [
      {
        "id": "consultation",
        "name": "Consultation",
        "desc": "Eka Scribe will listen to your conversation and create clinical notes"
      }
    ],
    "max_selection": {
      "supported_languages": 2,
      "supported_output_formats": 2,
      "consultation_modes": 1
    },
    "user_details": {
      "fn": "Dr. John",
      "mn": "",
      "ln": "Doe",
      "dob": "1985-06-15",
      "gen": "M",
      "s": "active",
      "is_paid_doc": true,
      "uuid": "user-uuid-123"
    },
    "wid": "workspace-id-456"
  },
  "message": "Configuration fetched successfully",
  "code": 200
}

3. Init transaction

Use this method to init a transaction before starting recording.

await ekascribe.initTransaction({
  mode: 'consultation',
  input_language: ['te', 'en'],
  output_format_template: [{ template_id: 'eka_emr_template' }],
  txn_id: 'abc-123',
  auto_download: false,
  model_training_consent: false,
  transfer: 'vaded' | 'non-vaded',
  model_type: 'pro' | 'lite',
  system_info: {
    platform: 'web',
    language: 'en',
    time_zone: 'Asia/Kolkata',
  },
  patient_details: {
    username: 'John Doe',
    age: 35,
    biologicalSex: 'M',
  },
  version: '1.0.0',
  flavour: 'web' | 'extension',
});

• Sample Response:

{
  "status_code": 200,
  "message": "Transaction initialized successfully",
  "business_id": "biz_abc123def456",
  "txn_id": "abc-123",
  "oid": "org_789xyz",
  "uuid": "user_uuid_456"
}

4. Start recording

Start recording with user-selected options.

await ekascribe.startRecording();

• Sample Response:

{
  "status_code": 200,
  "message": "Recording started successfully",
  "txn_id": "abc-123",
  error_code?: ERROR_CODE
}

5. Pause recording

Use the method to pause voice recording

await ekascribe.pauseRecording();

• Sample Response:

{
  "status_code": 200,
  "message": "Recording paused successfully",
  "is_paused": true,
  error_code?: ERROR_CODE,
}

6. Resume recording

Use the method to resume voice recording

await ekascribe.resumeRecording();

• Sample Response:

{
  "status_code": 200,
  "message": "Recording resumed successfully",
  "is_paused": false,
  error_code?: ERROR_CODE,
}

7. End recording

Use the method to end voice recording

await ekascribe.endRecording();

• Sample Response:

{
  "status_code": 200,
  "message": "Recording ended and files uploaded successfully",
  failed_files?: ['1.mp3', '2.mp3']; // if there are any failed files
  total_audio_files?: ['1.mp3', '2.mp3', '3.mp3', '4.mp3']; // list of all audio files generated
  error_code?: ERROR_CODE;
}

8. Retry upload recording

Use this method to retry uploading failed audio files.

await ekascribe.retryUploadRecording({ force_commit: true });

• Sample Response:

{
  "status_code": 200,
  "message": "All files uploaded successfully after retry",
  error_code?: ERROR_CODE;
  failed_files?: ['1.mp3', '2.mp3'];
  total_audio_files?: ['1.mp3', '2.mp3', '3.mp3', '4.mp3'];
}

force_commit behavior

— If force_commit is set to true, the SDK will call the commit API even if some audio files still fail to upload after retrying once.

— If force_commit is set to false, the SDK will wait until all audio files are uploaded successfully before making the commit request.

9. Patch recording session status

Use the method to cancel a recording session.

await ekascribe.patchSessionStatus({
  sessionId: 'abc-123',
  processing_status: 'cancelled',
  processing_error: {
    error: {
      type: 'user_action',
      code: 'cancelled_by_user',
      msg: 'Session cancelled by user',
    },
  },
});

• Sample Response:

{
  "status": "success",
  "message": "Session status updated successfully",
  "code": 200,
  error?: {
    code: string;
    message: string;
    display_message: string;
  };
}

10. Commit transaction

Use this method to commit a transaction that is not yet committed or returned a “commit failed” error in a previous step.

await ekascribe.commitTransactionCall();

• Response type:

{
  error_code?: ERROR_CODE;
  status_code: number;
  message: string;
};

11. Stop transaction

Use this method to stop a transaction that has not yet been stopped or returned a “stop failed” error in a previous step.

await ekascribe.stopTransactionCall();

• Response type:

{
  error_code?: ERROR_CODE;
  status_code: number;
  message: string;
};

12. Get output template prescriptions

Use this method to fetch the final generated prescription output for a session.

await ekascribe.getTemplateOutput({ txn_id: 'abc-123' });

13. Get previous sessions

Use this method to retrieve all the previous sessions for a specific doctor ID

const sessions = await ekascribe.getSessionHistory({ txn_count: 10 });

• Response type:

{
  data: [
    {
      "created_at": "string",
      "b_id": "string",
      "user_status": "string",
      "processing_status": "string",
      "txn_id": "string",
      "mode": "string",
      "uuid": "string",
      "oid": "string"
    }
  ],
  status: "string",
  code: "number",
  message: "string",
  retrieved_count: "number"
}

14. Get All Templates

Use this method to retrieve all available templates for the current user.

const templates = await ekascribe.getAllTemplates();

• Response type:

{
  items: [
    {
      id: "123;
      title: "Template Name";
      desc: "Template Description";
      section_ids: ["section-1", "section-2"];
      is_editable: true | false;
    }
  ];
  code: number;
  error?: { code: string; message: string };
}

15. Create Template

Use this method to create a new custom template.

const newTemplate = await ekascribe.createTemplate({
  title: 'My Custom Template',
  desc: 'Description of the template',
  section_ids: ['section1', 'section2', 'section3'],
});

• Response type:

{
  code: number;
  msg: string;
  template_id?: string;
  message?: string;
  error?: { code: string; message: string };
}

16. Edit Template

Use this method to update an existing template.

const updatedTemplate = await ekascribe.updateTemplate({
  template_id: 'template-123',
  title: 'Updated Template Title',
  desc: 'Updated description',
  section_ids: ['section1', 'section2', 'section4'],
});

• Response type:

{
  code: number;
  msg: string;
  template_id?: string;
  message?: string;
  error?: { code: string; message: string };
}

17. Delete Template

Use this method to delete an existing template.

const deleteResult = await ekascribe.deleteTemplate('template-123');

• Response type:

{
  code: number;
  msg: string;
  template_id?: string;
  message?: string;
  error?: { code: string; message: string };
}

18. Generate Template with AI by giving a prompt

Use this method to generate a template using AI with a text prompt.

const formData = new FormData();
formData.append('content', 'Create a cardiology consultation template');
formData.append('file', file);
formData.append('contentType', 'text/file');

const aiTemplate = await ekascribe.aiGenerateTemplate(formData);

• Response type:

{
  title: string;
  desc: string;
  sections: [
    {
      id: string;
      title: string;
      desc: string;
      format: 'P' | 'B';
      example: string;
      default?: boolean;
      parent_section_id?: string;
    }
  ];
  code: number;
  message: string;
}

19. Add templates to list

Use this method to mark templates as favourite templates.

const configUpdate = await ekascribe.updateConfig({
  my_templates: ['template1', 'template2'],
});

• Response type:

{
  auto_download?: boolean;
  default_languages?: string[];
  my_templates?: string[];
  scribe_enabled?: boolean;
  msg: string;
  code: number;
  error?: { code: string; message: string };
}

20. Get All Sections

Use this method to retrieve all available template sections.

const sections = await ekascribe.getAllTemplateSections();

• Response type:

{
  items: [
    {
      id: string;
      title: string;
      desc: string;
      format: 'P' | 'B';
      example: string;
      default?: boolean;
      parent_section_id?: string;
    }
  ];
  code: number;
  error?: { code: string; message: string };
}

21. Create Section in a template

Use this method to create a new section that can be used in templates.

const newSection = await ekascribe.createTemplateSection({
  title: 'Chief Complaint',
  desc: "Patient's primary concern",
  format: 'P', // 'P' for paragraph, 'B' for bullet points
  example: 'Patient presents with chest pain for 2 days',
});

• Response type:

{
  msg: string;
  section_id: string;
  code: number;
  action: 'updated' | 'created_custom';
  error?: { code: string; message: string };
}

22. Edit Section in a template

Use this method to update an existing template section.

const updatedSection = await ekascribe.updateTemplateSection({
  section_id: 'section-123',
  title: 'Updated Chief Complaint',
  desc: 'Updated description',
  format: 'B',
  example: 'Updated example text',
});

• Response type:

{
  msg: string;
  section_id: string;
  code: number;
  action: 'updated' | 'created_custom';
  error?: { code: string; message: string };
}

23. Delete Section from a template

Use this method to delete a template section.

const deleteResult = await ekascribe.deleteTemplateSection('section-123');

• Response type:

{
  msg: string;
  section_id: string;
  code: number;
  action: 'updated' | 'created_custom';
  error?: { code: string; message: string };
}

24. Convert a transaction into another template after prescription generation

Use this method to convert an existing transaction’s output to use a different template format.

const convertResult = await ekascribe.postTransactionConvertToTemplate({
  txn_id: 'abc-123',
  template_id: 'new-template-456',
});

• Response type:

{
  status: 'success' | 'failed';
  message: string;
  txn_id: string;
  template_id: string;
  b_id: string;
  code: number;
  msg: string;
  error?: { code: string; message: string; display_message: string };
}

25. Search past sessions by a patient name

Use this method to search through previous sessions by patient name.

// First get session history
const sessions = await ekascribe.getSessionHistory({ txn_count: 50 });

// Then search by patient name
const filteredSessions = await ekascribe.searchSessionsByPatientName({
  sessions: sessions.data || [],
  patientName: 'John Doe',
});

• Response type:

// Returns filtered array of session history data
[
  {
    created_at: 'string',
    b_id: 'string',
    user_status: 'string',
    processing_status: 'string',
    txn_id: 'string',
    mode: 'string',
    uuid: 'string',
    oid: 'string',
    patient_details: {
      username: 'string',
      oid: 'string',
      age: number,
      biologicalSex: 'M' | 'F' | 'O',
      mobile: 'string',
      email: 'string',
    },
  },
];

26. Upload audio file to get output summary

Use this method to upload audio files directly and get transcription output without real-time recording.

const audioFiles = [file1, file2]; // File or Blob objects
const audioFileNames = ['audio1.mp3', 'audio2.mp3'];

const uploadResult = await ekascribe.uploadAudioWithPresignedUrl({
  action: 'upload',
  audioFiles,
  audioFileNames,
  mode: 'consultation',
  txn_id: 'upload-session-123',
  input_language: ['en'],
  output_format_template: [{ template_id: 'eka_emr_template' }],
  transfer: 'non-vaded',
  auto_download: false,
  model_training_consent: false,
  system_info: {
    platform: 'web',
    language: 'en',
    time_zone: 'Asia/Kolkata',
  },
  model_type: 'pro',
});

• Response type:

{
  error_code?: ERROR_CODE;
  status_code: number;
  message: string;
  business_id?: string;
  txn_id?: string;
  oid?: string;
  uuid?: string;
}

27. Edit output summary

Use this method to edit the generated output summary for a completed transaction.

const editResult = await ekascribe.updateResultSummary({
  txnId: 'abc-123',
  data: [
    {
      'template-id': 'eka_emr_template',
      data: 'Updated prescription content here',
    },
  ],
});

• Response type:

{
  status: string;
  message: string;
  txn_id: string;
  b_id: string;
  code: number;
  error?: { code: string; message: string; display_message: string };
}

Utility Methods

const ekaScribe = getEkaScribeInstance({ access_token: 'old_token' });

1. Get total uploaded files

Use this method to retrieve all the audio files generated for a specific session.

const files = ekascribe.getTotalAudioFiles();

• Response type:

['1.mp3', '2.mp3', '3.mp3', '4.mp3'];

2. Get successfully uploaded files

Use this method to retrieve all the audio files that were uploaded successfully.

const successFiles = ekascribe.getSuccessFiles();

• Response type:

['3.mp3', '4.mp3'];

3. Get failed audio files

Use this method to retrieve all the audio files that failed to upload.

const failedFiles = ekascribe.getFailedFiles();

• Response type:

['1.mp3', '2.mp3'];

4. Reset Class Instance

Use this method to reset the EkaScribe instance and clear all stored data.

ekaScribe.resetEkaScribe();

5. Reinitialise VAD Instance

Use this method to reinitialize the Voice Activity Detection (VAD) instance.

ekaScribe.reinitializeVad();

6. Pause VAD Instance

Use this method to pause the Voice Activity Detection without stopping the recording session.

ekaScribe.pauseVad();

7. Destroy VAD Instance

Use this method to completely destroy the VAD instance and free up resources.

ekaScribe.destroyVad();

8. Update Authentication Tokens

Use this method to update the access token without reinitializing the entire SDK instance.

ekaScribe.updateAuthTokens({ access_token: 'new_token' });

Generic Callbacks

const ekaScribe = getEkaScribeInstance({ access_token: 'your_token' });

1. Event callback

This is a comprehensive callback that provides information about SDK operations, including success events, errors, progress updates, and system status. Use this callback to monitor all SDK activities and handle events globally in your application.

ekaScribe.onEventCallback((eventData) => {
  console.log('Event callback triggered:', eventData);
});

• Sample Callback Data:

{
  callback_type: 'AUDIO_UPLOAD' | 'TRANSACTION_STATUS' | 'VAD_STATUS' | 'RECORDING_STATUS',
  status: 'success' | 'error' | 'progress' | 'info',
  message: 'Audio file uploaded successfully',
  error?: {
    code: 500,
    msg: 'Upload failed',
    details: { fileName: 'audio_chunk_1.mp3' }
  },
  data?: {
    success: 3,
    total: 4,
    is_uploaded: true,
    fileName: 'audio_chunk_1.mp3',
    request: { txn_id: 'abc-123' },
    response: { status: 'uploaded' }
  },
  timestamp: '2024-01-15T10:30:45.123Z',
  metadata?: {
    txn_id: 'abc-123',
    chunk_index: 1
  }
}

2. User speech callback

This callback will return a boolean indicating whether the user is speaking or not.

ekaScribe.onUserSpeechCallback((isSpeech) => {
  console.log(isSpeech ? 'User is speaking' : 'User is not speaking');
});

3. VAD Callback to check if a frame is valid speech or not

This callback provides information about voice activity detection frames and audio processing status.

ekaScribe.onVadFramesCallback((vadData) => {
  console.log('VAD frame processed:', vadData);
});

• Sample Callback Data:

{
  status_code: 200,
  message: 'Audio captured. | No audio captured.',
  error_code?: 'speech_detected' | 'no_audio_capture'
}

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

Refer Ekascribe for SDK implementations.