@dialt/sdk

Version 0.48.0 includes breaking alpha API cleanup. Read the migration guide before upgrading.

The Browser SDK for the Dialt realtime API. It provides microphone capture, echo cancellation, streaming playback, interruptions, reconnects, text mode, and structured conversation events.

Install

npm install @dialt/sdk

Use the installed package through your application build. Do not expose a persistent API key in browser JavaScript.

The canonical Browser SDK guide covers the backend credential route, AudioWorklet assets, microphone lifecycle, input selection, events, tools, reconnection, text mode, and WebRTC. The WebSocket guide documents the wire protocol.

For an acknowledged same-session agent swap, call await client.handoffAgent({instructions, tools, voice?, context?, operationId?}). The SDK generates operationId when omitted; it correlates this live request only and is not a retry token. It resolves on the final applied or rejected acknowledgement (an optional queued one keeps it pending), and updates reconnect replay state only after application. Await it before another mode setter. On timeout or disconnect the outcome is uncertain and the SDK does not retry.

For host updates, await client.injectContext(text, { role: 'context', reply: true }) appends context immediately even while busy. An acknowledgement with accepted: true, reply_started: false, and queued: true means a reply waits for the next idle boundary. Waiting updates coalesce into one reply. Keep the same messageId and payload when retrying a lost acknowledgement; a replayed receipt describes the original acceptance. Reset, transfer teardown and session end cancel pending replies. User-role input retains its busy rejection.

Licensed under Apache-2.0.

Policy guidance

Define each rule once in mode.policy with id, when, and do:

{"include_instructions": true, "background_guidance": true,
 "rules": [{"id": "supervisor", "when": "The caller requests a supervisor.",
            "do": "Call request_supervisor and explain the tool result to the caller."}]}

Both switches default true and work independently. Declare and handle the tool normally; existing permission checks still apply. Background checks quietly inject guidance about the reviewed caller or assistant turn without requesting another reply or executing tools. Source revisions, flag updates/retractions, errors and completion events are reported through the ordinary event interface. Delivery is not proof the agent complied.

Policy rules use id, when and do; legacy action configurations are rejected. See the policy contract.

Voice selection uses the server roster from GET /v1/voices. Irish Male keeps the stable key classic. Circuit (circuit) is the default when no voice or saved preference is supplied. Empty keys are rejected locally; unknown, retired or unavailable keys return the server's nonretryable invalid_voice error. A rejected mid-session switch leaves the confirmed voice unchanged, including on reconnect. Retired keys must be replaced explicitly.