Trovacast

Voice

AI voice agents

Create AI voice agents with their models, voice and instructions, and place calls they carry from the first word to the hang-up — no stream of your own to run.

An AI agent is a voice model, an optional reasoning model, a transcriber and instructions. Define one with agents:write, then place a call with mode: AI_AGENT and it runs the conversation. The same agents run in the console’s campaigns. Provider credentials are the platform’s: no secret is ever set or returned through the API.

Choose models

GET /v1/models lists the models an agent can use, by provider, each with its roles: realtime (a speech-to-speech voice leg), reasoning (conversation turns), tts (speech synthesis) and stt (transcription) — and available: whether this deployment can run it. An agent naming a model its provider does not serve for that role is refused when it is saved (400 VALIDATION_FAILED), and one on a provider that is not available here is 422 MODEL_UNAVAILABLE (naming provider, leg, model and reason) — never mid-call. So is an agent whose voice could not take a call for another reason: an ElevenLabs voice on a deployment with no ElevenLabs agent id (reason: agent_id_missing), a composite voice without its transcription or reasoning key. Every agent reads availability: { runnable, reason } — whether a call with it would be admitted here now — and a call with one that cannot speak is refused 422 AI_PROVIDER_UNAVAILABLE before anything is written: no call, no call.* event. A test key also sees the mock provider’s mock-voice and mock-reasoning (testOnly: true): build a test agent on them and place its test calls before your organization has any AI provider key. A live agent needs a real provider — a live key never sees the mock and is refused it.

List the models
curl 'https://api.trovacast.com/v1/models' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 (json)
{
  "data": [
    {
      "object": "model",
      "provider": "openai",
      "id": "gpt-realtime",
      "label": "GPT Realtime",
      "roles": [
        "realtime"
      ],
      "available": true
    },
    {
      "object": "model",
      "provider": "anthropic",
      "id": "claude-sonnet-5",
      "label": "Claude Sonnet 5",
      "roles": [
        "reasoning"
      ],
      "available": true
    }
  ]
}

Create an agent

Enum values are lower case (openai, autonomous_voice, auto) — what answers and GET /v1/models give — and requests take them in either case (OPENAI still works). instructions (10–20,000 characters) are stored encrypted and returned only by GET /v1/agents/{agentId}.

Create an agent
curl -X POST 'https://api.trovacast.com/v1/agents' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Delivery confirmations",
  "kind": "autonomous_voice",
  "voice": {
    "provider": "openai",
    "model": "gpt-realtime"
  },
  "instructions": "You are Acme’s delivery assistant. Say you are an AI assistant and that the call may be recorded. Confirm the delivery slot, offer to reschedule, then end the call politely."
}'
201 (json)
{
  "object": "agent",
  "id": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
  "name": "Delivery confirmations",
  "description": null,
  "kind": "autonomous_voice",
  "voice": {
    "provider": "openai",
    "model": "gpt-realtime",
    "voiceId": null
  },
  "reasoning": null,
  "transcription": {
    "provider": "auto",
    "model": null
  },
  "isDefault": false,
  "active": true,
  "teamId": null,
  "archivedAt": null,
  "version": 1,
  "createdAt": "2026-11-05T10:00:00.000Z",
  "updatedAt": "2026-11-05T10:00:00.000Z"
}
  • kind — autonomous_voice runs a call on its own (the kind mode: AI_AGENT calls use); hybrid_voice hands to a person; agent_assist coaches a person on the desk.
  • voice — the provider and model of the voice leg, and the provider’s voiceId (its default when unset). reasoning — a separate model for the conversation, where the voice provider supports one. transcription — auto unless you choose a transcriber (elevenlabs, cartesia).
  • PATCH /v1/agents/{agentId} changes any of it, active: false switches the agent off without archiving it, and the version you read refuses a lost update (409 AI_AGENT_VERSION_CONFLICT); a taken name is 409 AI_AGENT_NAME_TAKEN. DELETE archives it.
  • A test key creates agents of its own (livemode: false), which take test calls only and can never be the default, and changes only those; a live agent is read-only to it (422 TEST_MODE_UNSUPPORTED). A live call naming a test agent is 404 AI_AGENT_NOT_FOUND. A test call with an agent is placed even while the organization’s AI-call switch is off — it never reaches a carrier — so you can build before AI calls are turned on.

What the agent does on a call

Beyond its instructions, an agent can open the call with a fixed line or wait for the caller, speak a language, end the call by itself, call your tools mid-call and pull structured data out of each finished call. Each field is optional on create and change; null clears it.

