--- name: suki-dictation description: >- Use when building real-time clinical Dictation with Suki: embed Dictation with the Dictation SDK or Web SDK, or use the Dictation APIs to create a transcription session, stream PCM audio over /ws/transcribe, receive partial and final transcript text, and end the session. license: SUKI_Proprietary metadata: author: suki version: "2.4" --- ## Dictation Use **Dictation** to convert spoken audio into text in real time. Dictation is a transcription workflow. It does not generate a full Ambient clinical note or populate Suki Medical form templates. Use: - **Ambient** for clinical note generation from visit conversations. - **Form filling** for structured Medical form output. - **Dictation** for real-time speech-to-text. - **Audio streaming** for shared WebSocket and audio wire-format details. ## Accuracy rules - Do not invent endpoints, SDK methods, request fields, response fields, or WebSocket message types. - Use `/ws/transcribe` for Dictation API audio streaming. - Do not use Ambient `/ws/stream` message formats on `/ws/transcribe`. - Dictation audio messages use `audioData`, not `data`. - Dictation ends an audio stream with the `AUDIO_END` event. - Do not use Ambient `START_TIME` or `RU9G` on the Dictation WebSocket. - Create a transcription session before opening `/ws/transcribe`. - Open a Dictation WebSocket only when the transcription session is in a state that allows streaming, such as `READY` or `IDLE`. - Do not assume that a single WebSocket connection represents the entire transcription session. Suki supports multiple streams under the same `transcription_session_id`. - Treat `is_final: false` transcript frames as intermediate text that can change. - Treat `is_final: true` transcript frames as final text for that segment. - Treat a transcript whose text is `EOF` as the end of results for that WebSocket. - Close the WebSocket before calling the REST end-session API. - For browser integrations, prefer the Dictation SDK or Web SDK rather than building the REST and WebSocket flow yourself. - Do not mix Dictation SDK instructions with Headless Web SDK Ambient hooks. - If this skill does not define a required detail, read the linked Dictation documentation or use the documentation MCP before generating code. ## Choose an integration path Once the path is known, **fetch that dedicated skill** and implement from it. | Path | Choose when | Dedicated skill | | --- | --- | --- | | **Dictation SDK** | You want Suki's hosted Dictation experience embedded in your application | `suki-dictation-sdk` | | **Web SDK Dictation** | You already use the Headed Web SDK and want its Dictation component | `suki-web-sdk` | | **Dictation API** | Your application owns audio capture and needs direct `/ws/transcribe` control | `suki-dictation-api` | Skill URLs: - Dictation SDK: https://developer.suki.ai/.well-known/agent-skills/suki-dictation-sdk/SKILL.md - Web SDK: https://developer.suki.ai/.well-known/agent-skills/suki-web-sdk/SKILL.md - Dictation API: https://developer.suki.ai/.well-known/agent-skills/suki-dictation-api/SKILL.md For browser applications, use the SDK or Web SDK unless you specifically need direct control over the Dictation API. ### Environment For direct API integrations, use staging unless the user explicitly requests production. | Environment | REST | WebSocket | | --- | --- | --- | | Staging | `https://sdp.suki-stage.com` | `wss://sdp.suki-stage.com` | | Production | `https://sdp.suki.ai` | `wss://sdp.suki.ai` | ## Dictation API workflow The API workflow is: ```text authenticate → create transcription session → wait until session is ready for streaming → connect to /ws/transcribe → send AUDIO messages → receive partial and final transcripts → send AUDIO_END → receive EOF → close WebSocket → end transcription session ``` ### API endpoints | Operation | Method | Path | | --- | --- | --- | | Login | `POST` | `/api/v1/auth/login` | | Register | `POST` | `/api/v1/auth/register` | | Create session | `POST` | `/api/v1/transcription/session/create` | | Stream audio | `WebSocket` | `/ws/transcribe` | | End session | `POST` | `/api/v1/transcription/session/{transcription_session_id}/end` | ## 1. Authenticate Dictation API requests use a Suki Token. The authentication flow is: ```text Partner Token → Suki authentication → Suki Token → Dictation API ``` Follow the Partner Authentication documentation for the authentication flow that applies to your partner type. Use the resulting token as: ```http sdp_suki_token: {sdp_suki_token} ``` for Dictation REST requests and the WebSocket handshake. Send: ```http sdp_provider_id: {provider_id} ``` when required by your partner configuration. ### Keep authentication separate from the SDK For the Dictation API, your application manages the Suki Token and sends it to the REST and WebSocket APIs. For the Dictation SDK or Web SDK, use the SDK's `SukiAuthManager`. Do not copy the raw API authentication flow into SDK code unless the SDK documentation explicitly requires it. ## 2. Create a transcription session Create a parent transcription session before opening the WebSocket: ```http POST /api/v1/transcription/session/create ``` Include: ```http Content-Type: application/json sdp_suki_token: {sdp_suki_token} ``` The request body is optional. You can provide an audio configuration: ```json { "audio_config": { "audio_encoding": "LINEAR16", "audio_language": "en-US", "sample_rate_hertz": 16000 } } ``` The documented defaults are: | Setting | Value | | --- | --- | | `audio_encoding` | `LINEAR16` | | `audio_language` | `en-US` | | `sample_rate_hertz` | `16000` | Currently, Dictation supports English (`en-US`). `audio_config` is optional. If omitted, Suki uses the documented defaults. The response contains: ```json { "transcription_session_id": "..." } ``` Save this identifier. Use the same `transcription_session_id` when: - Connecting to `/ws/transcribe`. - Reconnecting a WebSocket. - Opening multiple streams for the same parent session. - Ending the transcription session. ## 3. Wait for a streamable session After creating the transcription session, check the session state before opening `/ws/transcribe`. Open the WebSocket when the session is: ```text READY ``` or: ```text IDLE ``` Do not open the WebSocket when the session is already: ```text RUNNING ``` or: ```text COMPLETED ``` The WebSocket handshake can fail with `FailedPrecondition` when the session is not ready for a new stream. ### Multiple streams A transcription session can contain multiple WebSocket streams. All streams use the same: ```text transcription_session_id ``` Suki combines transcripts from the streams into the parent transcription session. This is useful for: - Reconnecting after a dropped WebSocket. - Push-to-talk workflows. - Streaming from multiple audio sources. - Workflows that contain multiple speech segments. Do not create a new parent transcription session simply because a WebSocket connection needs to be reopened. ## 4. Connect to `/ws/transcribe` Connect to: ```text wss://sdp.suki-stage.com/ws/transcribe ``` for staging or: ```text wss://sdp.suki.ai/ws/transcribe ``` for production. ### Browser authentication Browser clients authenticate during the WebSocket handshake with the `Sec-WebSocket-Protocol` header: ```http Sec-WebSocket-Protocol: SukiTranscriptionAuth,, ``` Use the exact protocol name: ```text SukiTranscriptionAuth ``` The order is: ```text SukiTranscriptionAuth → sdp_suki_token → transcription_session_id ``` Do not replace `SukiTranscriptionAuth` with the Ambient WebSocket protocol. ### Non-browser authentication Non-browser clients send the following headers during the WebSocket upgrade: ```http sdp_suki_token: {sdp_suki_token} transcription_session_id: {transcription_session_id} ``` Do not send authentication credentials as ordinary WebSocket messages after the connection is established. ## 5. Stream audio Send audio as JSON text frames. The message format is: ```json { "type": "AUDIO", "audioData": "" } ``` The audio field is: ```text audioData ``` not: ```text data ``` ### Audio requirements Use the audio configuration specified when creating the transcription session. The standard configuration is: | Setting | Value | | --- | --- | | Encoding | `LINEAR16` | | Sample rate | `16000` Hz | | Channels | Match the supported source configuration | | Transport | Base64 inside a JSON text frame | Encode the raw PCM audio bytes with standard Base64. Do not send: - Raw binary WebSocket frames. - WAV container data. - Base64 of a WAV file. - Hex-encoded audio. - Ambient `AUDIO.data` messages. ### Stream in chunks Send audio in small, regular chunks rather than sending the complete recording in one message. Chunked streaming reduces latency and allows Suki to return transcript updates while the provider is speaking. For audio chunking and performance guidance, use the current Dictation streaming documentation. ## 6. Receive transcript messages Suki sends transcript messages over the WebSocket. A partial transcript can look like: ```json { "transcript": { "transcript": "the recognized text so far", "words": [] }, "is_final": false, "transcript_id": "..." } ``` A final transcript can look like: ```json { "transcript": { "transcript": "The patient reports feeling better today.", "words": [] }, "is_final": true, "transcript_id": "..." } ``` ### Partial transcripts When: ```json "is_final": false ``` the transcript is intermediate. It can change as more audio is processed. Use partial transcripts for live UI updates, but do not treat them as final clinical text. ### Final transcripts When: ```json "is_final": true ``` the transcript for that segment is final. The recognizer will not revise that segment. Use final transcripts when your application needs stable transcript text. ### `transcript_id` Transcript messages can contain: ```text transcript_id ``` Use this identifier when your application needs to correlate or track individual transcript segments. Do not invent transcript IDs. ## 7. End an audio stream When the current speech stream is finished, send: ```json { "type": "EVENT", "event": "AUDIO_END" } ``` `AUDIO_END` tells Suki that the current audio stream has ended. Do not use the Ambient stream terminator: ```text RU9G ``` Do not send: ```json { "type": "AUDIO", "data": "RU9G" } ``` That format belongs to the Ambient-style `/ws/stream` protocol. ## 8. Wait for `EOF` After sending `AUDIO_END`, continue reading WebSocket messages. Suki sends an end-of-results message: ```json { "transcript": { "transcript": "EOF" } } ``` Treat: ```text transcript.transcript == "EOF" ``` as the end of results for the current WebSocket stream. The WebSocket closes shortly after `EOF`. Do not treat the literal text `EOF` as clinical transcript content. ## 9. Close the WebSocket After receiving `EOF`, close the WebSocket. Do not call the REST end-session endpoint while the WebSocket is still being used for the current stream. The normal sequence is: ```text AUDIO_END → receive final transcript messages → receive EOF → close WebSocket → REST end session ``` ## 10. End the transcription session When the complete Dictation workflow is finished, call: ```http POST /api/v1/transcription/session/{transcription_session_id}/end ``` Include: ```http sdp_suki_token: {sdp_suki_token} ``` The response can include: ```json { "transcription_session_id": "...", "status": "completed", "final_transcript": "...", "duration": 300, "ended_at": "2024-11-26T10:35:00Z" } ``` Use `final_transcript` when your application needs the final session-level transcript. Do not assume that every intermediate WebSocket transcript is identical to the final session transcript. ## Push-to-talk workflow Dictation supports multiple streaming connections under one parent transcription session. For push-to-talk: ```text create transcription session → wait for READY / IDLE → open WebSocket → stream speech → AUDIO_END → receive EOF → close WebSocket → wait for READY / IDLE → open a new WebSocket → stream next speech segment → ... → end parent transcription session ``` Reuse the same: ```text transcription_session_id ``` for the speech segments. Do not create a new parent session for every push-to-talk segment unless your application specifically needs separate transcription sessions. ## WebSocket reconnection WebSocket connections can drop. If the parent transcription session is still active: 1. Detect the dropped connection. 2. Check that the transcription session can accept another stream. 3. Reconnect using the same `transcription_session_id`. 4. Resume streaming. 5. Continue processing transcript messages. Do not blindly reconnect to a session that has already reached a terminal state. ## Dictation SDK Use the Dictation SDK when you want Suki's hosted Dictation UI rather than building the complete REST and WebSocket workflow. The Dictation SDK embeds Dictation through a Suki-hosted iframe. The SDK handles the Dictation UI and provides callbacks for the text returned to your application. Read the current Dictation SDK documentation for the exact packages and APIs available to your partner. ## Dictation Web SDK The Suki Web SDK also supports Dictation. For React applications, the current Web SDK documentation uses: ```text @suki-sdk/core @suki-sdk/react ``` Install: ```bash pnpm add @suki-sdk/core @suki-sdk/react ``` The React Web SDK exposes: ```text SukiAuthManager DictationClient DictationProvider Dictation ``` Use the Web SDK path when your application already uses the Suki Web SDK. ## Web SDK authentication Create one `SukiAuthManager` with your partner credentials. Example: ```ts import { SukiAuthManager } from "@suki-sdk/core"; const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", partnerToken: "YOUR_PARTNER_TOKEN", environment: "staging", loginOnInitialize: true, autoRegister: false, providerId: "YOUR_PROVIDER_ID", providerName: "YOUR_PROVIDER_NAME", providerOrgId: "YOUR_PROVIDER_ORG_ID", providerSpecialty: "YOUR_PROVIDER_SPECIALTY", }); ``` Use only the provider fields required by your partner configuration. Do not expose partner credentials in client-side source when your integration architecture requires server-side credential handling. ## Create a Web SDK Dictation client Create one `DictationClient` and reuse it for the page or application scope. For React, create it with `useMemo` so it is not recreated on every render. Example: ```tsx import { useMemo } from "react"; import { SukiAuthManager } from "@suki-sdk/core"; import { DictationClient } from "@suki-sdk/react"; const client = useMemo(() => { const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", partnerToken: "YOUR_PARTNER_TOKEN", environment: "staging", loginOnInitialize: true, autoRegister: false, providerId: "YOUR_PROVIDER_ID", providerName: "YOUR_PROVIDER_NAME", providerOrgId: "YOUR_PROVIDER_ORG_ID", providerSpecialty: "YOUR_PROVIDER_SPECIALTY", }); return new DictationClient({ authManager }); }, []); ``` Do not create a new `DictationClient` for every field or React render. ## Render Dictation in React Wrap the Dictation component with: ```tsx ``` Example: ```tsx import { useMemo, useState } from "react"; import { SukiAuthManager } from "@suki-sdk/core"; import { DictationClient, DictationProvider, Dictation, } from "@suki-sdk/react"; export function NotesWithDictation() { const client = useMemo(() => { const authManager = new SukiAuthManager({ partnerId: "YOUR_PARTNER_ID", partnerToken: "YOUR_PARTNER_TOKEN", environment: "staging", loginOnInitialize: true, autoRegister: false, providerId: "YOUR_PROVIDER_ID", providerName: "YOUR_PROVIDER_NAME", providerOrgId: "YOUR_PROVIDER_ORG_ID", providerSpecialty: "YOUR_PROVIDER_SPECIALTY", }); return new DictationClient({ authManager }); }, []); const [notes, setNotes] = useState(""); const [dictationActive, setDictationActive] = useState(false); return (