Agents

Agents are AI-powered voice assistants that handle phone conversations. Each agent has its own personality, knowledge, and capabilities defined through configuration.

Agent Components

An agent consists of three main AI components:

Speech-to-Text (STT)

Converts the caller's speech to text. Currently powered by Deepgram.

{
  "stt_config": {
    "provider": "deepgram",
    "model": "nova-3-general",
    "language": "nl",
    "keyterms": ["ja", "nee", "oké"]
  }
}

Field	Description
`provider`	STT provider (`deepgram`)
`model`	Model name (e.g., `nova-3-general`)
`language`	Language code (e.g., `nl`, `en`)
`keyterms`	Optional array of words to boost recognition accuracy

Language Model (LLM)

The brain of your agent. Processes the conversation and generates responses.

{
  "llm_config": {
    "provider": "openai",
    "model": "gpt-4o-mini",
    "temperature": 0.7,
    "messages": [
      {
        "role": "system",
        "content": "Je bent een vriendelijke klantenservice medewerker..."
      }
    ],
    "tools": []
  }
}

Field	Description
`provider`	LLM provider (`openai`, `anthropic`, `groq`)
`model`	Model name (e.g., `gpt-4o-mini`, `claude-3-sonnet`)
`temperature`	Response randomness (0-2, default 0.7)
`messages`	System prompts defining agent behavior
`tools`	Custom tools the agent can use (see Custom Tools)

Text-to-Speech (TTS)

Converts the agent's text responses to speech.

{
  "tts_config": {
    "provider": "elevenlabs",
    "model": "eleven_flash_v2_5",
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "language": "nl",
    "stability": 0.5,
    "similarity_boost": 0.75,
    "use_speaker_boost": true
  }
}

Available Providers:

Provider	Description	Access
`local`	Cost-efficient Piper TTS (96 voices, 35+ languages)	All users
`openai`	OpenAI TTS with natural voices	All users
`elevenlabs`	High-quality voice cloning and natural speech	All users
`cartesia`	Ultra-low latency TTS	All users

Common Fields:

Field	Description
`provider`	TTS provider
`voice_id`	Voice identifier (snake_case)
`language`	Language code (e.g., `nl`, `en`)
`model`	Model name (provider-specific)

ElevenLabs-specific:

Field	Description
`stability`	Voice consistency (0-1, default 0.5)
`similarity_boost`	Voice similarity to original (0-1, default 0.75)
`use_speaker_boost`	Enhance speaker clarity (boolean)
`speed`	Speech speed multiplier
`style`	Speaking style intensity (0-1)

Agent Properties

Property	Type	Description
`id`	UUID	Unique identifier (auto-generated)
`name`	string	Display name for the agent
`business_name`	string	Business the agent represents
`notification_email`	email	Email for call notifications
`first_message`	string	Initial greeting when call starts
`is_active`	boolean	Whether agent can handle calls
`voicemail_detection`	boolean	Automatically detect voicemail
`voicemail_message`	string	Message to leave on voicemail
`max_duration_seconds`	number	Maximum call duration (null = unlimited)
`autonomous_silence_handling`	boolean	Auto-detect silence and prompt caller
`webhook_url`	URL	Endpoint for webhook events
`webhook_secret`	string	Secret for signature verification
`webhook_events`	array	Events to send to webhook
`analysis_plan`	object	Post-call analysis configuration

Creating an Agent

Only the name is required. All other fields have sensible defaults.

Minimal agent:

Full agent:

See Create a New Agent for complete API documentation.

Updating an Agent

Use PATCH to update specific fields. Only provided fields are updated.

See Update an Agent for details.

Deleting an Agent

When you delete an agent, any phone numbers assigned to it will have their agent_id set to null.

See Delete an Agent for details.

List All Agents

Get an Agent

Phone Numbers - Assign agents to phone numbers

Webhooks - Configure event notifications

Agent Components#

Speech-to-Text (STT)#

Language Model (LLM)#

Text-to-Speech (TTS)#

Agent Properties#

Creating an Agent#

Updating an Agent#

Deleting an Agent#

Related#