Built for developers

Your code.
A natural
conversation.

Turn a request into a conversation that gets things done.

Give your agent the context. Let it talk, call your tools, and send the outcome back to your application.

Get an API key Explore the code

REST APIPython/Node.js/cURL

From request to resultIllustrative demo

POST /api/trigger-call/

curl --fail-with-body -X POST "https://api.vaanivoice.ai/api/trigger-call/" \

-H "X-API-Key: $VAANI_API_KEY" \

-H "Content-Type: application/json" \

-d '{

"agent_id": "YOUR_AGENT_ID",

"name": "Jane Doe",

"contact_number": "+12025550123",

"metadata": { "department": "cardiology" }

}'

Dispatch acceptedoutput.call_idSample request

01 — The conversationConnecting

VAANI

Hi Jane. Shall I book your cardiology appointment for Thursday at 10:30?

JANE

Yes, that works. Please book it.

book_appointmentReady when needed

02 — Back to your appcall_postprocessing

appointment_date —confirmation_code —

The outcome arrives after the call ends. Payload excerpt

Request accepted

One voice stack.
Multiple ways to connect.

01Call APIPut your agent on the line 02In-app voiceBring the conversation to your app 03CampaignsReach your audience, on schedule 04WebhooksGet the outcome, not just the audio

The first request

From a few lines
to the first ring.

Start with an agent, an API key, and a number.
Your application takes it from there.

1
Create an API key
In your dashboard, open Developers → API Keys.
2
Configure your agent
Have your agent ID and telephony setup ready.
3
Choose a test number
Use your own phone number, including + and the country code.

Before you run it

Set VAANI_API_KEY in your server environment. Replace the agent and phone placeholders. Keep your key out of browser code.

Read the complete quickstart

POST /api/trigger-call/REST API

1curl --fail-with-body -X POST "https://api.vaanivoice.ai/api/trigger-call/" \2  -H "X-API-Key: $VAANI_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "agent_id": "YOUR_AGENT_ID",6    "name": "Jane Doe",7    "contact_number": "+12025550123",8    "metadata": { "department": "cardiology" }9  }'

Accepted is just the beginning.

A successful response means the call was dispatched—not answered or completed. Keep output.call_id to retrieve results, or receive them through webhooks after processing.

Follow the outcome

Follow one conversation

A call is only
the beginning.

From your first request to the result in your app.Explore an illustrative appointment-booking flow.

API response01 / 05

Your application starts the call.

The request is accepted and a call ID comes back. The phone has not necessarily been answered yet.

The brief

Jane Doe · Cardiology
An agent configured to book appointments.

output.call_idJSON excerpt

{
  "success": true,
  "output": {
    "agent_name": "clinic_agent",
    "call_id": "outbound-SAMPLE_CALL_ID"
  }
}

Response excerpt · keep this ID to retrieve the transcript and analysis.

Get the result after the call

Vaani sends call events to your webhook endpoint. call_ended tells you the conversation has ended; call_postprocessing tells you the transcript, summary, and extracted details are ready.

Webhook guide

Agent experience

Persona is what it says. Experience is how the call feels.

Set this in the console, or patch /api/agent/{id}/experience. Only the fields you send are merged. The next call picks them up—nothing to retrain.

Background noise

bg_noise

0.2volume · 0–1

Filler words

filler_words

0.3frequency · 0–1

Eagerness to speak

eagerness_to_speak

balanced

Idle pulse

idle_conversation_settings

“Are you still there?”

Check-in Hang up

23s · 42s5–60s · warning before hang-up

Max duration

max_call_duration

30min

1maximum call length60

Voicemail

action

Detection enabled. Choose what happens when voicemail answers.

Idle check-in message

idle_call_warning_message

When the caller goes quiet

The agent checks in with this message after 23 seconds of silence.

End-call phrase

end_call_phrase

Your agent’s closing words

Set the phrase your agent uses to close the conversation.

PATCH /api/agent/{id}/experience

Configuration previewChanged: bg_noise

{
  "conversational_experience": {
    "eagerness_to_speak": "balanced",
    "bg_noise": {
      "enabled": true,
      "volume": 0.2,
      "sound": "office sound"
    },
    "filler_words": {
      "filler_words_frequency": 0.3,
      "filler_words_list": [
        "um",
        "let me see",
        "got it"
      ]
    }
  },
  "settings": {
    "idle_conversation_settings": {
      "pulse_check": true,
      "idle_call_warning_timeout": 23,
      "idle_call_hangup_timeout": 42,
      "idle_call_warning_message": "Are you still there?"
    },
    "end_call": {
      "enabled": true,
      "end_call_phrase": "Thank you. Goodbye!"
    },
    "call_settings": {
      "max_call_duration": 30,
      "enable_voicemail_detection": true,
      "action": "leave_message"
    }
  }
}

