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":{}}' \
  https://api.vaaniresearch.com/api/trigger-call/


{
  "success": true,
  "message": "Command processed",
  "output": "call_id_12345",
  "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 portal.vaaniresearch.com
  • 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: )

​
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

​
Request Body

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

​
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":{}}' \
  https://api.vaaniresearch.com/api/trigger-call/

​
Response

​
Success Response (200)

{
  "success": true,
  "message": "Command processed",
  "output": "call_id_12345",
  "error": null
}

​
Validation Error (422)

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