← Back to Documentation

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
1

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 includes: { "id": "asst_xxxx", ... }

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
2

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"
  }'

# The call begins immediately.
# View transcript, timeline, and audio in the admin dashboard.

Call request fields

  • assistantId - Which assistant handles the call
  • toPhoneNumber - Destination phone in E.164 format
  • fromPhoneNumber - (Optional) Caller ID to display

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, add:
{
  "reasoningWebhook": {
    "url": "https://your-api.com/voicerail",
    "bearerToken": "your-secret-token",
    "timeoutSeconds": 5
  }
}

// Your webhook receives:
{
  "callId": "call_abc123",
  "utterance": "What the user just said",
  "state": { /* JSON preserved across call */ },
  "context": [ /* Recent dialogue */ ]
}

// Return:
{
  "reply": "What assistant says (optional)",
  "state": { /* Updated state */ }
}

Learn more in the webhook integration guide.

Understanding DISC profiles

DISC is a behavioral psychology model with four dimensions:

DimensionHigh ScoreLow Score
DominanceDirect, decisive, results-focusedCollaborative, supportive
InfluenceEnthusiastic, persuasive, optimisticReserved, factual
SteadinessPatient, reliable, calmDynamic, flexible
ConscientiousnessAnalytical, precise, quality-focusedBig-picture, informal

Learn more in the DISC psychology guide.

Next steps