Outbound AI Voice Calls

Use POST /v1/ai/calls to start an outbound call handled by an AI Voice Agent. This is separate from regular outbound calls. The request names the agent, destination number, caller ID, and optional context for that specific conversation.

Endpoint

Endpoint	Method	Auth
/v1/ai/calls	POST	Required

Request

curl -sS https://api.minivoice.eu/v1/ai/calls \
  -X POST \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_id": "agent_20260707T120000.000000000",
    "from": "+15551230002",
    "to": "+15551230001",
    "context": {
      "customer_name": "Jordan Lee",
      "appointment_time": "2026-07-08T15:30:00Z",
      "reason": "appointment confirmation"
    }
  }'

Response

{
  "data": {
    "call_id": "call_20260707T120500.000000000",
    "ai_session_id": "agent_session_20260707T120500.000000000",
    "agent_id": "agent_20260707T120000.000000000",
    "status": "dialing",
    "runtime_type": "auto",
    "media_mode": "turn_based",
    "created_at": "2026-07-07T12:05:00Z"
  }
}

Parameters

Field	Type	Required	Description
agent_id	string	yes	Active AI agent owned by the authenticated customer.
to	string	yes	Destination phone number in E.164 format.
from	string	yes	Customer-owned active DID in E.164 format.
context	object	no	Freeform JSON object for the conversation. Raw context must fit within 4096 bytes before MiniVoice stores it under ai_context.

Validation

MiniVoice validates that the agent exists, belongs to the authenticated customer, is active, and is not deleted. from must be an active DID owned by the customer. The customer must have positive balance, must not exceed concurrent-call or calls-per-second limits, and must have an active outbound trunk. If originate fails before answer, the API returns a 502 with originate_failed and includes the call_id.

Context Use Case

For appointment confirmations, keep the agent reusable and pass appointment-specific data in context.

{
  "context": {
    "customer_name": "Jordan Lee",
    "appointment_time": "2026-07-08T15:30:00Z",
    "location": "Downtown Clinic",
    "confirmation_goal": "Ask whether the customer can still attend."
  }
}

The runtime uses this context as part of the session prompt. Unknown customer fields are accepted as long as the context is a JSON object and remains within the size limit.

Common Errors

{
  "error": {
    "code": "invalid_from",
    "message": "from must belong to this customer"
  }
}

{
  "error": {
    "code": "insufficient_balance",
    "message": "balance is too low to create AI call"
  }
}

{
  "error": {
    "code": "no_active_trunk",
    "message": "no active outbound trunk configured"
  }
}

Testing

Start with a test DID that belongs to your customer and an active outbound trunk. Create an agent that says it is a test call, then call your own mobile number. Verify the immediate response has status set to dialing, then fetch the returned ai_session_id from GET /v1/ai/sessions/:id after the call ends.