← Back to Documentation

Assistants

An assistant is a callable voice agent. Configure personality, voice, reasoning mode, and behavioral controls to create the exact experience you need.

Creating an Assistant

Create an assistant with a POST to /v1/assistants:

Terminal
curl https://api.aployee.com/v1/assistants \
  -H "Authorization: Bearer $APLOYEE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "SalesBot",
    "system_prompt": "You are an enthusiastic sales representative for Acme Corp.",
    "personality": {
      "formality": "casual",
      "assertiveness": "high",
      "empathy": "medium",
      "talkativeness": "high"
    },
    "voice": {
      "provider": "azure",
      "voice_id": "en-US-JennyNeural"
    },
    "reasoning_mode": "webhook",
    "webhook_url": "https://api.example.com/aployee"
  }'

Personality Sliders

Control how your assistant communicates with four intuitive sliders:

SliderOptionsEffect
formalitycasual | neutral | formalLanguage style: contractions, vocabulary, structure
assertivenesslow | medium | highHow directly the assistant pushes toward goals
empathylow | medium | highEmotional acknowledgment and validation
talkativenesslow | medium | highResponse length and elaboration

Internally, these map to DISC-based behavioral patterns. You get predictable speech patterns without needing to understand psychology models.

Archetypes

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

Archetypes
// Available archetypes
{
  "archetype": "challenger"  // Direct, results-oriented, challenges assumptions
}

{
  "archetype": "helper"      // Supportive, empathetic, service-focused
}

{
  "archetype": "counselor"   // Thoughtful, balanced, advisory
}

{
  "archetype": "collaborator" // Team-oriented, consensus-building
}

{
  "archetype": "mentor"      // Patient, growth-focused, educational
}

{
  "archetype": "architect"   // Strategic, big-picture, systematic
}

{
  "archetype": "analyst"     // Data-driven, logical, precise
}

{
  "archetype": "storyteller" // Narrative-driven, engaging, creative
}

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.

Voice Settings

Configure text-to-speech voice for your assistant:

FieldDescription
providerTTS provider: azure
voice_idVoice identifier (e.g., en-US-JennyNeural)
speaking_rateSpeed adjustment: 0.5 to 2.0 (default 1.0)

Behavioral Controls

Override prompt and personality with explicit configuration. No guesswork:

Behavioral Controls
{
  "behavioral_controls": {
    "max_call_duration_seconds": 600,
    "silence_timeout_ms": 5000,
    "max_consecutive_silences": 3,
    "escalation_rules": [
      {
        "trigger": "user_says_supervisor",
        "action": "transfer",
        "target": "+15551234567"
      }
    ],
    "disconnect_rules": [
      {
        "trigger": "user_says_goodbye",
        "action": "end_call"
      }
    ],
    "banned_phrases": ["competitor_name", "pricing_override"],
    "transfer_target": "+15559876543"
  }
}

Control Reference

  • max_call_duration_seconds - Auto-end call after this duration
  • silence_timeout_ms - How long to wait for user speech
  • max_consecutive_silences - End call after this many silences
  • escalation_rules - When and how to escalate/transfer
  • disconnect_rules - Conditions for ending the call
  • banned_phrases - Words/phrases the assistant must never say
  • transfer_target - Default number for transfers

Reasoning Modes

Choose how your assistant handles complex decisions:

ModeBest ForConfiguration
builtinPrototypes, demosNo additional config needed
webhookCustom logic, your own LLMSet webhook_url
mcpTool integrationsSet mcp_config

Next steps