Developers

Quickstart — First Call in 5 Minutes

Get your first AI voice call running in under 5 minutes. This guide uses the TypeScript SDK.

1. Install the SDK

bash

npm install @converse/sdk

2. Get your keys

Go to Settings → API Keys in your dashboard. You'll get two keys:

bash

# Secret key (server-side only — never expose)
export CONVERSE_API_KEY=sk_live_your_secret_key

# Publishable key (safe for client code)
export CONVERSE_PUBLIC_KEY=pk_live_your_public_key

3. Choose an active agent

Create and publish an agent in the dashboard, then read its public ID. Agent authoring remains an audited dashboard operation.

typescript

import { ConverseClient } from '@converse/sdk';

const converse = new ConverseClient({
  apiKey: process.env.CONVERSE_API_KEY!,
});

const agents = await converse.agents.list({ limit: 10 });
const agent = agents.data[0];
if (!agent) throw new Error('Publish an agent in the dashboard first');

console.log('Using agent:', agent.id);

4. Make an outbound call

typescript

const call = await converse.calls.create({
  agent_id: agent.id,
  to: '+919876543210',  // Phone number to call
  metadata: { task: 'Confirm tomorrow's appointment' },
});

console.log('Call initiated:', call.id, call.status);

Subscribe to live events through the dedicated realtime client:

typescript

import { ConverseRealtime, TRANSCRIPT, CALL_ENDED } from '@converse/sdk/realtime';

const realtime = new ConverseRealtime({ apiKey: process.env.CONVERSE_API_KEY! });
realtime.on(TRANSCRIPT, event => console.log(event.data));
realtime.on(CALL_ENDED, event => console.log('Call ended', event.data));
await realtime.connect();
realtime.subscribeToCall(call.id);

5. Or test in the browser (no phone needed)

typescript

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

// In your React component:
const { voiceState, agentState, connect, disconnect } = useConverseVoice({
  publicKey: 'pk_live_...',  // Publishable key — safe in client code
  agentId: agent.id,
});

// voiceState: idle → connecting → active → ended
// agentState: idle → connecting → listening → speaking
// Audio + mic handled automatically inside the SDK.

What's next?

Add tools so your agent can look up orders, create tickets, etc.
Upload a knowledge base so your agent can answer from your docs.
Connect a phone number to receive inbound calls.
Set up webhooks to get notified when calls complete.

Python quickstart

bash

pip install converse-ai

python

from converse import ConverseClient

client = ConverseClient(api_key="sk_live_your_key")

agents = client.agents.list(limit="10")
agent = agents["data"][0]

call = client.calls.create(
    agent_id=agent["id"],
    to="+919876543210",
    metadata={"task": "Confirm tomorrow's appointment"},
)
print(f"Call {call['id']} → {call['status']}")

Using with messaging channels

Connect and assign the channel under Channels. Incoming conversations then use the same agent automatically. The calls endpoint is voice-only; use Campaigns or the channel-specific dashboard controls for proactive messaging.

Languages and voices

Configure language, code-switching instructions, and a supported voice in the agent editor. These settings are not part of the public read-and-run API.