curl --request POST \
--url https://api.telleo.ai/v1/calls \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"agent_id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
"phone_number": "+919876543210"
}
'import requests
url = "https://api.telleo.ai/v1/calls"
payload = {
"agent_id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
"phone_number": "+919876543210"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c',
phone_number: '+919876543210'
})
};
fetch('https://api.telleo.ai/v1/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "call_6f1d2c9a8b7e4f3a2d1c0b9a",
"object": "call",
"status": "queued",
"status_reason": "<string>",
"scheduled_for": "2023-11-07T05:31:56Z",
"agent_id": "<string>",
"phone_number": "<string>",
"contact": {
"name": "<string>",
"email": "[email protected]",
"external_id": "<string>"
},
"variables": {},
"metadata": {},
"batch_id": "<string>",
"test": true,
"duration_seconds": 123,
"created_at": "2023-11-07T05:31:56Z",
"dialed_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"recording_url": "<string>",
"recording_expires_at": "2023-11-07T05:31:56Z",
"outcome": {
"disposition": "<string>",
"summary": "<string>",
"answers": {},
"lead_rating": 5,
"callback_requested": true,
"callback_time_text": "<string>",
"follow_up": "CALL",
"follow_up_note": "<string>",
"meeting": {
"requested": true,
"at": "<string>",
"time_text": "<string>",
"type": "<string>"
},
"transcript": [
{
"speaker": "agent",
"text": "<string>"
}
]
},
"idempotent_replay": true
}Start a call
Queues a call to one number and dials it as soon as a line is free and calling hours allow. Returns the call at once (usually queued or dialing); the outcome arrives on your webhook, or poll GET /calls/{id}.
Scope: calls:write.
curl --request POST \
--url https://api.telleo.ai/v1/calls \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"agent_id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
"phone_number": "+919876543210"
}
'import requests
url = "https://api.telleo.ai/v1/calls"
payload = {
"agent_id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
"phone_number": "+919876543210"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c',
phone_number: '+919876543210'
})
};
fetch('https://api.telleo.ai/v1/calls', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "call_6f1d2c9a8b7e4f3a2d1c0b9a",
"object": "call",
"status": "queued",
"status_reason": "<string>",
"scheduled_for": "2023-11-07T05:31:56Z",
"agent_id": "<string>",
"phone_number": "<string>",
"contact": {
"name": "<string>",
"email": "[email protected]",
"external_id": "<string>"
},
"variables": {},
"metadata": {},
"batch_id": "<string>",
"test": true,
"duration_seconds": 123,
"created_at": "2023-11-07T05:31:56Z",
"dialed_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z",
"recording_url": "<string>",
"recording_expires_at": "2023-11-07T05:31:56Z",
"outcome": {
"disposition": "<string>",
"summary": "<string>",
"answers": {},
"lead_rating": 5,
"callback_requested": true,
"callback_time_text": "<string>",
"follow_up": "CALL",
"follow_up_note": "<string>",
"meeting": {
"requested": true,
"at": "<string>",
"time_text": "<string>",
"type": "<string>"
},
"transcript": [
{
"speaker": "agent",
"text": "<string>"
}
]
},
"idempotent_replay": true
}Authorizations
Your AI calling API key (vak_call_…). Authorization: Bearer <key> also works.
Headers
Any unique string, e.g. your lead id. Retrying with the same key and body returns the first call instead of calling twice.
255Body
The agent that makes the call. Required on POST /calls; on a batch row it overrides the batch's agent_id. List yours with GET /agents.
E.164, e.g. +919876543210. Spaces, dashes, dots and brackets are ignored; a leading 00 is read as +.
"+919876543210"
Show child attributes
Show child attributes
Values for the {{placeholders}} in the agent's script. Keys: a letter, then letters, digits, _ or spaces, at most 40 characters. Values: text, number or boolean, at most 500 characters.
Show child attributes
Show child attributes
{ "course": "NEET 2027", "city": "Indore" }
Anything you want back on the call and its webhook (at most 8 KB as JSON). The agent never sees it.
{ "crm_owner": "u_42" }
Simulate the call: no phone rings and nothing is billed. It completes at once with a sample outcome and fires your webhook.
Response
Replay: a call with this Idempotency-Key already exists and is returned unchanged (idempotent_replay: true).
"call_6f1d2c9a8b7e4f3a2d1c0b9a"
"call"queued, dialing, in_progress, completed, no_answer, busy, failed, canceled, expired Why a call is waiting or did not happen, in plain words. Present only when there is one.
Present while a queued call is held until a later time (outside calling hours, a recall gap, the daily limit).
Show child attributes
Show child attributes
A temporary link to the recording. Fetch the call again for a fresh link after recording_expires_at.
What the AI took from the conversation. null until it has been processed (usually within a minute of the call ending), and for calls that did not connect.
Show child attributes
Show child attributes
Only on POST /calls: true when this is the call created by an earlier request with the same Idempotency-Key.