Connections

Connection Types

The SDK supports different connection modes based on the provider:

API Key Connection

{
  apiKey: string;
  config?: BaseConfig;
}

Sofya Compliance Provider Connection

{
  provider: "sofya_compliance";
  endpoint: string;
  config: SofyaComplianceConfig;
}

Sofya As Service Provider Connection

{
  provider: "sofya_as_service";
  endpoint: string;
  config: SofyaSpeechConfig;
}

Configuration Types

BaseConfig

interface BaseConfig {
  language: string;
  external_id?: string;
  record?: boolean;
}

Field	Type	Description
external_id	string (optional)	Identifier of the consultation in your application. Sent to the server as the x-external-id query param on every connection — including reconnections — and used to group all recordings belonging to the same consultation. Must be opaque: a UUID, hash, or internal id — never a CPF, name, readable medical record number, or email. To be used literally in the recording's storage path it must match ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$ (starts with a letter or digit, up to 64 characters, no :, /, spaces or accents); outside that pattern the server stores the recording under a hash and keeps the original value only in the metadata. Maximum 512 characters. Use the same value on every reconnection for a given consultation.
record	boolean (optional)	Requests (true) or refuses (false) server-side recording of this session. When omitted, the SDK sends nothing and the environment's default decides. true only results in a recording if the environment allows it — otherwise the session proceeds normally. Recording never changes the transcription itself.

const transcriber = new SofyaTranscriber({
  provider: "sofya_as_service",
  endpoint: "<wss-url>",
  config: {
    language: "pt-BR",
    external_id: "<consultation-id>",
    record: true,
  },
});

Compatibility

external_id and record are additive and optional. Applications that don't set them keep working exactly as before, including against older servers.

SofyaComplianceConfig

interface SofyaComplianceConfig extends BaseConfig {
  token: string;
  compartmentId: string;
  region: string;
}

SofyaSpeechConfig

interface SofyaSpeechConfig extends BaseConfig {}

Connection Flow

API Key Connection Flow

1. The SDK authenticates with the Sofya API using the provided API key.
2. The API returns a list of available providers and their configurations.
3. The SDK attempts to connect to each provider in order until a successful connection is established.
4. Once connected, the SDK emits a 'ready' event.

Provider-Specific Connection Flow

1. The SDK attempts to connect directly to the specified provider using the provided endpoint and configuration.
2. Once connected, the SDK emits a 'ready' event.