Local preview only · nothing is sent to the API

Illustrative conversation · not an audio simulation

AGENTum, let me check the available slots.

Balanced turn-takingNo fixed latency implied

Silence beginsCheck in at 23sEnd at 42s

Filler frequency changes how often phrases may be used, not a guaranteed word on every turn. Preview wording is illustrative.

Experience API reference ↗

Build around what you own

Your carrier. Your model.
Vaani’s voice stack.

Keep the line. Add the agent.

Connect your existing SIP trunk to Vaani. Your carrier owns the phone connection; Vaani runs the conversation and connects it to your tools.

Set up your carrier

Conversation architectureBYOC

Your SIP carrierYOUR INFRASTRUCTURE

Audio in / audio out

Vaani voice stackManaged conversation layer

UnderstandSpeech to text

ReasonAgent + model

SpeakText to speech

Actions during the conversation

Your application + REST toolsYOUR INFRASTRUCTURE

Your carrier remains the boundary for telephony ownership.

0–0msInterruption stop time

Stopping playback when the caller interrupts—not the full response turn.

0msFull-turn latency · p50

Caller finishes to agent audio. p90: 900–1200ms. Model and network affect timing.

0+Dialing countries

Availability depends on your telephony setup and carrier coverage.

Go a level deeper

Find your next
building block.

Dispatch calls, shape your agents, and read results.

api.vaanivoice.ai

POST /api/trigger-call/

Start an outbound call with a contact number. Telephony is the default; this example sends agent_id, name, contact_number, and optional metadata. Dispatch acceptance does not mean the call has finished. Replace the example number with your destination.

curl --fail-with-body -X POST "https://api.vaanivoice.ai/api/trigger-call/" \
  -H "X-API-Key: $VAANI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "YOUR_AGENT_ID",
    "name": "Jane Doe",
    "contact_number": "+12025550123",
    "metadata": { "department": "cardiology" }
  }'

Authenticate server-side with X-API-Key. Agent PATCH requests merge supplied fields. For endpoint coverage beyond these examples, use the API reference.

Keep building

Less setup.
More conversation.

The next step should be a useful one.
Start in the console, inspect the events, or open a guide.

Try your agent

Configure an agent in the console, then test it before wiring it into your application.

Open the console

Inspect the lifecycle

Walk through call events and the post-call result without dispatching a real call.

Explore the event flow

Start with Teacher AI

Describe the agent you need, then refine its behavior and connect your tools.

Meet Teacher AI

Build in your app

Follow the integration guides for telephony, browser voice, campaigns, and webhooks.

Open the guides

The implementation details

Good questions.
Clear answers.

How is latency measured?

Interruption stop time is typically 100–200ms: how quickly agent playback stops when the caller speaks. Full-turn response latency measures the caller finishing to the first agent audio: p50 is 600ms and p90 is 900–1200ms. Model choice, network, and telephony affect these timings.

Can the agent call our API during a conversation?

Yes. Configure a custom REST tool with its input schema. The agent can collect the required details, invoke your endpoint, and use the returned result in the conversation. The appointment flow above illustrates this pattern.

When are transcripts and analysis ready?

Post-call results finish asynchronously. The transcript endpoint can return 404 while processing, and call details may show waiting messages until analysis is ready. Completed call details include summary, entity, and call_eval_tag. You can also receive completed analysis through call_postprocessing.

How do we receive call results through webhooks?

Configure your webhook endpoint to receive call events. call_ended tells you the conversation has ended; call_postprocessing delivers the completed transcript, summary, and extracted details. Verify deliveries on your server using the signature contract documented for your integration before processing them.

Can we use voice inside our application?

Yes. Set medium to webrtc when calling trigger-call to start an in-app voice session. Make the API request from your backend and follow the WebRTC API reference for connection details. Keep your API key out of browser code.

What does a successful call trigger mean?

success: true means the request was accepted for dispatch, not that the person answered or the call completed. Save output.call_id to correlate the transcript, recording, call details, and webhook events.

Your next conversation starts here

Build the voice.
Keep it yours.

Get an API key, configure your agent, and make your first request.

Get an API key Read the quickstart

From a few linesto the first ring.

A call is onlythe beginning.

Your application starts the call.

Persona is what it says. Experience is how the call feels.

Your carrier. Your model.Vaani’s voice stack.

Keep the line. Add the agent.

Find your nextbuilding block.

POST /api/trigger-call/

Less setup.More conversation.

Try your agent

Inspect the lifecycle

Start with Teacher AI

Build in your app

Good questions.Clear answers.

Build the voice.Keep it yours.

From a few lines
to the first ring.

A call is only
the beginning.

Your carrier. Your model.
Vaani’s voice stack.

Find your next
building block.

Less setup.
More conversation.

Good questions.
Clear answers.

Build the voice.
Keep it yours.