Trovacast

Get started

An AI agent that looks things up

Create an AI voice agent with a tool your server answers, place a call it carries, answer its tool request and read what it extracted from the call.

In this quickstart you build an AI agent that confirms deliveries: it calls the customer, looks the order up on your server mid-call (a tool), and after the call hands you structured data it pulled from the conversation (an extraction). The full reference is AI voice agents.

Before you start

  • A live key with agents:read, agents:write, calls:write, contacts:write, transcripts:read and settings:write. A test key creates test agents and test calls, which never reach a carrier and never run a tool — good for building the requests, not for hearing the agent.
  • Calling enabled and prepaid credit, as for any call (Place a call).
  • An HTTPS endpoint of yours on a public host for the tool, answering within 4 seconds.
  • A webhook endpoint subscribed to call.summary.ready (with calls:read and transcripts:read) — see Receive webhooks.

Pick models this deployment runs

Every model in GET /v1/models says whether it is available here. Choose an available voice model: an agent naming one that is not is refused when you save it (422 MODEL_UNAVAILABLE, naming the provider), never when the call rings.

List the models
curl 'https://api.trovacast.com/v1/models' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"

Turn AI calls on

AI calls are switched off for a new organization. Read the settings for their version, then switch them on with it.

Read the call settings
curl 'https://api.trovacast.com/v1/settings/calls' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
Switch AI calls on
curl -X PATCH 'https://api.trovacast.com/v1/settings/calls' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "aiCallsEnabled": true,
  "version": 1
}'

Create the agent, with a tool and an extraction

Create the agent
curl -X POST 'https://api.trovacast.com/v1/agents' \
  -H "Authorization: Bearer $TROVACAST_API_KEY" \
  -H 'Idempotency-Key: agent-delivery-confirmations' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Delivery confirmations",
  "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. Look the order up before you answer questions about it, confirm the delivery slot or offer another, then end the call politely.",
  "firstMessage": "Hello, this is Acme’s delivery assistant. Is now a good time to talk about your order?",
  "language": "en-IN",
  "tools": [
    {
      "name": "lookup_order",
      "description": "Finds an order by its number and answers its delivery slot and 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": {
        "confirmed": {
          "type": "boolean"
        },
        "newSlot": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      },
      "required": [
        "confirmed",
        "newSlot"
      ]
    }
  }
}'

The answer carries toolSigningSecret — once. Store it: it signs every tool request this agent sends. (POST /v1/agents/{agentId}/tool-secret replaces it if it leaks.)

Answer the tool

When the agent decides to look an order up, Trovacast POSTs { "event": "agent.tool_call", "tool": "lookup_order", "arguments": { "orderId": "1042" }, "callId", "agentId", "toolCallId", … } to the tool’s URL, signed with the tool-signing secret exactly like a webhook. Verify the signature on the raw body, then answer { "result": … } within 4 seconds — the agent speaks from it.

Node.js (Express) (javascript)
import express from "express";
import { verifyWebhookSignature } from "@trovacast/sdk";

const app = express();

app.post("/trovacast/tools/lookup-order", express.raw({ type: "application/json" }), async (req, res) => {
  const signed = verifyWebhookSignature({
    payload: req.body,
    header: req.headers["trovacast-signature"],
    secrets: [process.env.TROVACAST_TOOL_SECRET],
  });
  if (!signed) return res.sendStatus(400);
  const { arguments: args } = JSON.parse(req.body.toString("utf8"));
  const order = await orders.find(args.orderId); // your own lookup
  res.json({
    result: order
      ? { status: order.status, slot: order.deliverySlot }
      : { error: "No order with that number" },
  });
});
Python (Flask) (python)
import json, os
from flask import Flask, request, jsonify, abort
from trovacast import verify_webhook_signature

app = Flask(__name__)

@app.post("/trovacast/tools/lookup-order")
def lookup_order():
    if not verify_webhook_signature(
        request.get_data(),
        request.headers.get("Trovacast-Signature"),
        [os.environ["TROVACAST_TOOL_SECRET"]],
    ):
        abort(400)
    args = json.loads(request.get_data())["arguments"]
    order = orders.find(args["orderId"])  # your own lookup
    if order is None:
        return jsonify(result={"error": "No order with that number"})
    return jsonify(result={"status": order.status, "slot": order.delivery_slot})

A slow, failing or oversized answer tells the agent the tool failed: it apologises and offers a follow-up, and never invents a result. Each tool call is on the call’s timeline by name and outcome — never its arguments or result.

Place the call

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."
  },
  "recording": {
    "enabled": true,
    "consentEvidence": {
      "source": "VERBAL",
      "text": "This call is recorded for quality and training.",
      "capturedAt": "2026-11-06T09:30:00.000Z"
    }
  },
  "maxDurationSec": 600
}'

The call rings, the agent says its first message and the conversation runs on its own; the usual call events arrive as it does.

Read what it extracted

Once the call has ended and its transcript is final, the extraction runs with the summary. call.summary.ready brings it to your webhook; or read it yourself.

The call's summary
curl 'https://api.trovacast.com/v1/calls/2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f/summary' \
  -H "Authorization: Bearer $TROVACAST_API_KEY"
200 — extracted (json)
{
  "object": "call_summary",
  "callId": "2c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f",
  "status": "ready",
  "extraction": {
    "status": "ready",
    "data": {
      "confirmed": false,
      "newSlot": "2026-11-08T10:00:00.000Z"
    },
    "failureCode": null,
    "extractedAt": "2026-11-06T10:00:00.000Z"
  }
}

extraction.data fits your schema (anything that does not is discarded, never stored), with any phone number in it masked to its last four digits. status: pending means it has not run yet; failed names why in failureCode.

Next steps