Sonde Health API Platform Documentation

Journaling API

Owned by Mohdsiddique Bagwan (Unlicensed)
Last updated: Sept 26, 2023 by Aman Jain
5 min read

Overview

Sonde APIs support Pass audio and the transcript

Voice sample collection for mental fitness requires 30-second voice audio sample. This voice sample request is made through a prompt. Users can be asked an insightful question or an open-ended question (“how are you feeling'). Sonde offers journaling capability such that the 30-second voice audio sample prompt can be transcribed. The transcribed text can be passed to partners for further analysis. Currently Sonde supports English language transcription.

Notes:

  • To access Journaling API, please contact Sonde at support@sondehealth.com. Please provide your company name and address

  • Refer Account for detail on how to create an account with Sonde

Limitation

  • Detection of voice sample and/or transcription including the intention of self-harm or harm to others is not supported.

Journal Deletion

  • Sonde can delete voice samples and/or transcribed journals for a specific user or group of users. Sonde can also selectively deleted specific sessions such as for the past week date range or last 4 journals. The request to delete needs to be made by sending an email with the user identifier number and specific deletion request to support@sondehealth.com

 

As a Developer, I want to transcribe user’s audio file

Refer Account for detail on how to create an account with Sonde and get the client-id & client-secret to complete below steps.

On your backend perform the below steps to transcribe an audio file.

STEP 1: GET THE APPROPRIATE ACCESS-TOKEN
STEP 2: REGISTER A USER WITH SONDE HEALTH
STEP 3: GET THE S3 SIGNED URL TO UPLOAD YOUR AUDIO FILE
STEP 4: RECORD YOUR AUDIO FILE
STEP 5: UPLOAD YOUR AUDIO FILE
STEP 6: CREATE TRANSCRIBE JOB
STEP 7: POLL TRANSCRIBE JOB

 

Detailed explanation with curl examples of each step is given below.

STEP 1: GET THE APPROPRIATE ACCESS-TOKEN

Get the access-token with scopes sonde-platform/users.write sonde-platform/transcriptions.write sonde-platform/transcriptions.read sonde-platform/storage.write.

Ensure your client-credentials are granted to these scopes during the registration/onboarding process with Sonde Health.

curl --request POST 'https://api.sondeservices.com/platform/v1/oauth2/token' \ --header 'Authorization: Basic <Base64EncodedString>' \ --header 'Content-Type: application/x-www-form-urlencoded' \ --data-urlencode 'grant_type=client_credentials' \ --data-urlencode 'scope=sonde-platform/users.write sonde-platform/transcriptions.write sonde-platform/transcriptions.read sonde-platform/storage.write'

Replace <Base64EncodedString> with the output of below command

$ echo -n "<clientid>:<clientsecret>" | openssl base64 -A

 

Response1:

{ "access_token": "ya29.QQIBibTwvKkE39hY8mdkT_mXZoRh7Ub9cK9hNsqrxem4QJ6sQa36VHfyuBe", "expire_in": 3600, "token_type": "Bearer" }

 

STEP 2: REGISTER A USER WITH SONDE HEALTH

Use "access_token" to register a user. Put the value of access_token into the Authorization header (refer to the below curl command).

It is expected that your server will register the user with SondePlatform during user sign-up process.

Replace <access_token> with the value of access_token attribute from Response1.

Note - Partners can send their userIdentifier in query parameter in below API if they wish to register a user with Sonde Heath using their user identifier, this will help Partners to map Sonde data

 

Response2:

Capture the userIdentifier, in the below response wiNODNXcm. This userIdentifier will be required while calling the /inference/voice-feature-scores API in the following steps.

Keep userIdentifier in your UserManagement module (or database) to later use it for same patient.
userIdentifier will be used in STEP 3.

STEP 3: GET THE S3 SIGNED URL TO UPLOAD YOUR AUDIO FILE

Call Storage Service to get the signed URL. In the Authorization header put the value of the access_token attribute from Response1 and the country-code in which you want to upload the wave file.

countryCode should be the country information that you have used while creating the account with Sonde Health.

Replace <access_token> with the access_token attribute’s value from Response1.

Replace <userIdentifier> with the userIdentifier attribute’s value from Response2.

 For detail information on capturing Mode, Please refer Capturing Mode

Response3:

The response is shown for illustration purposes.

The signedURL is required in STEP 5.

The filePath is required in STEP 6

 

STEP 4: RECORD YOUR AUDIO FILE

Record audio file.

Sonde recommends the following listed code snippet to record audio file:

 

Please find the sample wav file of 30 seconds length.

 

STEP 5: UPLOAD YOUR AUDIO FILE

Replace <audioFilePath> with the value of filePath attribute from Response3.

You can expect the 20X response code for the above-mentioned API.

 

STEP 6: CREATE TRANSCRIBE JOB

Call the /platform/async/v1/transcriptions API to create a transcribe job. Refer to the below curl command.

Replace <access_token> with the value of access_token attribute from Response1.

Replace <filePath> with the value of the path attribute of Response3.

 

Response4:

 

STEP 7: POLL TRANSCRIBE JOB

Call the /platform/async/v1/transcriptions/{jobId}.

Replace <jobId> with the value of jobId attribute from Response4.

Replace <access_token> with the value of access_token attribute from Response1.

 

Response5:

For 30 seconds audio file, it is recommended to perform the first poll API call at an interval of 15 seconds and the subsequent poll API call at an interval of 3 seconds.

Call above API till in response status == "IN_PROGRESS".

On status == "DONE", you will get transcribe of the audio file.

Please refer API REST API Reference for more detail on API request, response.

Sonde Health