Create a new voice AI agent.

Only name and instructions are required. All provider defaults are applied server-side — if you don't specify brain/voice/transcriber, the platform picks its current production defaults (Phantom brain, Cartesia sonic-3 voice with Fatima — Arabic, Soniox stt-rt-v4 transcriber with EN+AR language hints — pairs natively with Fatima for code-switching). Behavior defaults: turn_detection.mode=stt (Soniox owns endpointing), preemptive_generation=true, recording on with 30-day retention, post-call analysis on (PassFail rubric).

Brain (LLM) providers

phantom — default, Neuratel AI (~178ms TTFT)

• model: "phantom"

groq — Groq fast inference (~443ms TTFT)

• model: "meta-llama/llama-4-scout-17b-16e-instruct" (recommended)

• model: "llama-3.1-8b-instant" (fastest)

• model: "openai/gpt-oss-20b" (with reasoning)

openai — OpenAI GPT (~583-1213ms TTFT)

• model: "gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"

• model: "gpt-4.1", "gpt-4.1-mini", "gpt-4.1-nano"

xai — xAI Grok (~93-180ms TTFT)

• model: "grok-4-1-fast-non-reasoning" (recommended)

• model: "grok-4.20-0309-non-reasoning"

Voice (TTS) providers

cartesia — default, best quality (~37ms latency)

• voice_model: "sonic-3"

• voice_id: "731ace69-ee17-41bc-8c6f-665c9f1db95c" (default, Fatima — Arabic; pairs with default Soniox EN+AR hints)

• voice_speed: float or preset ("fastest","fast","normal","slow","slowest")

elevenlabs — most expressive (~71ms latency)

• voice_model: "eleven_flash_v2_5"

• voice_id: any ElevenLabs voice ID

• voice_speed: float (0.25–4.0), stability via config dict

phantom — Neuratel native voices (~100ms latency)

• voice_model: "phantom-english-speech-preview" or "phantom-arabic-speech-preview"

• voice_id not used; set voice name in config: {"voice": {"voice": "aria"}}

• English voices: aria, bella, claire, alex, david, marcus

• Arabic voices: omar, tariq, layla, nour

Transcriber (STT) providers

soniox — default, Soniox v4 with semantic end-of-utterance built in

• transcriber_model: "stt-rt-v4" (single unified model, 60+ languages)

• Default language_hints: ["en", "ar"], language_hints_strict: true

• When transcriber.provider="soniox", the worker auto-routes turn_detection.mode to "stt" (Soniox owns endpointing)

• Requires per-org soniox_api_key (BYOK)

deepgram — best accuracy for telephony-only English (~83ms latency)

• transcriber_model: "nova-3" (recommended), "nova-3-medical"

• language: BCP-47 e.g. "en-US", "ar", "multi" (auto-detect)

openai — GPT-4o powered (~138ms latency)

• transcriber_model: "gpt-4o-mini-transcribe"

• language: ISO code e.g. "en", "ar", "es"

phantom — Neuratel native STT

• transcriber_model: "phantom-stt-v1"

• language: "auto" (auto-detect)

Advanced config

Use the config dict for anything not covered by named params. It accepts the full agent config structure — same shape as get_agent returns.

config={
    "turn_detection": {
        "mode": "semantic_vad",   # or "vad"
        "min_delay": 0.5,
        "max_delay": 6.0,
        "endpointing_mode": "dynamic"  # or "fixed"
    },
    "timeout": {
        "enabled": True,
        "trigger_seconds": 15.0,
        "warning_messages": ["Are you still there?"],
        "final_message": "Goodbye!"
    },
    "background_audio": {
        "ambient": {"enabled": True, "source": "office_ambience", "volume": 0.3},
        "thinking": {"enabled": True, "source": "keyboard_typing", "volume": 0.5}
    },
    "tools": {
        "rag": {"enabled": True, "knowledge_base_ids": ["kb-id"], "top_k": 5},
        "voicemail": {"enabled": True, "action": "hangup"},
        "hangup": {"enabled": True, "keywords": ["goodbye", "bye"]}
    },
    "transfer": {
        "enabled": True,
        "mode": "blind",
        "destinations": [{"name": "Support", "number": "+15551234567",
                          "description": "Human agent", "keywords": ["human", "agent"]}]
    },
    "analytics": {
        "recording": {"enabled": True},
        "summary": {"enabled": True},
        "success_evaluation": {
            "enabled": True,
            "criteria": "Did the agent resolve the issue?",
        },
    },
    "interruption": {
        "enabled": True,
        "min_duration": 0.5,
        "min_words": 0,
        "false_interruption_timeout": 2.0,
        "resume_false_interruption": True
    }
}

