Docs - AI phone agents for SMB

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
appointment_scheduler - Agent optimized for scheduling appointments
receptionist - Receptionist agent for call routing and transfers
message_taker - Agent that takes messages and routes to directory extensions

AI/Voice Model Configuration

model

string

default:"gpt-4.1"

AI model used for the agent’s language processing.Supported values:

gpt-4.1 - OpenAI GPT-4.1 (default, recommended)
gpt-4.1-mini - OpenAI GPT-4.1 Mini (faster, more cost-effective)
gpt-4o - OpenAI GPT-4o
gpt-4o-mini - OpenAI GPT-4o Mini

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)

voiceSettings

object

Voice configuration settings. Structure varies based on ttsModel:For Cartesia (ttsModel: "cartesia"):

{
  "voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
  "speed": 1.0
}

For MiniMax (ttsModel: "minimax"):

{
  "voice_id": "English_radiant_girl",
  "model": "speech-2.6-turbo",
  "speed": 1.0
}

Advanced Voice Timing (optional, applies to all TTS models):

Property	Type	Default	Description
`min_endpointing_delay`	number	`0.1`	Seconds to wait after the caller stops speaking before the agent responds. Lower values feel more responsive; higher values reduce false interruptions.
`max_endpointing_delay`	number	`2.0`	Maximum seconds to wait when the caller pauses mid-sentence. Prevents the agent from cutting in during natural speech pauses.
`vad_min_silence_duration`	number	(system default)	Minimum silence duration in seconds for Voice Activity Detection to consider speech ended. Omit to use the system default.

Example with advanced timing:

{
  "voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02",
  "speed": 1.0,
  "min_endpointing_delay": 0.1,
  "max_endpointing_delay": 5.0,
  "vad_min_silence_duration": 0.55
}

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

emailToolEnabled

boolean

default:"false"

Whether the agent can send emails during or after calls

emailToolInstructions

string

Instructions for the agent on how and when to use the email tool

callDetection

boolean

default:"false"

Whether to enable answering machine / voicemail detection

echoDetection

boolean

default:"false"

Whether to enable echo detection during calls

enableRecording

boolean

default:"false"

Enable call recording. Recordings are saved to cloud storage and accessible via the Call Logs API.

transferRules

string

Rules and conditions for call transfers. Describes when and where the agent should transfer calls.Example: "Transfer to +15551234567 if the caller asks for billing support. Transfer to +15559876543 for technical issues."

array

Array of email addresses used for notifications and the email tool.Example: ["[email protected]", "[email protected]"]

emailServerId

string | null

UUID of the email server to use for this agent. Must belong to the same account. If omitted or null, the account’s default email server is used.Use the List Email Servers endpoint to retrieve available IDs.

Localization

language

string

default:"en-US"

Agent language for speech recognition and responses.Supported values:

en-US - English (US)
es-US - Spanish (US)
multi - Multilingual (English, Spanish, French, German, Hindi, Russian, Portuguese, Japanese, Italian, Dutch)

timezone

string

default:"America/New_York"

Agent timezone in IANA format. Used for date/time operations and calendar scheduling.Example: "America/New_York", "Europe/London", "Asia/Tokyo"

Knowledge Base

knowledgebaseLinks

array

Array of URLs the agent can reference for knowledge. The content at these URLs is ingested and made available to the agent during conversations.Example: ["https://example.com/faq", "https://example.com/pricing"]

Pronunciations

pronunciations

array

Custom pronunciation rules for specific words and names, using IPA (International Phonetic Alphabet) format. The agent’s TTS engine will use these rules to pronounce words correctly.Each entry is an object with:

word — The word or name (1–100 characters)
phonemes — The IPA phoneme string (e.g., <<ˈ|dʒ|eɪ|k|ə|b|s|ə|n>>)

Example:

[
  { "word": "Telzino", "phonemes": "<<t|ɛ|l|ˈz|iː|n|oʊ>>" },
  { "word": "jacobsen", "phonemes": "<<ˈ|dʒ|eɪ|k|ə|b|s|ə|n>>" }
]

