Quickstart

Make your product callable by phone in under 5 minutes. VoiceRail handles the conversation with built-in AI - no webhook required to get started.

Prerequisites

# Prerequisites
# - VoiceRail API key (from dashboard)
# - Organization ID (from dashboard)
# - That's it! No webhook or server needed to start

Create an assistant

An assistant is a callable voice agent with personality. Define its name, archetype, DISC profile, and voice. VoiceRail's built-in AI handles conversations automatically.

Terminal

curl -X POST https://api.voicerail.ai/v1/assistants \
  -H "Authorization: Bearer $VOICERAIL_KEY" \
  -H "X-Organization-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex",
    "archetype": "helper",
    "discProfile": {
      "dominance": 45,
      "influence": 70,
      "steadiness": 60,
      "conscientiousness": 50
    },
    "voice": {
      "provider": "azure",
      "voiceId": "en-US-JennyNeural"
    }
  }'

# Response:
# {
#   "id": "asst_xxxx",
#   "organizationId": "org-your-org-id",
#   "name": "Alex",
#   "archetype": "helper",
#   "personalityStage": 1,
#   "discProfile": {
#     "dominance": 45,
#     "influence": 70,
#     "steadiness": 60,
#     "conscientiousness": 50
#   },
#   "voice": {
#     "provider": "azure",
#     "voiceId": "en-US-JennyNeural",
#     "sttProvider": "azure"
#   },
#   "firstMessageMode": "assistant-speaks-first",
#   "createdAt": "2026-03-15T12:00:00Z"
# }

Required fields

name - Human-readable name for your assistant
archetype - Base personality: helper, challenger, mentor, analyst, etc.
discProfile - DISC behavioral profile (0-100 for each dimension)
voice - TTS configuration with provider and voiceId

Make a call

Start a call with your assistant. The call begins immediately. You can monitor the live transcript, timeline, and audio in the dashboard.

Terminal

curl -X POST https://voice.voicerail.ai/api/v1/calls \
  -H "Authorization: Bearer $VOICERAIL_KEY" \
  -H "X-Organization-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "asst_xxxx",
    "toPhoneNumber": "+15551234567"
  }'

# Response:
# {
#   "callId": "call_abc123",
#   "assistantId": "asst_xxxx",
#   "status": "initiating",
#   "toPhoneNumber": "+15551234567",
#   "fromPhoneNumber": "+18882881634",
#   "startedAt": "2026-03-15T12:01:00Z"
# }
#
# The call begins immediately.
# If fromPhoneNumber is omitted, the assistant's provisioned number is used.
# View transcript, timeline, and audio in the dashboard.

Call request fields

assistantId - Which assistant handles the call
toPhoneNumber - Destination phone in E.164 format
fromPhoneNumber - (Optional) Caller ID shown to recipient. If omitted, uses the phone number provisioned for this assistant. Required if no number is provisioned.

Phone number required

To make outbound calls, provision a phone number for your assistant from the dashboard. This number is used as the caller ID automatically. You can also pass a specific fromPhoneNumber to override.

That's it!

Your assistant is now making AI-powered voice calls with personality-driven conversations. No webhook, no server, no complex setup.

Level 2: Add custom reasoning (Optional)

Want to integrate your own business logic? Add a webhook to control reasoning and handle complex decisions. Your webhook receives context and returns replies.

Webhook (Optional)

// Optional: Add custom reasoning via webhook
// In your assistant creation or update, add:
{
  "reasoningWebhook": {
    "url": "https://your-api.com/voicerail",
    "bearerToken": "your-secret-token",
    "timeoutSeconds": 10
  }
}

// VoiceRail sends your webhook (with Authorization: Bearer header):
{
  "userInput": "What the caller just said",
  "conversationHistory": [
    { "role": "assistant", "content": "Hi! How can I help?" },
    { "role": "user", "content": "What the caller just said" }
  ],
  "callId": "c9f2a1b3-...",
  "organizationId": "org-abc123",
  "model": "gpt-4o-mini",
  "assistantRole": "Your assistant's system prompt..."
}

// Return:
{
  "content": "What the assistant says",
  "confidenceScore": 4
}

Learn more in the webhook integration guide.

Understanding DISC profiles

DISC is a behavioral psychology model with four dimensions:

Dimension	High Score	Low Score
Dominance	Direct, decisive, results-focused	Collaborative, supportive
Influence	Enthusiastic, persuasive, optimistic	Reserved, factual
Steadiness	Patient, reliable, calm	Dynamic, flexible
Conscientiousness	Analytical, precise, quality-focused	Big-picture, informal

Learn more in the DISC psychology guide.

Next steps

• Configure assistant personality and voice
• Add MCP tools for external integrations (optional)
• Set up custom hold music
• Try the live demo to hear it in action