Returns: agent id, name, status, brain provider/model, voice provider.

List all voice AI agents in your organization.

Use this to find agent IDs for making calls, starting campaigns, or assigning to phone numbers. Also useful to audit what agents exist and whether they're active.

Returns a summary for each agent — use get_agent for full configuration.

Get the complete configuration of a specific agent.

Returns every field and setting — brain, voice, transcriber, transfer rules, analytics, tools, interruption, timeout, background audio, and more. This is the full picture of how the agent behaves.

Use this before calling update_agent to understand current state, or to inspect how an agent is configured for debugging call quality issues.

The response structure matches what update_agent's config parameter accepts — you can read a section here, modify it, and pass it back.

Update any part of an agent's configuration.

Only the fields you provide are changed — everything else stays as-is. The backend deep-merges your changes, so you can update a single field inside a nested config without affecting sibling fields.

Two ways to update

Named parameters — for common changes:

update_agent(agent_id="...", temperature=0.5, voice_speed=1.1)

config parameter — for any section not covered by named params. Use get_agent first to see the current structure, then pass sections. Named params always override the corresponding section in config.

IMPORTANT: provider field required for voice/transcriber

The backend uses discriminated unions — voice and transcriber sections MUST include the provider field or validation fails. Always pair voice_id/voice_model/voice_speed with voice_provider. Same for transcriber.

Available config sections

config={
    "turn_detection": {
        "mode": "semantic_vad",   # or "vad"
        "min_delay": 0.5,
        "max_delay": 6.0,
        "endpointing_mode": "dynamic"
    },
    "timeout": {
        "enabled": True,
        "trigger_seconds": 15.0,
        "warning_messages": ["Are you still there?"],
        "final_message": "Goodbye!"
    },
    "background_audio": {
        "ambient": {"enabled": True, "source": "office_ambience", "volume": 0.3},
        "thinking": {"enabled": True, "source": "keyboard_typing", "volume": 0.5}
    },
    "tools": {
        "rag": {"enabled": True, "knowledge_base_ids": ["kb-id"], "top_k": 5},
        "voicemail": {"enabled": True, "action": "hangup"},
        "hangup": {"enabled": True, "keywords": ["goodbye", "bye"]}
    },
    "transfer": {
        "enabled": True,
        "mode": "blind",
        "destinations": [{"name": "Support", "number": "+15551234567",
                          "description": "Human agent", "keywords": ["human"]}]
    },
    "analytics": {
        "recording": {"enabled": True},
        "summary": {"enabled": True},
        "success_evaluation": {
            "enabled": True,
            "criteria": "Did the agent resolve the issue?",
        },
    },
    "tts_text_transforms": ["filter_markdown", "filter_emoji"],
    "preemptive_generation": False,
    "min_consecutive_speech_delay": 0.0
}

Permanently delete a voice AI agent.

This is irreversible. Any phone numbers assigned to this agent will stop answering calls immediately. Active calls in progress will not be affected, but no new calls can be made or received.

Before deleting, consider using update_agent with is_active=False to disable the agent without destroying its configuration.

List the platform's pre-built agent templates.

Returns the read-only catalog of template configurations the platform ships — useful as starting points before customising via create_agent. Each template includes a name, description, and full agent config block you can deep-merge with your own overrides.

List the {{variable}} placeholders an agent needs at call time.

Returns the names (and where possible, sources/categories) of every template variable the agent's prompt references — split into:

• system_variables: platform-injected (system__*) — never supply these

• dynamic_variables: caller-supplied at make_call / inbound webhook time

Use this before placing an outbound call to verify the dynamic_variables payload covers every required name. Saves a round-trip vs trial-and-error.