Advanced Configuration

config

object

General configuration object for additional settings.Example:

{
  "enable_recording": true,
  "user_timezone": "America/New_York",
  "inactivity_timeout": 15
}

Property	Type	Description
`enable_recording`	boolean	Enable call recording (saved to S3)
`user_timezone`	string	IANA timezone for calendar operations (e.g., `America/New_York`)
`inactivity_timeout`	number	Seconds before “Are you still there?” prompt (default: 15)
`ambient_type`	string	Type of ambient background audio
`ambient_volume`	number	Volume level for ambient audio
`thinking_sounds_enabled`	boolean	Enable thinking/processing sounds during pauses
`thinking_volume`	number	Volume level for thinking sounds
`thinking_clip_id`	string	Sound clip to play while the agent is thinking. `KEYBOARD_TYPING` (default) or `KEYBOARD_TYPING2`
`background_audio_enabled`	boolean	Enable background audio during calls
`summary_context`	string	Additional instructions for the AI-generated call summary. Use this to tell the summary what to focus on or what data to extract (e.g., `"Focus on customer complaints. Extract any mentioned order numbers."`).

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:

Field	Type	Required	Description
`type`	string	Yes	Must be `"webhook"`
`name`	string	Yes	Unique identifier (e.g., `Create_Ticket`)
`friendlyName`	string	Yes	Human-readable display name
`description`	string	Yes	What the webhook does - helps AI understand when to use it
`condition`	string	Yes	When to trigger: `before_call`, `during_call`, or `after_call`
`method`	string	Yes	HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`
`url`	string	Yes	Endpoint URL to call
`headers`	array	No	Array of `{key, value}` objects for HTTP headers
`parameters`	array	No	Array 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-4.1",
    "ttsModel": "cartesia",
    "voiceSettings": {"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02", "speed": 1.0},
    "transferEnabled": true,
    "transferRules": "Transfer to +15551234567 if the caller asks for billing support",
    "language": "en-US",
    "timezone": "America/New_York",
    "enableRecording": true,
    "knowledgebaseLinks": ["https://example.com/faq", "https://example.com/pricing"],
    "email": ["[email protected]"]
  }'

{
  "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-4.1",
    "voice_model": "gpt-4o-realtime-preview",
    "stt_model": "deepgram",
    "tts_model": "cartesia",
    "voice_settings": {"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02", "speed": 1.0},
    "config": {},
    "extensions": {},
    "integrations": {},
    "transfer_enabled": true,
    "transfer_rules": "Transfer to +15551234567 if the caller asks for billing support",
    "language": "en-US",
    "timezone": "America/New_York",
    "enable_recording": true,
    "echo_detection": false,
    "call_detection": false,
    "knowledgebase_links": ["https://example.com/faq", "https://example.com/pricing"],
    "email": ["[email protected]"],
    "email_tool_enabled": false,
    "email_server_id": null,
    "pronunciations": [],
    "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:

Function	Description
`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.

API Reference

Agents

Email Servers

Voices

STT Providers

Call Logs

Metrics

Resellers

Organizations

Sessions

Billing

Create Agent

Request Body

Required Fields

Agent Configuration

AI/Voice Model Configuration

Call Features

Localization

Knowledge Base

Pronunciations

Advanced Configuration

Built-in Agent Functions

API Reference

Agents

Email Servers

Voices

STT Providers

Call Logs

Metrics

Resellers

Organizations

Sessions

Billing

​Request Body

​Required Fields

​Agent Configuration

​AI/Voice Model Configuration

​Call Features

​Localization

​Knowledge Base

​Pronunciations

​Advanced Configuration

​Built-in Agent Functions

Request Body

Required Fields

Agent Configuration

AI/Voice Model Configuration

Call Features

Localization

Knowledge Base

Pronunciations

Advanced Configuration

Built-in Agent Functions