Agents and variables

Choose who calls, and fill their script with your data.

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": "[phone]",
  "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=.