Converse Documentation

Client SDKs

Add AI voice and chat to any app. One package per platform — installs in seconds, handles everything internally.

What client SDKs do

Client SDKs run on your user's device (browser, phone). They connect to Converse using a short-lived token from your backend, handle audio/WebSocket transport, emit state events, and render UI components. Your API key never touches the client.

Available Platforms

Web (React + Vanilla JS)

@converse/web

npm i @converse/sdk

React Native

@converse/react-native

npm i @converse/react-native

iOS (Swift)

ConverseSDK

SwiftPM

Android (Kotlin)

io.converse:converse-sdk

Gradle

Flutter (Dart)

converse_sdk

pub.dev

Features (All Platforms)

Voice Calls

Connect to AI agents with real-time voice. Mic, speaker, state — all managed.

Chat

WebSocket-based real-time messaging with streaming responses.

State Machine

voiceState (idle→connecting→active→ended) + agentState (listening→thinking→speaking)

UI Components

Pre-built visualizers and chat views — swap colors/sizes, same props.

Token Auth

Production-ready: tokenProvider function fetches short-lived tokens from YOUR backend.

Custom Branding

Zero Converse branding exposed to end users. Full customization.

Architecture

// Production flow:

┌──────────────┐ ┌───────────────┐ ┌─────────────────┐

│ Your App │ │ Your Backend │ │ Converse Cloud │

│ (Client SDK)│ │ (Server SDK) │ │ │

├──────────────┤ ├───────────────┤ ├─────────────────┤

│ tokenProvider│────▶│ tokens.create │────▶│ validates key │

│ │◀────│ return token │◀────│ returns token │

│ connect(token)│───────────────────────────▶│ WebRTC/WSS │

│ state events │◀─────────────────────────────│ voice + chat │

└──────────────┘ └───────────────┘ └─────────────────┘

Quick Example (React)

tsx

import { useConverseVoice, ConverseOrb } from '@converse/sdk/components';

function VoiceAgent() {
  const { voiceState, agentState, connect, disconnect } = useConverseVoice({
    agentId: 'agent_xxx',
    tokenProvider: async () => {
      const res = await fetch('/api/token', { method: 'POST', body: JSON.stringify({ agentId: 'agent_xxx' }) });
      return res.json();
    },
  });

  return (
    <ConverseOrb
      state={agentState}
      size="lg"
      color="#7c3aed"
      onClick={voiceState === 'idle' ? connect : disconnect}
    />
  );
}