Skip to main content
POST
/
api
/
trigger-call
# API_KEY=your_api_key

curl -X POST -H "X-API-Key:vaani_3916d7d1d8736c2883582d8ab005be31" -H "Content-Type: application/json" \
 -d '{"agent_id":"uuid-or-agent-name","contact_number":"+1234567890","name":"John","voice":"","metadata":{},"outbound_number":"+1234567890","dnd_check_skipped":true}' \
 https://api.vaanivoice.ai/api/trigger-call/


{
  "success": true,
  "message": "Call initiated successfully",
  "output": {
    "agent_name": "vaani321talha",
    "call_id": "outbound-1776774443-863aa698"
  },
  "error": null
}

​
Create Dispatch

Create an outbound call. This endpoint triggers an outbound call using a preconfigured agent.

​
Important Concepts

​
Agent ID

You must pass an agent_id, which is a UUID that uniquely identifies an agent. You can obtain the agent_id from the Agent Config page on the Vaani portal:
  • Go to app.vaanivoice.ai
  • Navigate to Agent Config
  • Select your agent
  • Copy the Agent ID (UUID)

​
Metadata

The metadata object contains template variables that you configure while creating the agent.
  • Each key in metadata corresponds to a variable used in the agent’s prompt or flow
  • These values are dynamically injected at call time
  • The structure depends on how the agent was configured

​
Required Fields

  • agent_id: Agent UUID from the Agent Config page
  • contact_number: Contact number with country code (e.g., +919876543210)
  • name: Customer name
  • voice: Voice preference (optional, default: "")
  • metadata: Template variables for the agent (optional, default: )

​
Optional Telephony Fields

  • outbound_number: Specific outbound caller ID to use (E.164 format)

​
DND Check Control

  • dnd_check_skipped: Set to true to skip the Do Not Disturb (DND) check for the call

​
Parameters

​
agent_id
string
required
Agent UUID obtained from the Agent Config page on the portal
​
contact_number
string
required
Contact number with country code (e.g., +919876543210)
​
name
string
required
Customer name
​
voice
string
default:""
Voice preference (optional)
​
metadata
object
default:"{}"
Template variables configured while creating the agent
​
dnd_check_skipped
boolean
default:"false"
Set to true to skip the Do Not Disturb (DND) check for this call
​
outbound_number
string
default:"null"
Optional outbound caller ID to use (E.164 format)

​
Request Body

{
  "agent_id": "string (uuid)",
  "contact_number": "string",
  "name": "string",
  "voice": "string",
  "metadata": {},
  "outbound_number": "string",
  "dnd_check_skipped": "boolean",
}

​
Request Example

# API_KEY=your_api_key

curl -X POST -H "X-API-Key:vaani_3916d7d1d8736c2883582d8ab005be31" -H "Content-Type: application/json" \
 -d '{"agent_id":"uuid-or-agent-name","contact_number":"+1234567890","name":"John","voice":"","metadata":{},"outbound_number":"+1234567890","dnd_check_skipped":true}' \
 https://api.vaanivoice.ai/api/trigger-call/

​
Response

​
Success Response (200)

{
  "success": true,
  "message": "Call initiated successfully",
  "output": {
    "agent_name": "vaani321talha",
    "call_id": "outbound-1776774443-863aa698"
  },
  "error": null
}
​
success
boolean
Whether the call was dispatched successfully
​
message
string
Status message — "Call initiated successfully" on success
​
output
object
Call dispatch details
​
error
string | null
Error message if the operation failed, null on success

​
Validation Error (422)

{
  "detail": [
    {
      "loc": ["body", "contact_number"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
​
detail
array
Array of validation error objects