Recording with the SDK

Once a way is set up to obtain a valid access token, follow these steps to add consultation recording to your application:

Initialize the SDK

Initialize the SDK in the client, using the access token obtained from your server.

Once you have obtained a valid access token via your backend, initialize the Squire SDK on the client instantiating the Squire class with the access token. The outputLanguage option should be set to the language in which the consultation report will be generated. (See Languages for supported languages.)


import Squire from '@squirehealth/sdk';
 
// Your logic to fetch an access token goes here ...
 
const squire = new Squire({
  token: 'REPLACE_WITH_ACCESS_TOKEN',
  outputLanguage: 'nl',
});

This step must only be done once. We recommend to do this after users log into your system, or on opening of the EHR client if they are already authenticated.

Once initialized, the SDK can be used.

Recording Flow

Get microphones

Get the list of available microphones. This is useful to show the user which microphone they can use for the consultation.


const audioInputs = await squire.getAudioInputs();

Calling this function also will request microphone permissions, if not yet granted.

The function returns a list of microphone devices, each with the following properties:

deviceId: The unique identifier of the microphone device.
label: The display name of the microphone device.
isDefault: A boolean indicating whether this is the default selected microphone.

Register event listeners


squire.on('summary-ready', (summary) => {
  if (summary.data === null) {
    // No report content. `summary.report_status` says why.
    return;
  }
 
  // `summary` contains the structured report data as generated by Squire
  // your logic to store consultation report data in the EHR goes here
});

Check summary.data before reading it. A consultation can end without any report content, in which case data is null and report_status says why. See Report status.

For information about the structure of the summary, see the output documentation.

Start a consultation

Start a consultation by calling the startRecording method. This will start a new consultation in the background and begin streaming audio. This method returns a promise that resolves with the Consultation object.


const consultation = await squire.startRecording();

By default, the same input language as the output language will be used. If you want to set a different input language, you can do so by passing the inputLanguage option when starting the consultation. (See Languages for supported languages.)

Likewise, the default audio input is the system default microphone. If you want to use a different microphone, you can pass the audioInput option of the desired microphone.


const consultation = await squire.startRecording({
  inputLanguage: 'fr',
  audioInput: audioInputs[0],
  templateId: 'specialist_general_api'
});

The templateId option is used to specify the template that will be used for the output summary. Supported: specialist_general_api, soap_new_complaint_api.

You can optionally set report length per consultation with writingStyle: brief, balanced, or detailed. If you omit it, the user’s default report length is used, as in earlier SDK versions.


const consultation = await squire.startRecording({
  inputLanguage: 'nl',
  templateId: 'soap_new_complaint_api',
  writingStyle: 'brief',
});

That default is the authenticated user’s report length preference stored for their account. To read it (for example to pre-fill your UI):


const defaultStyle = await squire.getDefaultWritingStyle();

To update it from your integration (for example so later calls without writingStyle use the new preference):


await squire.setDefaultWritingStyle('balanced');

Stop a consultation

Stop a consultation by calling the stopRecording method. This will stop the recording and close the consultation.


squire.stopRecording();

Once the consultation has finished processing, the summary-ready event will be emitted with the consultation data. That last event ends the recording whether or not a report was produced: if there is no report content, its data is null and report_status says why. See Report status.

Pausing and resuming a consultation

You can temporarily pause and later resume an ongoing consultation. This is useful if you want to temporarily stop recording without ending the consultation.

To pause recording:


squire.pauseRecording();

To resume recording:


squire.resumeRecording();

Retrieve a consultation summary

You can retrieve the full consultation summary at any time. This is useful if you need to fetch the summary data on-demand.

Using the Consultation object returned by startRecording:


const summary = await consultation.getSummary();

If you no longer hold the original Consultation object (e.g. after a page refresh), you can create one from a consultation ID using squire.consultation():


const consultation = squire.consultation('consultation-uuid');
const summary = await consultation.getSummary();

getSummary() resolves for a consultation with no report as well: it returns the consultation’s metadata with data set to null, and report_status explaining why. Check summary.data before iterating over it. See Report status.

For information about the structure of the summary, see the output documentation.

For advanced SOAP functionality including splitting and merging consultations, see the Multi-SOAP documentation.

For real-time transcription workflows, see the Dictation documentation.

Product usage

To fetch the remaining allowance per product for the signed-in user, see Product usage.

Error handling

For details on error handling, including built-in and explicit error handling strategies, as well as log level configuration, see the Error Handling page.