AI Voice Agent DID Routing

A DID controls inbound routing. To send callers directly to an AI Voice Agent, update the DID route to ai_agent and provide an active ai_agent_id. The authenticated customer must own both the DID and the agent.

Endpoint

Endpoint	Method	Auth
/v1/dids/:id/routing	PATCH	Required

Request

curl -sS https://api.minivoice.eu/v1/dids/did_123/routing \
  -X PATCH \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "route_mode": "ai_agent",
    "ai_agent_id": "agent_20260707T120000.000000000"
  }'

Response

{
  "data": {
    "id": "did_123",
    "number": "+15551230002",
    "number_e164": "+15551230002",
    "status": "active",
    "route_mode": "ai_agent",
    "ai_agent_id": "agent_20260707T120000.000000000",
    "application_id": null,
    "sip_trunk_id": null,
    "created_at": "2026-07-07T12:00:00Z",
    "updated_at": "2026-07-07T12:05:00Z"
  }
}

Route Modes

route_mode	Required field	Result
webhook	application_id	Inbound call is sent to the application's answer_url.
application	application_id	Accepted alias; stored as webhook.
sip	sip_trunk_id	Inbound call is routed to an active SIP trunk.
sip_trunk	sip_trunk_id	Accepted alias; stored as sip.
ai_agent	ai_agent_id	Inbound call starts an AI agent session.
reject	none	Inbound call is rejected.

Inbound Call Flow

1. Caller dials the DID.
2. MiniVoice resolves the DID for the customer.
3. If route_mode is ai_agent, MiniVoice checks that ai_agent_id is present and active.
4. MiniVoice creates an AI session for the call.
5. The AI runtime answers, plays or generates the greeting, and runs the conversation until completion, transfer, hangup, or failure.
6. You can read the session afterward with GET /v1/ai/sessions/:id.

Common Failure

{
  "error": {
    "code": "invalid_routing",
    "message": "selected AI agent was not found or is inactive"
  }
}

This usually means the agent ID is wrong, belongs to another customer, has been paused, or has been deleted.

Testing

Create a small test agent with a greeting such as "Thanks for calling the test receptionist. Please say sales or support." Route a test DID to the agent, place an inbound call, and confirm that an AI session appears in GET /v1/ai/sessions?agent_id=.... Pause the agent and retry the routing update; the API should reject the inactive agent.