Skip to main content
POST
/
v1
/
agents
curl -X POST https://api.example.com/v1/agents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "sms",
    "agent_name": "Sales Follow-up Agent",
    "starting_message": "Hi {{first_name}}, interested in our services?",
    "prompt": "You are a helpful sales agent. Ask about their budget and timeline.",
    "organization_id": "1763070568417x...",
    "user_id": "1763072368418x...",
    "drip_schedule": [
      {"day": 1, "message": "Just checking in!"},
      {"day": 3, "message": "Happy to help when you'\''re ready!"}
    ]
  }'

{
  "success": true,
  "agent_id": "1763072369786x980265710064263640",
  "agent_type": "sms",
  "agent_name": "Sales Follow-up Agent",
  "has_drip_schedule": true,
  "organization_id": "1763072364720x...",
  "created_by": "1763072368418x...",
  "message": "SMS agent created successfully",
  "powered_by": "Teli"
}
Create a reusable AI agent with custom conversation prompts. Supports both SMS and Voice agents.
SMS agents have no additional charges beyond standard SMS costs. Voice agents use Teli Voice platform with per-second billing.

​
Authorizations

​
X-API-Key
string
required
Authentication header containing your API key.

​
Body

​
agent_type
string
required
Agent type: sms or voiceExample: "voice"
​
agent_name
string
required
Display name for the agent.Example: "Sales Follow-up Agent" or "Sophie Agent"
​
starting_message
string
required
First message/greeting sent to contacts. Supports variables: {{first_name}}, {{last_name}}Example: "Hi {{first_name}}, interested in our services?"
​
prompt
string
required
AI behavior instructions. Tells the agent how to respond.Example: "You are working for Pranta Nir Software Solutions. You are supposed to ask users if they want any consulting or software development support. If yes, ask them their budget for the software."
​
organization_id
string
required
Organization unique_id.Example: "1763070568417x631086913669115287"
​
user_id
string
required
User unique_id (agent creator).Example: "1763072368418x263803518630956376"
​
drip_schedule
array
SMS agents only. Automated follow-up messages.Each item: { "day": number, "message": string }Example:
[
  {"day": 1, "message": "Just checking in from yesterday!"},
  {"day": 3, "message": "Still here if you need anything!"}
]
​
voice_id
string
Voice agents only. Voice ID for text-to-speech (e.g., “11labs-Adrian”, “11labs-Josh”)Default: "11labs-Adrian"
​
detect_voicemail
boolean
Voice agents only. Enable voicemail detection.Default: false
​
voicemail_message
string
Voice agents only. Message to leave if voicemail is detected.
​
language
string
Voice agents only. Language code (e.g., “en-US”, “es-ES”, “fr-FR”)Default: "en-US"
​
general_tools
array
Voice agents only. Tools for function calling (end call, transfer, custom API, etc.)See Update Agent Tools for details.
​
knowledge_base_ids
array
Voice agents only. Array of knowledge base IDs to link to this agent.Example: ["knowledge_base_7a0682ce5fc02413"]Agent will automatically retrieve relevant information from these KBs during calls.
​
kb_config
object
Voice agents only. Knowledge base retrieval configuration.Properties:
  • top_k (number): Chunks to retrieve (1-10, default: 3)
  • filter_score (number): Similarity threshold (0-1, default: 0.6)
Example:
{
  "top_k": 3,
  "filter_score": 0.6
}

curl -X POST https://api.example.com/v1/agents \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_type": "sms",
    "agent_name": "Sales Follow-up Agent",
    "starting_message": "Hi {{first_name}}, interested in our services?",
    "prompt": "You are a helpful sales agent. Ask about their budget and timeline.",
    "organization_id": "1763070568417x...",
    "user_id": "1763072368418x...",
    "drip_schedule": [
      {"day": 1, "message": "Just checking in!"},
      {"day": 3, "message": "Happy to help when you'\''re ready!"}
    ]
  }'

{
  "success": true,
  "agent_id": "1763072369786x980265710064263640",
  "agent_type": "sms",
  "agent_name": "Sales Follow-up Agent",
  "has_drip_schedule": true,
  "organization_id": "1763072364720x...",
  "created_by": "1763072368418x...",
  "message": "SMS agent created successfully",
  "powered_by": "Teli"
}

​
Response

​
agent_id
string
Agent identifier. Use this when creating campaigns.
​
unique_id
string
Agent unique identifier (alternative ID)
​
agent_type
string
Confirms the agent type: sms or voice
​
agent_name
string
Agent display name
​
has_drip_schedule
boolean
Whether automated follow-ups are configured (SMS agents only)
​
voice_agent_id
string
Voice agent ID (voice agents only)
​
voice_llm_id
string
Voice LLM ID (voice agents only)
​
voice_id
string
Voice ID for TTS (voice agents only)
​
powered_by
string
Always returns “Teli”

​
Agent Types

​
SMS Agents

  • Used for text-based conversations
  • Support drip schedules for automated follow-ups
  • No additional charges beyond SMS costs
  • Can be configured with SMS-to-voice transfer

​
Voice Agents

  • Used for phone call conversations
  • Powered by Teli Voice platform
  • Support voicemail detection and custom voicemails
  • Billed per second of call time
  • Can be used standalone or with SMS-to-voice transfer

​
Notes

  • Agent IDs are unique across your organization
  • Prompts support variable substitution: {'{'}{'{'}}first_name{'}'}{'}'}}, {'{'}{'{'}}last_name{'}'}{'}}'}
  • Voice agents are created on Teli Voice platform and automatically configured
  • SMS agents can trigger voice agents when SMS-to-voice is enabled in campaigns
  • Both agent types support organization-wide or user-specific visibility