An agent that looks orders up
curl -X PATCH 'https://api.trovacast.com/v1/agents/7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "firstMessage": "Hello, this is Asha from Acme. Is now a good time to talk about your delivery?",
  "language": "en-IN",
  "endCallPhrases": [
    "Have a great day"
  ],
  "maxTurns": 20,
  "tools": [
    {
      "name": "lookup_order",
      "description": "Finds an order by its number and answers its delivery status.",
      "parameters": {
        "type": "object",
        "properties": {
          "orderId": {
            "type": "string",
            "description": "The order number"
          }
        },
        "required": [
          "orderId"
        ]
      },
      "url": "https://api.example.com/trovacast/tools/lookup-order"
    }
  ],
  "extraction": {
    "schema": {
      "type": "object",
      "properties": {
        "rescheduled": {
          "type": "boolean"
        },
        "newSlot": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "rescheduled",
        "newSlot"
      ]
    }
  }
}'
  • firstMessage is said word for word when the call connects; firstSpeaker: caller makes the agent wait for the caller instead. Unset, each voice keeps its own default (the answer shows which).
  • language (BCP 47, hi-IN) is what transcription listens for, what a Sarvam voice speaks and what the agent is told to reply in — it still follows a caller who switches.
  • endCallPhrases and maxTurns end the call once the agent’s line has played: after it says one of the phrases, or after its n-th line.
  • tools are answered by your HTTPS endpoint: a signed agent.tool_call POST (verify it like a webhook, with the agent’s tool-signing secret — answered once as toolSigningSecret when the agent first gets a tool, rotated with POST /v1/agents/{agentId}/tool-secret). Answer { "result": … } within 4 seconds (16 KB at most); the agent speaks from it. Every tool call is on the call’s timeline by name and outcome, never its arguments.
  • extraction.schema is applied to each finished call’s transcript; the result is extraction on GET /v1/calls/{callId}/summary and in call.summary.ready (AI over the API).
  • Tool parameters and the extraction schema use a JSON Schema subset both reasoning providers can be held to: type, description, enum, format, properties, required, items and additionalProperties: false — at most 5 levels and 8 KB. Anything else is refused when the agent is saved, with the keyword named.

Place a call with an agent

An AI agent call
curl -X POST 'https://api.trovacast.com/v1/calls' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: ai-call-order-1042' \
  -H 'Content-Type: application/json' \
  -d '{
  "mode": "AI_AGENT",
  "to": {
    "phone": "+919876543210"
  },
  "aiAgent": {
    "agentId": "7d8e9f0a-1b2c-4d3e-8f4a-5b6c7d8e9f0a",
    "objective": "Confirm the delivery slot for order 1042."
  },
  "purpose": "SERVICE",
  "recording": {
    "enabled": true,
    "consentEvidence": {
      "source": "VERBAL",
      "text": "This call is recorded for quality and training.",
      "capturedAt": "2026-11-05T09:30:00.000Z"
    }
  },
  "maxDurationSec": 600
}'

aiAgent.objective is added to the agent’s instructions for this call only (it is stored with the call: keep personal data out of it). The call reads mode: "ai" with aiAgentId set, and follows the same events, billing and checks as any call. An agent that is switched off or archived is 409 AI_AGENT_INACTIVE; one that is not yours, 404 AI_AGENT_NOT_FOUND.

An agent answers the calls you place with it, and the inbound calls of a number routed to it (AI over the API) — where you can also read each call’s transcript and summary. A call flow hands a caller to an agent for one step (the ai verb, or connect to { ai: agentId } — see An AI agent as a step); to hand a call that is already live to an agent, transfer it to such a flow (Call control).

Errors

CodeStatusMeaning and what to do
AI_AGENT_INACTIVE409aiAgent.agentId — or (2026-11-07) a new ai route on PATCH /v1/numbers/{numberId} — names an AI agent that is switched off (active: false) or archived. Nothing was dialled, and the route was not changed. See AI voice agents.What to do: Switch a switched-off agent on with PATCH /v1/agents/{agentId} (active: true); for an archived one, name another agent.
AI_AGENT_NOT_FOUND404aiAgent.agentId — or (2026-11-07) a new ai route on PATCH /v1/numbers/{numberId} — names no AI agent of this organization of the request's mode (GET /v1/agents lists them; a test agent on a live call or number reads exactly as an unknown one). Nothing was dialled, and the route was not changed.What to do: Pass an agentId from GET /v1/agents, using a key of the same mode as the agent (a number takes live calls: route it to a live agent).
AI_CALLS_DISABLED409The organization's call policy turns machine-run calls off.What to do: Turn AI calls on with PATCH /v1/settings/calls (aiCallsEnabled: true and the version from GET /v1/settings/calls; a live key with settings:write), or in the console under Settings → Calling policy, then retry. See Turn AI calls on or off.
AI_PROVIDER_UNAVAILABLE422mode: AI_AGENT named an AI agent whose voice cannot run on this deployment — or (2026-11-07) a transfer action named a call flow that hands callers to such an agent (agentId names it; nothing was changed on the call): reason is voice_key_missing (its provider has no key here), agent_id_missing (an ElevenLabs voice with no ElevenLabs agent id), transcription_key_missing or reasoning_key_missing (a composite voice without its speech-to-text or reasoning key); provider and leg name the leg. Nothing was written or dialled — no call, no call.* event. The same code is a call’s failure.code when its voice could not start once the call existed. See AI voice agents.What to do: Do not retry the same request: it is refused the same until the agent or the deployment changes. Check GET /v1/agents/{agentId} (availability), then choose an agent that reads runnable: true, or switch this one to a voice GET /v1/models marks available. On a test key, build the agent on the mock voice.
MODEL_UNAVAILABLE422An AI agent names a model whose provider this deployment cannot run (no credentials are set up for it); provider, leg and model say which. GET /v1/models marks each model available.What to do: Pick a model GET /v1/models marks available for that leg, and set it on the agent (PATCH /v1/agents/{agentId}) or in the request. See Choose models.
TEST_MODE_UNSUPPORTED422A test-mode key (tc_test_…) cannot perform this: either it has no sandbox — managing templates, the WhatsApp account or email domains, writing broadcasts, renting numbers — or it would read or change live data: a recording, a contact export, consent, changing or erasing an existing contact, or changing live call flows, applications and AI agents. (A live customer’s conversation, or a live message to quote or react to, is not refused but not found: 404.) See Authentication.What to do: Repeat the request with a live key (tc_live_…); no test key can do it. In test mode, work on the test records your test key created instead.