​
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.

​
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:

​
Data Streams

​
Transcript Stream

PropertyTypeDescription
typestringMessage type (transcript)
data.idstringUnique identifier for the transcript
data.transcriptstringThe transcribed text
data.isFinalbooleanIndicates whether the transcript is finalized
data.participant.idstringParticipant identifier
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",
    "start": 12345.67,
    "duration": 5.0,
    "transcript": "Patient presents with fever and cough.",
    "isFinal": true,
    "participant": { "id": "UUID", "role": "doctor" },
    "time": { "start": 12345.67, "end": 12350.67 }
    }
  ]
}

​
Fact Stream

PropertyTypeDescription
typestringMessage type (fact)
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., EHR)
data.createdAtstringTimestamp when the fact was created
data.updatedAtstringTimestamp when the fact was last updated
{
  "type": "fact",
  "data": [
    {
    "id": "UUID",
    "text": "Patient has a history of hypertension.",
    "group": "medical-history",
    "groupId": "UUID",
    "isDiscarded": false,
    "source": "EHR",
    "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 language for transcription
transcription.isDiarizationbooleanNo - falseEnable speaker diarization
transcription.isMultichannelbooleanNo - falseEnable multi-channel audio processing
transcription.participantsarrayYesList of participants with roles
mode.typestringfactsProcessing mode
mode.outputLocalestringYesOutput language locale

​
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. 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.

​
Error Handling

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

​
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.

Was this page helpful?

List All Interactions