Juvoly V2 WebSocket API
This page provides an overview of how to interact with our WebSocket API. For detailed code examples, check out the following links:
Overview
To use the WebSocket API, follow these two steps:
- Create a session using HTTP: Use your client ID and API key to establish a session.
- Open a WebSocket: Initiate the WebSocket for the session to begin transcribing and summarizing.
See an overview of the interaction below:
Create a Session
See HTTP API documentation for details on how to get the session token.
Open a WebSocket
After obtaining the sessionId, you can establish a WebSocket connection.
This can be done directly from the client, such as a web browser.
There’s no need to redirect audio through your back-end.
Create the Connection
To create the connection, use the following WebSocket URL:
wss://services.juvoly.nl/api/v2/socket/<model>
For the model parameter you can choose from the values below. Choose generic if in doubt.
| name | Experimental | Comment |
|---|---|---|
| generic | no | Default. Improved support for medical terms. Only supports Dutch. |
| multilingual | no | Supports 90+ languages. |
| kolibri | yes | Under development. Faster and more precise version of the “generic” model. |
| radiology | no | Special support for radiology style transcripts. |
You’ll need to provide the following subprotocol headers:
- “v2.juvoly”
- ”<client id>”
- ”<session id>”
Note:
The headers are specified in line with https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Sec-WebSocket-Protocol.
The order of the values is important.
After successfully connecting, wait for a ready message from the server before sending any other data. The message will look like this:
{
"type": "ready"
}
Using PCM
The WebSocket API supports sending audio blobs in most common formats like wav/flac/mp3.
If you want to publish audio in the PCM format you will need to specify the URL parameter encoding=PCM.
So to create the connection, use the following WebSocket URL instead:
wss://services.juvoly.nl/api/v2/socket/<model>?encoding=PCM
Start Transcribing
When you receive the “ready” message, you can begin sending audio blobs over the WebSocket connection. The audio data can be transmitted directly as raw bytes, without any additional protocol. For more details on how to send audio blobs, check out the language-specific examples linked at the beginning of this page.
After sending audio blobs, you will begin receiving transcription utterances in real time. While audio is being transcribed you will also receive utterances that did not finish processing yet. This will be indicated by the completed field being set to false. The content may change in subsequent messages until the completed value is received.
Example completed message:
{
"type": "transcript",
"utterance":
{
"id": "0",
"sentence": "Goedemiddag.",
"words":
[
{
"word": "Goedemiddag.",
"start": 8.48,
"end": 9.12,
}
]
},
"completed": true
}
Example intermediate update that is not yet finalized and completed:
{
"type": "transcript",
"utterance":
{
"id": "1",
"sentence": "Wat heeft",
"words":
[
{
"start": 9.84,
"end": 9.92,
"word": "Wat"
},
{
"start": 10.08,
"end": 10.16,
"word": "heeft"
}
]
},
"completed": false
}
Request Mapping Including Summarization
To map the transcript so far to a document like for example a summary, send the following request over the WebSocket connection:
{
"type": "map",
"templateKey": "<template-key>"
"templateParameters": {
"<parameter-key>": "<parameter-value>"
}
}
Note that the template key is generally expected to be chosen based on the returned templates from the template endpoint described in HTTP API.
If you’re just looking for a SOAP/SOEP summary you can fill in soap as template key.
The parameters are optional and can be omitted if in doubt.
Shortly after submitting your request, you will receive a message containing the mapped documents. It will look like the example below:
{
"type": "mapping",
"documents":
[
{
"fields":
[
{
"key": "subjective",
"name": "Subjectief",
"value": "Keelpijn en hoofdpijn al 2 weken."
},
{
"key": "objective",
"name": "Objectief",
"value": ""
},
{
"key": "assessment",
"name": "Evaluatie",
"value": "Mogelijke infectie van de keel."
},
{
"key": "plan",
"name": "Plan",
"value": "Antibiotica voorgeschreven."
}
],
"resources":
[]
},
{
"fields":
[
{
"key": "subjective",
"name": "Subjectief",
"value": "Plekje op de voet, behandeling gewenst."
},
{
"key": "objective",
"name": "Objectief",
"value": ""
},
{
"key": "assessment",
"name": "Evaluatie",
"value": "Niet gedefinieerd, verdere evaluatie nodig."
},
{
"key": "plan",
"name": "Plan",
"value": "Verwijzing naar dermatoloog."
}
],
"resources":
[]
}
]
}
Request Summarization (deprecated)
Note: This request is deprecated. Please use the map request described above instead.
To request a summarization to SOEP format, send a request over the WebSocket connection. The request format should be as follows:
{
"type": "summarizeSoep"
}
Shortly after submitting your request, you will receive a message containing the summary. It will look like the example below:
{
"type": "summarySoep",
"summary":
{
"episodes":
[
{
"subjective": "Keelpijn en hoofdpijn al 2 weken.",
"objective": "",
"evaluation": "Mogelijke infectie van de keel.",
"plan": "Antibiotica voorgeschreven."
},
{
"subjective": "Plekje op de voet, behandeling gewenst.",
"objective": "",
"evaluation": "Niet gedefinieerd, verdere evaluatie nodig.",
"plan": "Verwijzing naar dermatoloog."
}
]
}
}
Subscribe to Information
It is possible to subscribe to information that is extracted live from the transcript. Information consists of:
- Codings - Snomed, ICPC
- Resources - thuisarts.nl, NHG guideline
- Measurements - weight, length, temperature, pulse, pack years, blood pressure, oxygen saturation
This can be done by sending the following message:
{
"type": "subscribe",
"subscription":
{
"type": "information"
}
}
After doing so you will start receiving information if relevant information is found. It is possible that no relevant information is found so you won’t receive information messages. Example information:
{
"type": "information",
"codings":
[
{
"system": "snomed",
"code": "392570002",
"description": "bevinding betreffende bloeddruk"
},
{
"system": "icpc",
"code": "K29",
"description": "Andere symptomen/klachten hartvaatstelsel"
}
],
"resources":
[
{
"link": "https://www.thuisarts.nl/hoge-bloeddruk",
"description": "Hoge bloeddruk",
"origin": "Thuisarts"
},
{
"link": "https://richtlijnen.nhg.org/standaarden/cardiovasculair-risicomanagement",
"description": "",
"origin": "NHG"
}
],
"measurements":
[
{
"description": "Bloeddruk",
"value": "140/90",
"unit": "mmHg",
"codings": [
{
"system": "nhg-table-45",
"code": "RRSYKA",
"value": "180"
},
{
"system": "nhg-table-45",
"code": "RRDIKA",
"value": "90"
}
]
}
]
}