AI Voice Agent Overview

MiniVoice AI Voice Agent lets a customer route a live phone call to an AI agent or start an outbound AI call through the API. The customer-facing API is prompt-first: you create an agent with a name, greeting, instructions, model, voice, and runtime limits. You do not send customer_id; MiniVoice derives the customer from the API key.

Use this feature when you want MiniVoice to answer or place a real call, speak with the caller, record the AI session, and expose session details afterward. A common first integration is a receptionist: the caller reaches a DID, the DID routes to an active AI agent, the agent answers with a greeting, collects the caller's reason, and either completes the conversation or transfers to an approved destination.

Integration Flow

1. Create an AI agent with POST /v1/ai/agents.
2. Activate the agent, or create it with is_active omitted because new agents default to active.
3. Route a DID to the agent with PATCH /v1/dids/:id/routing.
4. Place a test call to the DID, or create an outbound AI call with POST /v1/ai/calls.
5. Inspect the session with GET /v1/ai/sessions/:id.
6. Inspect usage with GET /v1/ai/usage/summary.

Object Relationship

Object	Purpose	Example ID
Customer	Owns applications, DIDs, trunks, AI agents, balance, and limits.	cust_123
API key	Authenticates API requests and scopes them to the customer.	not returned in responses
AI agent	Stores prompt, greeting, model, voice, limits, fallback, and tool configuration.	agent_20260707T120000.000000000
DID	Controls inbound routing. A DID can route to an application, SIP trunk, AI agent, or reject mode.	did_123
Trunk	Provides outbound calling capacity for outbound AI calls.	trunk_123
AI session	Represents one live AI conversation associated with a call.	agent_session_123

First Agent

curl -sS https://api.minivoice.eu/v1/ai/agents \
  -X POST \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Receptionist",
    "greeting": "Thanks for calling Northstar Dental. How can I help you today?",
    "instructions": "You are a concise receptionist. Help callers with appointments, working hours, and routing. If the caller asks for billing or urgent care, transfer to the approved front desk destination.",
    "model": "gpt-4.1-mini",
    "voice": "alloy",
    "language": "en",
    "runtime_limits": {
      "max_turns": 8,
      "max_call_seconds": 300,
      "silence_timeout_ms": 3000,
      "turn_recording_max_seconds": 10
    }
  }'

Response

{
  "data": {
    "id": "agent_20260707T120000.000000000",
    "name": "Receptionist",
    "status": "active",
    "is_active": true,
    "model": "gpt-4.1-mini",
    "voice": "alloy",
    "language": "en",
    "greeting": "Thanks for calling Northstar Dental. How can I help you today?",
    "instructions": "You are a concise receptionist. Help callers with appointments, working hours, and routing. If the caller asks for billing or urgent care, transfer to the approved front desk destination.",
    "business_profile": "",
    "behavior_config": {
      "campaign_mode": false,
      "max_turn_latency_ms": 8000,
      "runtime_limits": {
        "max_turns": 8,
        "max_call_seconds": 300,
        "silence_timeout_ms": 3000,
        "turn_recording_max_seconds": 10
      },
      "fallback_message": ""
    },
    "tool_config": {
      "type": "",
      "target": "",
      "message": "",
      "hangup_tool_description": "",
      "transfer_tool_description": "",
      "transfer_destinations": []
    },
    "created_at": "2026-07-07T12:00:00Z",
    "updated_at": "2026-07-07T12:00:00Z"
  }
}

Supported Runtime Shape

The public API exposes two runtime concepts in responses:

Field	Values	Meaning
runtime_type	auto, realtime, turn_based	The configured AI runtime mode used for outbound AI call creation responses.
media_mode	turn_based, realtime_gateway, sip_gateway	The configured media path used by the voice runtime.

Most integrations should not branch on runtime internals. Store these fields for debugging and support, but build the product around calls and sessions.

Common Failure

{
  "error": {
    "code": "invalid_ai_agent",
    "message": "instructions must be at most 8000 characters"
  }
}

Keep prompts specific and short enough to fit the validation limit. Put dynamic caller data in outbound call context, not in a new agent per call.