Skip to main content
POST
https://api.telzino.com
/
v1
/
agents
curl -X POST https://api.telzino.com/v1/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Handles customer inquiries and support requests",
    "greetingMessage": "Hello! Thank you for calling Acme Corp. How can I help you today?",
    "systemPrompt": "You are a helpful customer support agent for Acme Corp. Be friendly and professional. If the customer needs to speak with a human, use the transfer_call function.",
    "agentType": "simple",
    "model": "gpt-4o",
    "ttsModel": "cartesia",
    "voiceSettings": {"voice_id": "alloy", "speed": 1.0},
    "transferEnabled": true,
    "config": {
      "enable_recording": true,
      "user_timezone": "America/New_York"
    }
  }'

{
  "data": {
    "id": "abc12345-e89b-12d3-a456-426614174000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries",
    "greeting_message": "Hello! How can I help you today?",
    "system_prompt": "You are a helpful customer support agent...",
    "agent_type": "simple",
    "model": "gpt-4o",
    "voice_model": "gpt-4o-realtime-preview",
    "stt_model": "deepgram",
    "tts_model": "cartesia",
    "voice_settings": {"voice_id": "alloy", "speed": 1.0},
    "config": {"enable_recording": true, "user_timezone": "America/New_York"},
    "extensions": {},
    "integrations": {},
    "transfer_enabled": true,
    "status": "active",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Request Body

​
Required Fields

​
name
string
required
Display name of the agent (1-255 characters)
​
organizationId
string
required
Organization ID to create the agent in (UUID format)

​
Agent Configuration

​
description
string
Description of what the agent does
​
greetingMessage
string
Initial message the agent says when call starts. This is spoken immediately when a call connects.Example: "Hello! Thank you for calling Acme Corp. How can I help you today?"
​
systemPrompt
string
System prompt defining agent behavior and personality. This guides the AI’s responses throughout the conversation.Example: "You are a helpful customer support agent for Acme Corp. Be friendly, professional, and concise. If you don't know an answer, offer to transfer the call to a human agent."
​
agentType
string
default:"simple"
Type of agent configuration.Supported values:
  • simple - Basic agent with standard configuration
  • advanced - Agent with additional features enabled
  • custom - Fully customizable agent configuration

​
AI/Voice Model Configuration

​
model
string
default:"gpt-4o"
AI model used for the agent’s language processing.Supported values:
  • gpt-4o - OpenAI GPT-4o (recommended)
  • gpt-4o-mini - OpenAI GPT-4o Mini (faster, more cost-effective)
​
voiceModel
string
default:"gpt-4o-realtime-preview"
Voice model for real-time speech processing
​
sttModel
string
default:"deepgram"
Speech-to-text model.Supported values:
  • deepgram - Deepgram STTv2 with flux-general-en model (recommended)
​
ttsModel
string
default:"cartesia"
Text-to-speech model.Supported values:
  • cartesia - Cartesia TTS (high quality, supports custom voices)
  • minimax - MiniMax TTS (multilingual support)
  • deepgram - Deepgram TTS (Aura voices)
​
voiceSettings
object
Voice configuration settings. Structure varies based on ttsModel:For Cartesia (ttsModel: "cartesia"):
{
  "voice_id": "alloy",
  "speed": 1.0
}
For MiniMax (ttsModel: "minimax"):
{
  "voice_id": "English_radiant_girl",
  "model": "speech-2.6-turbo",
  "speed": 1.0
}
For Deepgram (ttsModel: "deepgram"):
{
  "voice_id": "aura-asteria-en"
}

​
Call Features

​
transferEnabled
boolean
default:"false"
Whether SIP call transfer is enabled. When enabled, the agent can transfer calls to:
  • SIP extensions: Format sip:extension@hostname
  • US phone numbers: Automatically formatted to tel:+1XXXXXXXXXX

​
Advanced Configuration

​
config
object
General configuration object for additional settings.Example:
{
  "enable_recording": true,
  "user_timezone": "America/New_York",
  "inactivity_timeout": 15
}
PropertyTypeDescription
enable_recordingbooleanEnable call recording (saved to S3)
user_timezonestringIANA timezone for calendar operations (e.g., America/New_York)
inactivity_timeoutnumberSeconds before “Are you still there?” prompt (default: 15)
​
extensions
object
Extensions configuration for webhooks and MCP servers.Structure:
{
  "tools": [
    {
      "type": "webhook",
      "name": "Create_Support_Ticket",
      "friendlyName": "Create Ticket",
      "description": "Creates a support ticket when the customer reports an issue",
      "condition": "after_call",
      "method": "POST",
      "url": "https://api.helpdesk.com/v2/tickets",
      "headers": [
        { "key": "Authorization", "value": "Bearer YOUR_API_TOKEN" },
        { "key": "Content-Type", "value": "application/json" }
      ],
      "parameters": [
        { "key": "subject", "value": "" },
        { "key": "description", "value": "" },
        { "key": "customer_email", "value": "[email protected]" },
        { "key": "priority", "value": "normal" }
      ]
    }
  ],
  "mcp_servers": []
}
Webhook fields:
FieldTypeRequiredDescription
typestringYesMust be "webhook"
namestringYesUnique identifier (e.g., Create_Ticket)
friendlyNamestringYesHuman-readable display name
descriptionstringYesWhat the webhook does - helps AI understand when to use it
conditionstringYesWhen to trigger: before_call, during_call, or after_call
methodstringYesHTTP method: GET, POST, PUT, PATCH, or DELETE
urlstringYesEndpoint URL to call
headersarrayNoArray of {key, value} objects for HTTP headers
parametersarrayNoArray of {key, value} objects - AI extracts values from conversation
Webhook conditions:
  • before_call - Execute before the agent answers (pre-fetch caller info)
  • during_call - Execute while call is active (create tickets, real-time lookups)
  • after_call - Execute after call ends (log to CRM, send summaries)
Parameters: Leave the value empty for fields you want the AI to extract from the conversation. Provide default values for fallbacks.
Integrations (Google Calendar, Outlook, ModMed) are configured via the Telzino Dashboard UI, not through this API. The integrations field may appear in GET responses but cannot be set via POST/PUT requests.
curl -X POST https://api.telzino.com/v1/agents \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "organizationId": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Handles customer inquiries and support requests",
    "greetingMessage": "Hello! Thank you for calling Acme Corp. How can I help you today?",
    "systemPrompt": "You are a helpful customer support agent for Acme Corp. Be friendly and professional. If the customer needs to speak with a human, use the transfer_call function.",
    "agentType": "simple",
    "model": "gpt-4o",
    "ttsModel": "cartesia",
    "voiceSettings": {"voice_id": "alloy", "speed": 1.0},
    "transferEnabled": true,
    "config": {
      "enable_recording": true,
      "user_timezone": "America/New_York"
    }
  }'

{
  "data": {
    "id": "abc12345-e89b-12d3-a456-426614174000",
    "organization_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries",
    "greeting_message": "Hello! How can I help you today?",
    "system_prompt": "You are a helpful customer support agent...",
    "agent_type": "simple",
    "model": "gpt-4o",
    "voice_model": "gpt-4o-realtime-preview",
    "stt_model": "deepgram",
    "tts_model": "cartesia",
    "voice_settings": {"voice_id": "alloy", "speed": 1.0},
    "config": {"enable_recording": true, "user_timezone": "America/New_York"},
    "extensions": {},
    "integrations": {},
    "transfer_enabled": true,
    "status": "active",
    "is_active": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Built-in Agent Functions

When created, every agent automatically has access to these functions that the AI can call during conversations:
FunctionDescription
transfer_call(phone_number)Transfer call to a SIP extension or US phone number (requires transferEnabled: true)
end_call()End the current call gracefully
get_date_details(date_string)Parse and get details about a date/time
Additional functions are added based on enabled integrations (Google Calendar, Outlook, ModMed) and configured webhook tools in the extensions field.