Start a human call

curl --request POST \
  --url https://api.telleo.ai/v1/human-calls \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "phone_number": "+919876543210"
}
'

import requests

url = "https://api.telleo.ai/v1/human-calls"

payload = { "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({phone_number: '+919876543210'})
};

fetch('https://api.telleo.ai/v1/human-calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "hcall_7d2e9b1c4a6f8e0d3b5c7a9e",
  "object": "human_call",
  "status": "queued",
  "status_reason": "<string>",
  "no_answer_by": "counsellor",
  "counsellor": {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>"
  },
  "phone_number": "<string>",
  "contact": {
    "name": "<string>",
    "email": "[email protected]",
    "external_id": "<string>"
  },
  "crm_lead_linked": true,
  "metadata": {},
  "analyze": true,
  "status_updates": "realtime",
  "created_at": "2023-11-07T05:31:56Z",
  "dialed_at": "2023-11-07T05:31:56Z",
  "answered_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "duration_seconds": 123,
  "recording_url": "<string>",
  "recording_expires_at": "2023-11-07T05:31:56Z",
  "disposition": {
    "key": "INTERESTED",
    "label": "<string>",
    "notes": "<string>",
    "set_at": "2023-11-07T05:31:56Z",
    "set_by": "counsellor"
  },
  "analysis": {
    "status": "not_requested",
    "reason": "<string>",
    "summary": "<string>",
    "short_update": "<string>",
    "call_type": "<string>",
    "inferred_goal": "<string>",
    "outcome": "<string>",
    "sentiment": "<string>",
    "conversion_likelihood": "<string>",
    "counsellor_rating": 123,
    "outcome_rating": 123,
    "language": "<string>",
    "credits": 123,
    "completed_at": "2023-11-07T05:31:56Z"
  },
  "cost": {
    "credits": 123,
    "billed": true,
    "note": "billed_by_provider"
  },
  "idempotent_replay": true
}

POST

human-calls

Start a human call

curl --request POST \
  --url https://api.telleo.ai/v1/human-calls \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "phone_number": "+919876543210"
}
'

import requests

url = "https://api.telleo.ai/v1/human-calls"

payload = { "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({phone_number: '+919876543210'})
};

fetch('https://api.telleo.ai/v1/human-calls', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "id": "hcall_7d2e9b1c4a6f8e0d3b5c7a9e",
  "object": "human_call",
  "status": "queued",
  "status_reason": "<string>",
  "no_answer_by": "counsellor",
  "counsellor": {
    "id": "<string>",
    "name": "<string>",
    "email": "<string>"
  },
  "phone_number": "<string>",
  "contact": {
    "name": "<string>",
    "email": "[email protected]",
    "external_id": "<string>"
  },
  "crm_lead_linked": true,
  "metadata": {},
  "analyze": true,
  "status_updates": "realtime",
  "created_at": "2023-11-07T05:31:56Z",
  "dialed_at": "2023-11-07T05:31:56Z",
  "answered_at": "2023-11-07T05:31:56Z",
  "ended_at": "2023-11-07T05:31:56Z",
  "duration_seconds": 123,
  "recording_url": "<string>",
  "recording_expires_at": "2023-11-07T05:31:56Z",
  "disposition": {
    "key": "INTERESTED",
    "label": "<string>",
    "notes": "<string>",
    "set_at": "2023-11-07T05:31:56Z",
    "set_by": "counsellor"
  },
  "analysis": {
    "status": "not_requested",
    "reason": "<string>",
    "summary": "<string>",
    "short_update": "<string>",
    "call_type": "<string>",
    "inferred_goal": "<string>",
    "outcome": "<string>",
    "sentiment": "<string>",
    "conversion_likelihood": "<string>",
    "counsellor_rating": 123,
    "outcome_rating": 123,
    "language": "<string>",
    "credits": 123,
    "completed_at": "2023-11-07T05:31:56Z"
  },
  "cost": {
    "credits": 123,
    "billed": true,
    "note": "billed_by_provider"
  },
  "idempotent_replay": true
}

Authorizations

X-API-Key

string

header

required

Your AI calling API key (vak_call_…). Authorization: Bearer <key> also works.

Headers

Idempotency-Key

string

Any unique string per click, e.g. lead-8812-call-1. A retry with the same key and body returns the first call instead of ringing the counsellor again; a different body is refused (409). Honoured for 24 hours.

Maximum string length: 255

Body

application/json

phone_number

string

required

The contact to connect, E.164. Formatting is ignored as for AI calls.

Example:

"+919876543210"

counsellor_id

string

The counsellor to ring, from GET /counsellors. Send this or counsellor_email, not both.

counsellor_email

string<email>

The counsellor's email in your account (case-insensitive).

contact

object

Show child attributes

metadata

object

Anything you want back on the call and its webhooks (at most 8 KB as JSON).

analyze

boolean

default:false

Transcribe and analyse the call once its recording is in (0.15 credits per recorded minute). You get human_call.analysis_ready.

Response

Replay: a call with this Idempotency-Key already exists and is returned unchanged (idempotent_replay: true).

string

Example:

"hcall_7d2e9b1c4a6f8e0d3b5c7a9e"

object

string

Allowed value: "human_call"

status

enum<string>

Available options:

queued,

ringing_counsellor,

connecting,

in_progress,

completed,

no_answer,

busy,

failed,

canceled

status_reason

string

Why a call failed, in plain words. Present only when there is one.

no_answer_by

enum<string> | null

Only on no_answer / busy: which phone did not pick up, when the provider says so.

Available options:

counsellor,

contact,

null

counsellor

object

Show child attributes

phone_number

string

contact

object

Show child attributes

crm_lead_linked

boolean

The call was filed on the one lead in your account with this number (it shows on the lead's timeline).

metadata

object

analyze

boolean

status_updates

enum<string>

How live status is on your provider: Vacademy Voice realtime, Exotel final_only, Airtel delayed (after its call record is imported).

Available options:

realtime,

final_only,

delayed

created_at

string<date-time>

dialed_at

string<date-time> | null

answered_at

string<date-time> | null

When the contact picked up, when known.

ended_at

string<date-time> | null

duration_seconds

integer | null

recording_url

string | null

A temporary link to the recording (24 hours). Fetch the call again for a fresh link.

recording_expires_at

string<date-time> | null

disposition

object | null

The outcome recorded by the counsellor or by you. null until set.

Show child attributes

analysis

object

AI analysis of the conversation. Fields beyond status are present once it is completed.

Show child attributes

cost

object | null

null while the call runs. Only Vacademy Voice talk time is charged to your credits; Exotel and Airtel bill you directly.

Show child attributes

idempotent_replay

boolean

Only on POST /human-calls: true when this is the call created by an earlier request with the same Idempotency-Key.

Overview

Endpoints

Start a human call

Authorizations

Headers

Body

Response