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:
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:
| Slider | Options | Effect |
|---|---|---|
| formality | casual | neutral | formal | Language style: contractions, vocabulary, structure |
| assertiveness | low | medium | high | How directly the assistant pushes toward goals |
| empathy | low | medium | high | Emotional acknowledgment and validation |
| talkativeness | low | medium | high | Response 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:
// 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:
| Field | Description |
|---|---|
| provider | TTS provider: azure |
| voice_id | Voice identifier (e.g., en-US-JennyNeural) |
| speaking_rate | Speed adjustment: 0.5 to 2.0 (default 1.0) |
Behavioral Controls
Override prompt and personality with explicit configuration. No guesswork:
{
"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 durationsilence_timeout_ms- How long to wait for user speechmax_consecutive_silences- End call after this many silencesescalation_rules- When and how to escalate/transferdisconnect_rules- Conditions for ending the callbanned_phrases- Words/phrases the assistant must never saytransfer_target- Default number for transfers
Reasoning Modes
Choose how your assistant handles complex decisions:
| Mode | Best For | Configuration |
|---|---|---|
| builtin | Prototypes, demos | No additional config needed |
| webhook | Custom logic, your own LLM | Set webhook_url |
| mcp | Tool integrations | Set mcp_config |
Next steps
- • Learn about webhook integration
- • Set up MCP for tool calls
- • Start making calls