Quick Start

Get your first voice AI conversation running in under 5 minutes.

Step 1: Register & Login

BASH

# Register a new account
curl -X POST https://ultravoice.us.inc/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass123!",
    "first_name": "Dev",
    "last_name": "User"
  }'

Check your email for a 6-digit OTP code, then verify:

BASH

curl -X POST https://ultravoice.us.inc/api/v1/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "code": "482916"}'

Now login to get your JWT token:

BASH

curl -X POST https://ultravoice.us.inc/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "SecurePass123!"}'

# Response:
# { "data": { "access_token": "eyJhbGci...", "refresh_token": "...", "expires_in": 86400 } }

BASH

export TOKEN="eyJhbGciOiJIUzI1NiIs..."

Step 2: Create an Agent

An Agent is a voice AI assistant with its own personality, providers, and configuration.

BASH

curl -X POST https://ultravoice.us.inc/api/v1/agents/ \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "system_prompt": "You are a friendly support agent. Keep responses concise — 1-2 sentences max.",
    "welcome_message": "Hello! How can I help you today?",
    "workspace_id": "YOUR_WORKSPACE_ID",
    "language": "en"
  }'

BASH

export AGENT_ID="a1b2c3d4-..."

Step 3: Configure AI Providers

Each agent needs three providers: LLM (brain), ASR (ears), and TTS (voice).

LLM — OpenAI GPT-4o Mini

BASH

curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider_type":"llm","provider_name":"openai","api_key":"sk-proj-...","model_name":"gpt-4o-mini"}'

ASR — Deepgram Nova-2

BASH

curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider_type":"asr","provider_name":"deepgram","api_key":"dg_...","model_name":"nova-2"}'

TTS — ElevenLabs Turbo

BASH

curl -X POST https://ultravoice.us.inc/api/v1/agents/$AGENT_ID/providers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"provider_type":"tts","provider_name":"elevenlabs","api_key":"sk_...","model_name":"eleven_turbo_v2_5","voice_id":"pFZP5JQG7iQjIQuC4Bku"}'

Step 4: Start a Voice Session

BASH

curl -X POST https://ultravoice.us.inc/api/v1/voice/sessions/start \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"'$AGENT_ID'","user_id":"user-123","welcome_message":"Hello!"}'

# Response:
# { "session_id": "f7e8d9c0-...", "agent_id": "...", "status": "ready" }

Step 5: Connect via WebSocket

Connect to stream audio in real-time:

TEXT

wss://ultravoice.us.inc/api/v1/voice/ws/f7e8d9c0-...

Send: Raw PCM Int16 audio at 16kHz mono (binary frames)
Receive: WAV-wrapped PCM audio (binary) + JSON events (text)

Using the Dashboard

The easiest way to test is the built-in Voice Test page:

Log in to the dashboard
Navigate to Voice Test in the sidebar
Select your agent from the dropdown
Click Start Conversation and speak into your microphone

💡

No code required for testing! The dashboard handles WebSocket connection, audio capture, and playback automatically.