Programmatic AI Calling API for Developers & Platforms

The Integration Model in Four Steps

The API surface is deliberately small. Most integrations use four endpoints and one webhook handler, and are working end to end inside a day.

• Create the agent — Define the prompt, the voice, the allowed tools and the structured fields you want extracted. This is configuration, done once, not per call.
• Trigger the call — Post the destination number, the agent ID and a JSON context object. You get back a call ID immediately; the call is queued and placed asynchronously.
• Receive the result webhook — When the call ends your endpoint gets one event: call.completed with the results, or call.failed if the call did not connect (busy, no answer, failed).
• Handle the completion payload — On completion you receive the transcript, recording URL, disposition and the structured fields the agent extracted, ready to write into your database.

Design your webhook handler to be idempotent and to return quickly. Acknowledge first, process asynchronously, and run a reconciliation job that fetches any call whose webhook you missed.

Quickstart: Trigger an Outbound Call in 10 Seconds

Pass the customer's phone number, the agent ID and any context about the customer in one authenticated JSON POST. Add the header x-call-type: test while you call your own phone:

curl -X POST https://app.vistaraai.in/api/v1/calls/initiate \
  -H "x-api-key: $VISTARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "agentId": "AGENT_UUID",
    "name": "Ravi",
    "metadata": { "lead_id": "L-1042" }
  }'

# Response: { "success": true, "callId": "7b840e61-…", "message": "Call initiated successfully" }

Webhook Receiver: Structured Results After Every Call

Once the call finishes, Vistara AI posts one event to the agent's webhook URL with the recording URL, transcript, summary, sentiment and extracted answers. Webhooks carry no signature, so protect the URL with a secret token:

// Express webhook handler (set the URL as the agent's webhook_url)
app.post("/webhooks/vistara/:token", express.json(), (req, res) => {
  if (req.params.token !== process.env.VISTARA_WEBHOOK_TOKEN) return res.sendStatus(404);
  res.sendStatus(200); // acknowledge first, then process

  const { event, callId, data } = req.body;
  if (event === "call.completed") {
    // data.transcript, data.summary, data.sentiment, data.answers, data.recordingUrl, data.metadata
    saveCallResult(callId, data);
  } else if (event === "call.failed") {
    markNotConnected(callId, data.status); // busy | no-answer | failed | canceled
  }
});

Failure Modes to Design For

Voice adds failure modes that a purely HTTP integration does not have, because there is a physical phone network and a human being involved. Handle these explicitly rather than treating any non-success as a generic error.

• The call is never answered — The most common outcome by volume in outbound. Your data model needs attempt-level records, not just a single call result per contact.
• Answered by voicemail — Dispositioned separately from a human answer. Treating these as connects will quietly corrupt every ratio you calculate.
• Answered, then immediately hung up — Distinct from a completed call and diagnostically important — it usually points at your opening line rather than anything technical.
• Partial extraction — The call completed but the customer did not answer every question. Make your fields nullable and decide what constitutes a usable result.
• Transfer failed — The hot transfer was attempted and nobody picked up. Have a defined fallback — usually booking a callback — rather than leaving the customer stranded.
• Duplicate triggers — Retried requests from your side. Call creation has no idempotency key, so do not blindly resend a request that timed out: mark it uncertain and let a reconciliation job check the call before retrying.

What the API Handles and What Stays Yours

A clear boundary makes estimation easier. This is the split.

Triggering Calls From Your Own Systems

The integration surface is deliberately small. If your system can send an HTTP request, it can place a call — no telephony knowledge required, and no need to understand SIP or carrier routing.

• Outbound trigger — Post the destination number, the agent ID and a JSON object of context variables. The call is queued immediately and returns a call ID.
• Result webhooks — Your endpoint receives one event per call when it ends — call.completed or call.failed — so your own system stays in sync without polling.
• Completion payload — On completion you get the transcript, the recording URL, the disposition and the structured fields the agent extracted.
• Mid-call tool calls — The agent can call back into your API during the conversation to check stock, fetch an outstanding balance, or reserve a slot, then speak the answer.
• No-code paths — For teams without engineering bandwidth, Google Sheets, file upload and native CRM connectors cover most workflows without writing anything.