Create an exact copy of an agent with all its configuration.

Duplicates everything: brain settings, voice, transcriber, transfer rules, analytics config, tools, and conversation settings. The copy is independent — changes to one don't affect the other.

Great for:

• A/B testing different prompts or voices on the same setup

• Creating language variants (duplicate, then change language + instructions)

• Branching a proven agent before making experimental changes

• Setting up dev/staging/prod versions of the same agent

Place an outbound phone call using a voice AI agent.

This connects a real phone call between your AI agent and the destination number. The agent handles the entire conversation autonomously using its configured instructions and voice.

Prerequisites

1. An agent must exist (use create_agent or list_agents to find one)

2. A phone number must be provisioned (use list_numbers to find one)

3. Account must have sufficient balance (use get_balance to check)

Minimum required

Just three fields: which agent talks, who to call, and which number to call from. Everything else is optional.

Per-call customization

Two powerful ways to customize each call without changing the agent:

dynamic_variables — inject values into the agent's prompt template. If the agent's instructions contain {{customer_name}}, pass: dynamic_variables={"customer_name": "Alice"}

agent_override — deep-merge config changes over the saved agent for this call only. The agent itself is not modified. Use this to:

• Change the prompt for a specific call

• Use a different voice or language

• Adjust temperature for a sensitive conversation

• Override any config section (brain, voice, transcriber, etc.)

Example override:

{"brain": {"instructions": "Special prompt for this call only"}}

Args: agent_id: The agent that will handle this call to_number: Destination in E.164 format (+12125551234) number_id: Your phone number ID to call from (from list_numbers) dynamic_variables: Template variables for the agent's prompt caller_id_name: Display name shown to the recipient (max 50 chars) caller_id_number: Override caller ID number (E.164). Defaults to the number_id's phone number if not set. agent_override: Per-call config overrides. Same structure as the agent config from get_agent. Deep-merged over the saved agent — only affects this call.

Returns: call_id for tracking via get_call, success status, and numbers.

List recent voice sessions with a summary of each.

Returns call history sorted by most recent first. Each entry includes status, duration, and outcome — but NOT the transcript. Use get_call with a specific call_id to read the full transcript.

Filter by channel (transport: phone, web, whatsapp_voice) and/or direction (inbound vs outbound, NULL for web). Filter by agent_id to see calls handled by a specific agent.

Args: limit: How many calls to return (1-100, default 10) channel: Transport filter: "phone" | "web" | "whatsapp_voice" direction: "inbound" or "outbound" (NULL for web sessions) agent_id: Filter to calls handled by this agent

Get full details for a specific voice session including transcript.

This is the primary tool for post-call analysis. Returns everything: the full conversation transcript (who said what, in order), call summary, recording URL, success evaluation, topics discussed, and any data extracted during the call.

The transcript is a list of turns: [{"role": "agent", "text": "..."}, {"role": "user", "text": "..."}, ...] — making it easy to review exactly what happened on the call.

Use this when asked: "What happened on that call?", "What did the caller say?", "Was the agent successful?", "Show me the transcript."

Immediately terminate an active voice session.

Disconnects all participants instantly — the caller hears the line drop. There is no graceful goodbye; the call just ends.

Use get_active_calls first to find the call_id of a live call. Only works on calls that are currently in progress.

Use this sparingly — for emergencies, stuck calls, or when explicitly asked to end a call. In most cases, the agent's own timeout and hangup logic will end calls naturally.

Get all voice sessions happening right now across your organization.

Returns real-time data: which agents are on calls, how long each call has been running, caller numbers, and connection status.

Use this for live monitoring, to find a call_id for hangup_call, or to check system load before starting a campaign.

Returns empty list when no calls are active — that's normal.

Create an outbound calling campaign to dial a list of contacts.

A campaign automates outbound calling at scale — it takes an agent, a phone number, and a contact list, then systematically dials each contact using the AI agent to handle the conversation.

How campaigns work

1. Create the campaign (this tool) — defines who calls, from what number

2. Start the campaign (start_campaign) — begins dialing contacts

3. The system calls contacts in parallel (up to max_concurrent_calls)

4. Each call is handled by the agent autonomously

5. Monitor progress with get_campaign

