Assistants

Creating an Assistant

Create an assistant with a POST to /v1/assistants. Only name, archetype, discProfile, and voice are required:

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_a1b2c3d4",
  "name": "Alex",
  "archetype": "helper",
  "discProfile": { ... },
  "createdAt": "2024-01-15T10:30:00Z"
}

Required Fields

Field	Description
name	Human-readable name for your assistant
archetype	Base personality pattern (see Archetypes below)
discProfile	DISC behavioral profile (0-100 for each dimension)
voice	TTS configuration with provider and voiceId

DISC Profile

DISC is a behavioral psychology model with four dimensions. Each dimension is scored 0-100 and influences how your assistant communicates:

Dimension	High Score (70+)	Low Score (30-)
Dominance	Direct, decisive, results-focused	Collaborative, supportive, patient
Influence	Enthusiastic, persuasive, optimistic	Reserved, factual, analytical
Steadiness	Patient, reliable, calm	Dynamic, flexible, fast-paced
Conscientiousness	Analytical, precise, quality-focused	Big-picture, informal, flexible

Learn more in the DISC psychology guide.

Archetypes

Archetypes provide pre-configured conversation patterns with "beats" - natural conversation milestones that guide the flow:

challenger

Direct and results-oriented. Challenges assumptions and drives toward decisions. Great for sales.

helper

Supportive and service-focused. Prioritizes user needs and satisfaction. Perfect for support.

mentor

Patient and educational. Uses Socratic questioning to help users learn. Ideal for training.

analyst

Data-driven and precise. Structures conversations around facts and evidence. Great for technical support.

counselor

Thoughtful and balanced. Provides guidance while respecting autonomy. Good for advisory roles.

collaborator

Team-oriented and consensus-building. Works alongside users toward shared goals.

architect

Strategic and systematic. Takes a big-picture approach to problem-solving.

storyteller

Narrative-driven and engaging. Uses stories and examples to communicate.

Voice Settings

Configure text-to-speech voice for your assistant:

Field	Description
provider	TTS provider: `azure`
voiceId	Voice identifier (e.g., `en-US-JennyNeural`, `en-US-GuyNeural`)

Popular Azure Voices

en-US-JennyNeural - Female, conversational, warm
en-US-GuyNeural - Male, friendly, professional
en-US-AriaNeural - Female, neutral, clear
en-US-DavisNeural - Male, calm, authoritative

Call Configuration (Optional)

Customize how your assistant handles calls:

Field	Description
quickGreeting	Short intro phrase played immediately (e.g., "Hey, this is Sarah")
firstMessage	First full message after greeting (null = DISC-based greeting)
firstMessageMode	`assistant-speaks-first` (default) or `assistant-waits-for-user`
voicemailMessage	Message to leave on voicemail (outbound only)
endCallMessage	Message to say when ending the call
endCallPhrases	Phrases that trigger automatic call ending
transferDestinations	Phone numbers for the transferCall tool

Full Example

A fully-configured sales assistant with custom persona and transfer destinations:

Full Configuration

{
  "name": "SalesBot",
  "archetype": "challenger",
  "discProfile": {
    "dominance": 75,
    "influence": 80,
    "steadiness": 35,
    "conscientiousness": 55
  },
  "voice": {
    "provider": "azure",
    "voiceId": "en-US-GuyNeural"
  },
  "quickGreeting": "Hey, this is Mike from Acme",
  "firstMessage": "I noticed you started a trial last week. How's it going so far?",
  "endCallMessage": "Great talking with you!",
  "endCallPhrases": ["goodbye", "have a great day", "talk soon"],
  "transferDestinations": [
    {
      "phoneNumber": "+15551234567",
      "name": "Sales Manager",
      "description": "Escalate pricing or contract questions",
      "transferMode": "warm-transfer-with-summary"
    }
  ],
  "personaFingerprint": {
    "stockPhrases": ["here's the thing", "let me be direct"],
    "acknowledgments": ["got it", "absolutely"],
    "contractionLevel": 85,
    "turnTakingStyle": "confirmations"
  }
}

Persona Fingerprint (Optional)

Fine-tune natural speech characteristics. If not provided, defaults are auto-generated from the DISC profile:

Persona Fingerprint

{
  "personaFingerprint": {
    "stockPhrases": ["here's the thing", "let me think", "I've seen this before"],
    "preferredHedges": ["kind of", "I think", "probably"],
    "acknowledgments": ["got it", "I hear you", "makes sense"],
    "fillerPreferences": ["well", "so", "I mean"],
    "turnTakingStyle": "mixed",
    "contractionLevel": 70,
    "speechRate": 10,
    "pitchAdjustment": 0
  }
}

Fingerprint Fields

stockPhrases - Repeated phrases for personality consistency (max 5)
preferredHedges - Hedging expressions like "kind of", "probably" (max 5)
acknowledgments - Responses like "got it", "I hear you" (max 5)
fillerPreferences - Fillers like "well", "so" (max 3)
turnTakingStyle - How to end turns: questions, confirmations, or mixed
contractionLevel - 0-30 formal, 31-70 casual, 71-100 very casual
speechRate - Speed adjustment (-50 to +50)
pitchAdjustment - Pitch adjustment (-20 to +20)

Custom Reasoning Webhook (Optional)

Integrate your own reasoning model or business logic. The webhook receives conversation context and returns responses:

Reasoning Webhook

{
  "reasoningWebhook": {
    "url": "https://your-api.com/voicerail/reasoning",
    "bearerToken": "your-secret-token",
    "timeoutSeconds": 5
  }
}

Learn more in the webhook integration guide.