Text chat

Archived SDK documentation

This page preserves the previous SDK documentation and its existing URL. The generated API reference was produced from SDK 0.1.5, source commit 4db9fbe925bf07a4b95e936a5bb172d6ab5820bb. Handbook behavior and compatibility claims below are historical descriptions, not a newly verified support guarantee. For the reviewed version-specific reference, see the SDK 0.1.5 overview.

Open a text session when your app needs a typed conversation with no microphone or WebRTC setup. The SDK requests POST /api/v1/sessions/token with mode: 'text', connects the channel WebSocket, and routes your app's web_chat flow entry on the platform.

For the TelAPI wire format and REST upgrade/downgrade endpoints, see Browser SDK → Text chat.

Prerequisites

• An endpoint whose flow includes a web_chat entry point (visible in TelWeb under the endpoint's entry-point configuration).
• DelphiClient configured with apiDomain + apiKey, or a same-origin sessionTokenUrl proxy.
• Platform webrtc flag on (gates all SDK session routes, including text-only).

Check support before opening UI:

const caps = await delphi.getCapabilities(endpointId);

if (!caps.interactionModes.text) {
  throw new Error('This endpoint does not support text chat.');
}

const canHandoff =
  caps.runtime.migration.includes('text_to_voice') &&
  caps.runtime.migration.includes('voice_to_text');

Minimal example

const session = await delphi.openSession({
  endpointId: '24599c70-1e79-4e52-9819-e2d97acf45a5',
  mode: 'text',
});

session.onChat((chat) => {
  if (chat.role === 'assistant') {
    console.log('AI:', chat.content);
  }
});

session.sendTextChat('Hello — what can you help me with?');

sendTextChat sends a chat message with intent: 'conversation' and expects a text reply. For full control (context-only updates, read-aloud intents, preferred response mode), use sendChat() — see the API reference.

React — useDelphiSession

import {useDelphiSession} from '@ki-kombinat/delphi-client-js-sdk/react';

function ChatPanel({endpointId}: {endpointId: string}) {
  const {connected, messages, sendTextChat} = useDelphiSession({
    endpointId,
    mode: 'text',
  });

  const [input, setInput] = useState('');

  const visible = messages.filter(
    (m) => m.type === 'chat' && m.chat?.content && m.chat.intent !== 'browser_context',
  );

  return (
    <div>
      {!connected && <p>Connecting…</p>}
      <ul>
        {visible.map((m) => (
          <li key={m.messageId}>{m.chat!.content}</li>
        ))}
      </ul>
      <input
        value={input}
        onChange={(e) => setInput(e.target.value)}
        onKeyDown={(e) => {
          if (e.key === 'Enter' && input.trim()) {
            sendTextChat(input.trim());
            setInput('');
          }
        }}
      />
    </div>
  );
}

Attach <DelphiProvider> at the app root with the same DelphiClient instance — same pattern as the voice quick start.

Page context without a reply

Keep the AI aware of what the user sees:

session.setBrowserContext({
  text: document.body.innerText.slice(0, 4000),
  identifier: window.location.pathname,
  source: 'page',
});

This sends intent: 'browser_context' with responseExpected: false — no assistant turn is triggered.

Upgrade to voice

When the flow supports both web_chat and web_voice, migrate the live text session to a WebRTC call on the same sessionId:

delphi.setRemoteAudioElement(document.querySelector('#remote-audio')!);

await delphi.upgradeToVoice({
  endpointId,
  autoDial: true, // dial as soon as the SIP plugin registers
  browserContext: {identifier: 'browser-user-1'}, // optional, sent before dial
});

What the SDK does internally:

1. Confirms an open text session for endpointId.
2. POST /api/v1/sessions/upgrade with the current sessionId.
3. Closes the text WebSocket and opens voice_conversation with the upgraded token.
4. Re-imports prior chat messages into the new session for UI continuity.
5. Connects WebRTC using telproDomain / webrtcGatewayUrl from the upgrade response.

Attach the remote <audio> element before calling upgradeToVoice (same rule as Voice call).

Downgrade to text

Switch back to typed chat after a call:

const session = await delphi.downgradeToText({
  endpointId,
  endCallFirst: true, // default — hang up WebRTC before reopening text
});

session.sendTextChat('Thanks — can you summarise what we discussed?');

The SDK sends prepare_voice_to_text_handoff on the channel, calls POST /api/v1/sessions/downgrade, tears down WebRTC, and reopens mode: 'text' with the same sessionId.

Text overlay on a voice call (no migration)

If the user is already in a voice_conversation and you only want a typing panel alongside the call — without changing session mode:

const session = await delphi.startCall({endpointId, autoDial: true});

session.enableTextChat('text'); // AI replies in text; user can still speak
session.sendTextChat('Please email me the confirmation number.');

// later
session.disableTextChat();

Use upgradeToVoice / downgradeToText when the primary transport should switch between text-only and full voice. Use enableTextChat when voice remains the main session and text is auxiliary input.

Cleanup

await delphi.endSession(endpointId, 'text');
// or, if upgraded: await delphi.endCall()

Non-voice sessions also auto-close after sessionIdleTimeoutMs (default 5 minutes) when idle.

Common gotchas

• openSession({ mode: 'text' }) fails with 409 — endpoint flow lacks a web_chat entry or the endpoint is archived.
• Upgrade returns 503 — FEATURE_WEBRTC=false or TelPro is not configured on the deployment.
• No assistant reply to typed text on a voice call — call enableTextChat() first; by default voice sessions ignore chat unless text-chat mode is enabled.
• Stale getSession(endpointId) after handoff — pass the mode: getSession(endpointId, 'text') vs 'voice_conversation'.

Next step

Voice call — start directly in voice_conversation when you do not need a text-first UX.