6. Pause/stop at any time with pause_campaign or stop_campaign

Prerequisites

• An agent configured for outbound calls (use create_agent)

• A phone number to call from (use list_numbers)

• A call list with contacts (upload via the dashboard, or pass call_list_id)

• Sufficient account balance for the expected call volume

Concurrency

max_concurrent_calls controls how many calls run simultaneously. Start low (3-5) to validate agent performance before scaling up. Higher concurrency = faster completion but more simultaneous cost.

Args: name: Campaign display name (e.g. "Q2 Renewal Outreach") agent_id: The agent that handles every call in this campaign phone_number_id: Phone number UUID for caller ID (from list_numbers) call_list_id: Contact list ID (contains numbers + variables to dial) max_concurrent_calls: Simultaneous call limit (default 5) scheduled_start: ISO 8601 datetime to auto-start (e.g. "2026-04-15T09:00:00Z"). Omit to start manually with start_campaign.

List all outbound campaigns with current status and progress.

Shows each campaign's state (draft, running, paused, completed, stopped) and progress (total contacts vs completed calls).

Use this to find campaign IDs for start/pause/stop operations, or to monitor overall campaign health at a glance.

Get full details and real-time progress for a campaign.

Returns the complete campaign configuration, execution stats (calls completed, failed, remaining), and performance data.

Use this to monitor a running campaign, debug why calls are failing, or review results after completion.

Start a campaign — begins dialing contacts immediately.

The campaign must be in "draft" or "paused" status. Once started, the system begins placing calls up to the configured concurrency limit. Calls continue until all contacts are reached or the campaign is paused/stopped.

Check get_balance before starting — insufficient credits will cause calls to fail mid-campaign.

Pause a running campaign — no new calls, active calls finish.

Calls already in progress will complete naturally. No new calls are placed. The campaign retains its progress and can be resumed with start_campaign.

Use this to throttle costs, investigate quality issues, or pause during off-hours before resuming later.

Stop a campaign permanently — remaining contacts will not be called.

Unlike pause, stopping is final. The campaign cannot be restarted. Any contacts not yet called are abandoned. Calls in progress will finish, but the campaign is marked as stopped.

Use pause_campaign instead if you might want to resume later.

List all phone numbers provisioned in your organization.

Phone numbers are the entry point for inbound calls and the caller ID for outbound calls. Each number can be assigned to one agent at a time.

Use this to:

• Find a number_id for make_call or create_campaign

• See which agent each number routes to

• Check number capabilities (voice, SMS, etc.)

• Find unassigned numbers available for new agents

A number with agent_id=null is not answering inbound calls. Assign an agent with assign_number to start routing calls to it.

Route a phone number's inbound calls to an AI agent.

After assignment, every inbound call to this number is automatically answered by the specified agent. The agent uses its configured first_message, instructions, voice, and all other settings.

If the number was previously assigned to a different agent, the assignment is replaced — calls immediately start routing to the new agent.

This only affects inbound calls. For outbound calls, you specify the agent and number separately in make_call.

Args: phone_number_id: The number to configure (from list_numbers) agent_id: The agent that will answer calls (from list_agents)

Remove the agent from a phone number — inbound calls stop being answered.

After unassigning, calls to this number will not be picked up by any agent. The number still exists and can be reassigned later.

Use this when retiring a number, switching agents (unassign then assign_number to the new agent), or temporarily taking a number offline for maintenance.

List all knowledge bases in your organization.

Knowledge bases are documents, FAQs, and web content that agents can search during calls using RAG (retrieval-augmented generation). When a caller asks a question, the agent searches attached knowledge bases for relevant information before responding.

Use this to see what knowledge exists before creating duplicates, or to find knowledge_base_ids for attach_knowledge_to_agent.

Create a knowledge base from plain text content.

The text is immediately chunked and indexed for RAG retrieval. After creating, use attach_knowledge_to_agent to connect it to an agent — the agent will then search this content during calls.

Best for: FAQs, product specs, policies, scripts, pricing tables, troubleshooting guides, or any structured text content.

Tips for good knowledge base content:

• Use clear headings and Q&A format for best retrieval

• Keep each topic self-contained (the system retrieves chunks)

