Overview

The WebSocket Secure (WSS) API enables real-time, bidirectional communication with the Corti system for interaction streaming. Clients can send and receive structured data, including transcripts and facts updates.

This documentation provides a structured guide for integrating the Corti WSS API for real-time interaction streaming.

This /stream endpoint supports real-time ambient documentation interactions.

  • If you are looking for a stateless, atomic endpoint that is more geared towards front-end dictation workflows you should use the /transcribe WSS
  • If you are looking for asynchronous ambient documentation interactions, then please refer to the /documents endpoint

Environment Options

EnvironmentDescription
usUS-based instance
euEU-based instance
beta-euBeta EU instance (default)

Establishing a Connection

Clients must initiate a WebSocket connection using the wss:// scheme and provide a valid interaction ID in the URL.

When creating an interaction, the 200 response provides a websocketUrl for that interaction including the tenant-name as url parameter. The authentication for the WSS stream requires in addition to the tenant-name parameter a token parameter to pass in the Bearer access token.

Request

Path Parameters

id
string
required

Unique interaction identifier

Query Parameters

tenant-name
string
required

Specifies the tenant context

token
string
required
Bearer $token

Responses

101 Switching Protocols

Indicates a successful WebSocket connection. Once connected, the server streams data in the following formats.

By default, returned data streams as well as incoming audio are being saved. Based on the interactionId you can find the saved transcripts and facts and recording(s) in the relevant REST endpoints. Audio recordings are saved as .webm format. This can be configured by Corti to be turned off to ensure you can comply with your applicable regulations and data handling preferences.

Data Streams

Transcript Stream

PropertyTypeDescription
typestringMessage type (transcript)
data.idstringUnique identifier for the transcript
data.transcriptstringThe transcribed text
data.finalbooleanIndicates whether the transcript is finalized or interim
data.participant.channelstringThe audio channel for the participant (e.g. 0 or 1)
data.participant.rolestringRole of the participant (e.g., doctor)
data.time.startnumberStart time of the transcript segment
data.time.endnumberEnd time of the transcript segment
{
  "type": "transcript",
  "data": [
    {
    "id": "UUID",
    "transcript": "Patient presents with fever and cough.",
    "final": true,
    "speakerId": -1,
    "participant": { "channel": 0, "role": "doctor" },
    "time": { "start": 1.71, "end": 11.296 }
    }
  ]
}

Fact Stream

PropertyTypeDescription
typestringMessage type (facts)
data.idstringUnique identifier for the fact
data.textstringText description of the fact
data.groupstringCategorization of the fact (e.g., medical-history)
data.groupIdstringUnique identifier for the group
data.isDiscardedbooleanIndicates if the fact was discarded
data.sourcestringSource of the fact (e.g., core for generated automatically)
data.createdAtstringTimestamp when the fact was created
data.updatedAtstringTimestamp when the fact was last updated
{
  "type": "facts",
  "data": [
    {
    "id": "UUID",
    "text": "Patient has a history of hypertension.",
    "group": "medical-history",
    "groupId": "UUID",
    "isDiscarded": false,
    "source": "core",
    "createdAt": "2024-02-28T12:34:56Z",
    "updatedAt": "2024-02-28T12:35:56Z"
    }
  ]
}

Sending Messages

Clients must send a stream configuration message and wait for a response of type CONFIG_ACCEPTED before transmitting other data.

Stream Configuration

PropertyTypeRequiredDescription
typestringYesMessage type (config)
configurationobjectYesConfiguration settings
transcription.primaryLanguagestringYesPrimary spoken language for transcription
transcription.isDiarizationbooleanNo - falseEnable speaker diarization
transcription.isMultichannelbooleanNo - falseEnable multi-channel audio processing
transcription.participantsarrayYesList of participants with roles assigned to a channel
mode.typestringfacts, transcriptionProcessing mode
mode.outputLocalestringYesOutput language locale specific to facts

Example Configuration

{
  "type": "config",
  "configuration": {
    "transcription": {
      "primaryLanguage": "en",
      "isDiarization": false,
      "isMultichannel": false,
      "participants": [
        {
          "channel": 0,
          "role": "multiple"
        }
      ]
    },
    "mode": {
      "type": "facts",
      "outputLocale": "en"
    }
  }
}

Once the server responds with:

{
  "type": "CONFIG_ACCEPTED"
}

Clients can proceed with sending audio or controlling the stream status.

Controlling Stream Status

To end the stream, send:

{
  "type": "end"
}

The connection remains open until all transcripts are complete. The server then sends a message of type: "ENDED" and closes the connection.

Sending Audio Data

Ensure that your configuration was accepted before starting to send audio and that your initial audio chunk is not too small as it needs to contain the headers to properly decode the audio. We recommend sending audio in chunks of 500ms. In terms of buffering, the limit is 64000 bytes per chunk. Audio data should be sent as raw binary without JSON wrapping.

While we for bandwith and efficiency reasons recommend utilizing the webm/opus encoding, you can send a variety of common audio formats as the audio you send first passes through a transcoder. Similarly, you do not need to specify any sample rate, depth or other audio settings.

Channels, participants and speakers

In a typical on-site setting you will be sending mono-channel audio. If the microphone is a stereo-microphone, you can ensure to set isMultichannel: false and audio will be converted to mono-channel, ensuring no duplicate transcripts are being returned.

In a virtual setting such as telehealth, you would typically have the virtual audio on one channel from webRTC and mix in on a separate channel the microphone of the local client. In this scenario, define isMultichannel: true and assign each channel the relevant participant role, e.g. if the doctor is on the local client and channel 0, then you can set the role for channel 0 to doctor.

Diarization is independent of audio channels and participant roles. If you want transcript segments to be assigned to automatically identified speakers, set isDiarization: true. If false, transcript segments will be returned with speakerId: -1. If set to true, then diarization will try to identify speakers separately on each channel. The first identified speaker on each channel will have transcript segments with speakerId: 0, the second speakerId: 1 and so forth.

SpeakerIds are not related or matched to participant roles.

Error Handling

In case of an invalid or missing interaction ID, the server will return an error before opening the WebSocket.

From opening the WebSocket, you need to commit the configuration within 15 seconds, else the WebSocket will close again

During a WebSocket session the following messages related to configuration can be returned.


  {"type": "CONFIG_DENIED"} // in case the configuration is not valid
  {"type": "CONFIG_MISSING"}
  {"type": "CONFIG_NOT_PROVIDED"}
  {"type": "CONFIG_ALREADY_RECEIVED"}

In addition, a reason will be supplied, e.g. reason: language unavailable

Closing the Connection

To terminate the WebSocket session, send a standard WebSocket close frame, or use:

{
  "type": "end"
}

The connection remains open until all transcripts are complete, at which point the server sends a message of type ENDED and then closes.

You can at any time open the WebSocket again and resume by sending the configuration.