Docs - AI phone agents for SMB

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"
  }
}

POST

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-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"
  }
}

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
}

Cartesia voices also accept two optional fields:

Property	Type	Description
`model`	string	Cartesia TTS model (e.g. `sonic-3`). When set, must match the model registered for the selected `voice_id`.
`language`	string	Locale passed to Cartesia TTS (e.g. `es`). When set, must match the language registered for the selected `voice_id`.

Most English Cartesia voices do not accept model or language overrides. Non-English voices (e.g. Spanish) require both:

{
  "voice_id": "d46e87a1-7c6d-4b18-9359-926f4a35ffdf",
  "model": "sonic-3",
  "language": "es",
  "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"]

Business (Google Place)

googlePlaceId

string

Google Place ID linking the agent to a Google Business Profile listing. The platform fetches the listing’s details (hours, location, phone, website, services, ratings) shortly after creation, and the agent uses them as verified facts when answering callers.Example: "ChIJVS6XxJPFU4gRoE8c8ql2lCQ"

Warm Transfer

warmTransferEnabled

boolean

Enable warm transfer routing for this agent.

warmTransferRules

string

Plain-language rules for when and where to warm transfer. Example: "If the caller asks for billing, confirm first and warm transfer to pbx:1234."

warmTransferMohUrl

string

Public URL of the hold-music file played during warm transfer. The easiest way to set this is Upload Hold Music, which saves the URL for you. Leave empty for built-in hold music.

warmTransferPassThroughCallerNumber

boolean

Whether the original caller’s number is passed to the transfer destination. Defaults to true.

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": [
    {
      "url": "https://mcp.acme.com/mcp",
      "name": "Acme CRM MCP"
    }
  ]
}

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.

MCP Servers Request Body

Each entry in the mcp_servers array inside extensions is validated at write time. The request shape is different from the stored shape returned by GET. Validated request fields for each mcp_servers entry:

Field	Type	Required	Description
`name`	string	Yes	Friendly label for the connection (displayed in the Portal)
`url`	string	Yes	MCP endpoint URL. Use your streamable HTTP endpoint when `transport_type` is `"http"`, or your SSE endpoint when `transport_type` is `"sse"`
`transport_type`	string	No	`"sse"` (default) or `"http"`
`auth_headers`	array	No	Array of `{key, value}` objects sent as HTTP headers to the MCP server
`initialization_options`	object	No	Optional MCP initialization options stored with the connection

After saving, the platform transforms each entry to the stored MCPConnection format: name → connection_name, url → mcp_endpoint_url, auth_headers array → header object, and assigns a generated id. See Get Agent — Stored MCP Connection Shape for the full list of stored fields.

The Get Agent response returns the stored shape with snake_case keys: id, connection_name, mcp_endpoint_url, transport_type (lowercase sse or http), and optional tools entries with name and description only. Do not paste a GET mcp_servers array into a create or update body without transforming it to match the request fields above.The schema is strict — any unrecognized field in an mcp_servers entry (for example, fields from the stored GET shape such as connection_name, mcp_endpoint_url, or id) will be rejected with a 400 error. Only url, name, transport_type, auth_headers, and initialization_options are accepted.

MCP servers are auto-tested on save. When you include extensions.mcp_servers, the API tests each server (opening the transport and listing tools). Reachable servers are stored with a fingerprint and discovered tools, and appear with a green Connected badge in the Portal (agent → Integrations → MCP). Servers that are unreachable at save time are still stored, but without a fingerprint — they appear with a yellow Not tested badge, and the response includes a non-fatal warnings array:

{ "data": { "...": "..." }, "warnings": [{ "connection_name": "Acme CRM MCP", "message": "Connection failed" }] }

To validate a configuration before creating an agent, use Test MCP Connection.

The integrations field cannot be set on create. After creating the agent, configure integrations (ModMed, Google/Outlook Calendar, Twilio, NetSapiens) via the Dashboard or with the integrations field on Update Agent. Integration secrets are write-only — they never appear in API responses, including this endpoint’s response. MCP servers can be configured in the Dashboard under agent Integrations, or via extensions.mcp_servers on this endpoint and on Update Agent.

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), configured webhook tools in extensions.tools, and MCP servers in extensions.mcp_servers.

List Agents Get Agent

​Request Body

​Required Fields

​Agent Configuration

​AI/Voice Model Configuration

​Call Features

​Localization

​Knowledge Base

​Business (Google Place)

​Warm Transfer

​Pronunciations

​Advanced Configuration

​MCP Servers Request Body

​Built-in Agent Functions

Request Body

Required Fields

Agent Configuration

AI/Voice Model Configuration

Call Features

Localization

Knowledge Base

Business (Google Place)

Warm Transfer

Pronunciations

Advanced Configuration

MCP Servers Request Body

Built-in Agent Functions