Agents and variables

An agent is a configured AI caller: its voice, language, opening line, script, the questions it asks and the labels it can give a call. You create and edit agents in the dashboard (Settings → AI calling); the API chooses which one makes each call with agent_id.

Listing agents

curl https://api.telleo.ai/v1/agents -H "X-API-Key: $TELLEO_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
      "object": "agent",
      "name": "Riya – admissions",
      "language": "en-IN",
      "uses_contact_name": true,
      "variables": ["course", "city"]
    }
  ],
  "has_more": false
}

Only agents that are turned on and can call out are listed. Using one that is turned off returns 409 agent_disabled; an inbound-only agent returns 409 agent_inbound_only.

Personalising the call

Agent scripts contain placeholders in double braces, such as:

Hi , this is Riya from Shiksha Academy. You enquired about in — is this a good time?

You fill them per call:

{
  "agent_id": "17ea33d2-5b6c-4c1e-9a1f-2d4e6f8a9b0c",
  "phone_number": "+919876543210",
  "contact": { "name": "Asha Verma" },
  "variables": { "course": "NEET 2027", "city": "Indore" }
}

{{name}} comes from contact.name. When uses_contact_name is true, always send it: an agent that does not know the name greets the person without it.
Everything else comes from variables. The variables list on each agent shows exactly which keys its script uses.
The agent also knows the current date and time on its own; you do not send those.

Rules for variables

	Limit
Number of variables	50 per call
Key	Starts with a letter; letters, digits, `_` and spaces; up to 40 characters
Value	Text, a number or `true`/`false`; up to 500 characters

Variables are spoken by the agent, so send them the way a person would say them: "NEET 2027", not "neet_2027_batch_b".

Keep data the agent should not say in metadata instead. It is stored with the call and returned to you, but never shown to the agent.

The contact

Field	Purpose
`contact.name`	How the agent addresses the person (up to 120 characters).
`contact.email`	Stored with the call and returned to you.
`contact.external_id`	Your id for this person (CRM record id, lead id). Filter calls with `GET /v1/calls?external_id=`.

Get started

Concepts

Webhooks

Guides

Platform

Agents and variables

Listing agents

Personalising the call

Rules for variables

The contact

​Listing agents

​Personalising the call

​Rules for variables

​The contact

Listing agents

Personalising the call

Rules for variables

The contact