• Include the exact phrases callers would use, not just jargon

• Max 500KB of text per knowledge base

Args: name: Display name (e.g. "Returns Policy FAQ", "Product Catalog") text: The actual content to index. Plain text or markdown. description: What this knowledge covers (helps with organization)

Create a knowledge base by scraping and indexing a web page.

Fetches the URL, extracts the content (handles JavaScript-rendered pages), converts to clean text, chunks it, and indexes for RAG. Processing happens asynchronously — check the status field.

Best for: product documentation, help center articles, pricing pages, company info, or any publicly accessible web content.

The URL must be publicly accessible. Status will be "processing" initially, then "ready" when indexing completes (usually <30 seconds), or "error" if the page couldn't be fetched.

Args: name: Display name (e.g. "Product Documentation", "Pricing Page") url: Public URL to scrape (https://docs.example.com/faq) description: What this knowledge covers

Connect knowledge bases to an agent for RAG-powered conversations.

Once attached, the agent automatically searches these knowledge bases when callers ask questions. The agent retrieves relevant chunks and uses them to give accurate, grounded answers instead of hallucinating.

This REPLACES all current attachments — pass the complete list of knowledge base IDs you want attached, not just new additions. To add a new KB without removing existing ones, include all current IDs plus the new one.

Multiple knowledge bases can be attached to the same agent. The system searches across all of them and returns the most relevant chunks regardless of which KB they came from.

Args: agent_id: The agent to connect knowledge to knowledge_base_ids: Complete list of KB IDs to attach

Check the current account balance and credit status.

Returns the available balance in the account's billing currency (set in organization settings — defaults to USD).

Always check this before:

• Making outbound calls (make_call)

• Starting campaigns (start_campaign)

• Any operation that incurs telephony or AI costs

A zero or negative balance means calls will fail. The has_credits field is a quick boolean check for sufficient funds.

Get usage summary for a time period.

Returns aggregate stats: how many calls were made, total seconds and minutes consumed, and total amount billed. Billing is per-second, so total_seconds is the granular metric. Useful for cost monitoring, capacity planning, and usage reporting.

Args: days: Look-back period in days (default 30, max 365). Use 1 for today's usage, 7 for the past week.

Create a webhook to receive real-time notifications for call events.

Webhooks send HTTP POST requests to your URL when events occur. Use them to trigger workflows, update CRMs, log call outcomes, or build real-time dashboards.

Available event types (dotted notation)

Call lifecycle:

• "call.started" — call connected, conversation beginning

• "call.ended" — call disconnected, final data available

• "call.ringing" — outbound call is ringing

• "call.answered" — outbound call was picked up

• "call.failed" — call could not connect

• "call.transferred" — call was transferred to another number

• "call.summary.ready" — post-call summary and analytics available

Transcript events:

• "transcript.partial" — real-time partial transcript update

• "transcript.final" — final transcript segment

• "transcript.ready" — complete transcript available

Recording:

• "recording.ready" — call recording is available for download

Agent events:

• "agent.turn.started" — agent began generating a response

• "agent.turn.ended" — agent finished speaking

• "agent.tool.called" — agent invoked a tool (RAG, transfer, hangup, etc.)

Pass an empty list or omit events to subscribe to ALL event types.

The signing secret is returned ONCE in the response. Save it immediately — use it to verify webhook requests via HMAC-SHA256 to ensure they're genuinely from Neuratel.

Args: name: Display name for this webhook (e.g. "CRM Integration") url: Your HTTPS endpoint to receive events. Must use HTTPS. events: Event types to subscribe to (dotted format). Empty = all.

List all configured webhook subscriptions.

Shows each webhook's URL, subscribed events, active status, and delivery health (failure count, last successful delivery).

Use this to audit integrations, check for delivery failures, or verify that the right events are being captured.

A high failure_count indicates the endpoint is down or rejecting requests — investigate the URL or check your server logs.

List conversation threads across SMS, WhatsApp, and voice.

A conversation groups all messages and voice sessions exchanged with one contact through one channel. Use this for inbox-style review.

Args: channel: "sms" | "whatsapp" | "voice" (omit for all channels) status: Conversation lifecycle filter limit: Max threads (default 20, max 100)

Get a single conversation thread including its current state.

Returns the conversation envelope (channel, contact, agent assignment, dynamic_variables, last activity) but NOT the message history. Use list_conversation_messages for the messages.

List messages exchanged in a conversation, newest first.

Args: conversation_id: From list_conversations limit: Max messages (default 50) since: ISO 8601 — return messages after this timestamp before: ISO 8601 — return messages before this timestamp

Send an outbound message into an existing conversation.

For SMS / WhatsApp freeform replies. Templated WhatsApp sends should use the agent's WhatsApp template config instead of this tool.

Args: conversation_id: Target thread body: Message text (required by backend ConversationSendRequest) media_urls: Optional list of media URLs for MMS / WhatsApp media client_temp_id: Optional client-supplied dedup key

Mark all messages in a conversation as read.

Get a unified timeline of messages + voice sessions for a conversation.

Useful when a contact has both chat exchanges and call attempts on the same thread — the timeline interleaves them chronologically.

Set or update dynamic_variables on a conversation thread.

These variables are inherited by any subsequent voice/chat turn that renders the agent's prompt template. Useful when context arrives out-of-band (CRM sync, webhook from your system, etc.).

Args: conversation_id: Target thread dynamic_variables: dict of {name: value} replace: If True, replaces the existing dict entirely. If False (default), merges into the existing dict.

Get chat-channel KPIs (SMS + WhatsApp).

Returns inbound / outbound message counts, response latency, agent utilisation, and per-conversation outcomes for the requested window. For combined voice + chat KPIs use get_combined_analytics instead.

Check a phone number against the platform DNC directory.

Hits the global directory (federal/state lists where applicable plus platform-curated entries) and any per-org entries. Returns whether the number is blocked, the source list, and timestamps.

Always check before placing an outbound call to a new contact — dialing a DNC-listed number can carry per-call regulatory penalties.

Args: phone: E.164 formatted number (e.g. "+12125551234")

List DNC entries visible to your organization.

Returns both your own org_upload entries and any platform-managed entries that block dialing org-wide. Filter by source to see only org-uploaded vs platform-curated.

Args: source: Optional filter — "org_upload" | "inbound_optout" | "platform" limit: Max entries to return (default 100)

Add a number to your organization's DNC list.

Once added, all subsequent outbound calls (manual or campaign) to this number from your org will be blocked at dial time.

Args: phone: E.164 formatted number reason: Optional human-readable reason (e.g. "customer requested", "STOP received via SMS")

Soft-expire an org_upload DNC entry.

Only org_upload entries can be removed. Platform-managed entries are immutable to org admins. The entry is soft-expired (audit-preserved), not hard-deleted.

Args: entry_id: ID returned by dnc_list_entries or dnc_add_entry

Get the organisation's DNC protection settings.

Returns whether DNC checks block outbound calls (protection_enabled) and whether STOP-style replies on inbound chat auto-add the sender (auto_add_inbound_optouts).

Toggle DNC protection and inbound STOP auto-detection.

Args: protection_enabled: Master switch — if False, DNC checks are logged but not enforced at dial time. auto_add_inbound_optouts: If True, the platform watches inbound SMS/WhatsApp for STOP-style language and adds the sender to your org DNC list.

List the platform's built-in system__* template variables.

These are auto-injected at call time by the platform — you never pass them in dynamic_variables. Use this catalog to:

• Validate which {{system__*}} placeholders are safe to embed in agent prompts

• Distinguish auto-injected variables from user-supplied ones when building dynamic_variables payloads for make_call

Each entry has name, description, and available_on (the channels where the variable resolves to a real value vs falling back to "").

Get combined voice + chat KPI dashboard.

Returns total volume, success rate, average sentiment score, total cost, and per-bucket time series across both voice sessions and chat conversations. For per-channel breakdowns use get_chat_analytics or list_calls instead.

Args: start_date: ISO date for the lookback window start end_date: ISO date for window end (defaults to now) agent_id: Filter to one agent channel: "phone" | "web" | "whatsapp_voice" | "sms" | "whatsapp" direction: "inbound" | "outbound" interval: Bucket granularity — "hour" | "day" | "week" | "month"