Docs - AI phone agents for SMB

curl -X PUT https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "systemPrompt": "Updated system prompt with new instructions...",
    "status": "active",
    "ttsModel": "cartesia",
    "voiceSettings": {"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02", "speed": 1.1},
    "transferEnabled": true,
    "transferRules": "Transfer to +15559876543 for technical issues",
    "language": "multi",
    "timezone": "Europe/London",
    "knowledgebaseLinks": ["https://example.com/updated-faq"]
  }'

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
    "name": "Updated Agent Name",
    "description": "Handles customer inquiries",
    "greeting_message": "Hello! How can I help you today?",
    "system_prompt": "Updated system prompt...",
    "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.1},
    "config": {},
    "extensions": {},
    "integrations": {},
    "transfer_enabled": true,
    "transfer_rules": "Transfer to +15559876543 for technical issues",
    "language": "multi",
    "timezone": "Europe/London",
    "enable_recording": false,
    "echo_detection": false,
    "call_detection": false,
    "knowledgebase_links": ["https://example.com/updated-faq"],
    "email": null,
    "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-16T14:20:00Z"
  }
}

PUT

agents

{agentId}

curl -X PUT https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "systemPrompt": "Updated system prompt with new instructions...",
    "status": "active",
    "ttsModel": "cartesia",
    "voiceSettings": {"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02", "speed": 1.1},
    "transferEnabled": true,
    "transferRules": "Transfer to +15559876543 for technical issues",
    "language": "multi",
    "timezone": "Europe/London",
    "knowledgebaseLinks": ["https://example.com/updated-faq"]
  }'

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
    "name": "Updated Agent Name",
    "description": "Handles customer inquiries",
    "greeting_message": "Hello! How can I help you today?",
    "system_prompt": "Updated system prompt...",
    "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.1},
    "config": {},
    "extensions": {},
    "integrations": {},
    "transfer_enabled": true,
    "transfer_rules": "Transfer to +15559876543 for technical issues",
    "language": "multi",
    "timezone": "Europe/London",
    "enable_recording": false,
    "echo_detection": false,
    "call_detection": false,
    "knowledgebase_links": ["https://example.com/updated-faq"],
    "email": null,
    "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-16T14:20:00Z"
  }
}

Path Parameters

agentId

string

required

The unique identifier of the agent (UUID format)

Request Body

All fields are optional. Only include the fields you want to update.

Basic Information

name

string

Display name of the agent (1-255 characters)

description

string

Description of what the agent does

greetingMessage

string

Initial message the agent says when call starts

systemPrompt

string

System prompt defining agent behavior and personality

agentType

string

Type of agent configuration.Supported values: simple, advanced, custom, appointment_scheduler, receptionist, message_taker

status

string

Agent activation status.Supported values:

active - Agent is available to receive calls
inactive - Agent is temporarily disabled
cancelled - Agent is permanently disabled
pending - Agent is pending activation

AI/Voice Model Configuration

model

string

AI model used for the agent.Supported values: gpt-4.1 (recommended), gpt-4.1-mini, gpt-4o, gpt-4o-mini

voiceModel

string

Voice model for real-time speech

sttModel

string

Speech-to-text model.Supported values: deepgram

ttsModel

string

Text-to-speech model.Supported values: cartesia, minimax

voiceSettings

object

Voice configuration settings. Structure varies based on ttsModel:For 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:

{"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.
`max_endpointing_delay`	number	`2.0`	Maximum seconds to wait when the caller pauses mid-sentence.
`vad_min_silence_duration`	number	(system default)	Minimum silence duration in seconds for Voice Activity Detection. 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

Whether SIP call transfer is enabled. Supports:

SIP extensions: sip:extension@hostname
US phone numbers: Automatically formatted to tel:+1XXXXXXXXXX

emailToolEnabled

boolean

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

Whether to enable answering machine / voicemail detection

echoDetection

boolean

Whether to enable echo detection during calls

enableRecording

boolean

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. Pass null to revert to the account’s default email server.Use the List Email Servers endpoint to retrieve available IDs.

Localization

language

string

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

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 | null

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) and the agent uses them as verified facts when answering callers.

Set to a Place ID to link (or relink) the agent’s business.
Set to null or "" to unlink.
Changing or clearing the id also clears the cached listing data (google_place_data, google_place_context, google_place_fetched_at), so details from the previously linked business are never served while the new listing is fetched. Re-sending the already-stored id is a no-op and keeps the cache.

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 in IPA format. Replaces the entire pronunciations list for the agent.Each entry is an object with:

word — The word or name (1–100 characters)
phonemes — The IPA phoneme string

Pass an empty array [] to clear all pronunciation rules.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.Common properties:

Property	Type	Description
`enable_recording`	boolean	Enable call recording
`user_timezone`	string	IANA timezone (e.g., `America/New_York`)
`inactivity_timeout`	number	Seconds before inactivity prompt
`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.Webhook structure:

{
  "tools": [
    {
      "type": "webhook",
      "name": "Log_Call_To_CRM",
      "friendlyName": "Log to CRM",
      "description": "Logs call details and transcript to the CRM after the call ends",
      "condition": "after_call",
      "method": "POST",
      "url": "https://api.yourcrm.com/calls/log",
      "headers": [
        { "key": "Authorization", "value": "Bearer YOUR_API_TOKEN" }
      ],
      "parameters": [
        { "key": "caller_phone", "value": "" },
        { "key": "call_summary", "value": "" },
        { "key": "transcript", "value": "" },
        { "key": "sentiment", "value": "" }
      ]
    }
  ],
  "mcp_servers": [
    {
      "url": "https://mcp.acme.com/mcp",
      "name": "Acme CRM MCP"
    }
  ]
}

MCP server objects (mcp_servers):Same request validation as Create Agent — MCP request body: name and url are both required on each entry; transport_type, auth_headers (array of {key, value}), and initialization_options (object) are optional. The platform transforms each entry on write (name → connection_name, url → mcp_endpoint_url) so the stored shape differs from the request shape — see Get Agent — Stored MCP Connection Shape.Webhook conditions:

before_call - Execute before the agent answers
during_call - Execute while call is active
after_call - Execute after call ends

See Webhooks documentation for complete details and examples.

Integrations

integrations

object

Third-party integration configurations. Supported provider keys: modmed, googleCalendar, outlookCalendar, twilio, netsapiens. Unknown provider keys are stored as-is.Update semantics — unlike extensions (which is a full replace), integrations uses a field-level merge per provider:

Only the fields you send change; omitted fields and omitted providers are preserved.
Set a field to null to clear that field.
Set a whole provider to null to remove the provider.

This example updates only Twilio’s fromNumber, clears its testToNumber, and removes the ModMed integration — everything else is untouched:

{
  "integrations": {
    "twilio": { "fromNumber": "+15551234567", "testToNumber": null },
    "modmed": null
  }
}

Provider fields (required when creating a new provider entry; partial updates only need to leave the stored object valid):

Provider	Required fields	Optional fields
`twilio`	`accountSid`, `authToken`, `fromNumber`	`testToNumber`, `connected_at`
`modmed`	`firm_url_prefix`, `username`, `password`, `environment` (`sandbox`, `practice_sandbox`, `production`)	`tokens`, `connected_at`
`googleCalendar`	`access_token`, `expires_at`	`refresh_token`, `email`, `selected_calendar_id`, `selected_calendar_name`, `timezone`
`outlookCalendar`	`access_token`, `expires_at`	`refresh_token`, `email`, `selected_calendar_id`, `selected_calendar_name`, `timezone`
`netsapiens`	`url`, `username`, `password`, `domain`, `client_id`, `client_secret`, `extension`, `access_token`	`api_version` (`v1`, `v2`), `refresh_token`, `user_scope`, `connected_at`

Behavior notes:

Configs are stored as-is — credentials are not validated against the provider. ModMed/NetSapiens entries written without valid tokens will not function at runtime until tokens are supplied or the integration is connected via the Dashboard.
Unlike the Dashboard flow, writing twilio here does not auto-create the send_sms_via_twilio tool in extensions — add the tool yourself if you want the agent to send SMS.
Secret fields (passwords, authToken, client_secret, access/refresh tokens) are write-only: they are accepted on PUT but never returned by any agent endpoint. The merge semantics make this safe — a GET → modify → PUT round-trip won’t wipe stored secrets.

MCP can be set in the Dashboard or via extensions.mcp_servers here (see Create Agent — MCP request body); persisted shape on read is documented under Get Agent.

MCP servers are auto-tested on save. Each entry in extensions.mcp_servers is tested when you update the agent: reachable servers are stored with a fingerprint and discovered tools (green Connected badge in the Portal); unreachable servers are still stored but without a fingerprint (yellow Not tested badge), and the response includes a non-fatal warnings array ([{ "connection_name": "...", "message": "..." }]). Re-testing on update means an MCP server you keep in the payload retains its verified status instead of being reset.To validate a configuration before assigning it, use Test MCP Connection.

curl -X PUT https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "systemPrompt": "Updated system prompt with new instructions...",
    "status": "active",
    "ttsModel": "cartesia",
    "voiceSettings": {"voice_id": "f786b574-daa5-4673-aa0c-cbe3e8534c02", "speed": 1.1},
    "transferEnabled": true,
    "transferRules": "Transfer to +15559876543 for technical issues",
    "language": "multi",
    "timezone": "Europe/London",
    "knowledgebaseLinks": ["https://example.com/updated-faq"]
  }'

Secrets are never returned. Responses from this and every other agent endpoint omit secret fields: integration passwords, twilio.authToken, netsapiens.client_secret, calendar access/refresh tokens, and the SIP password inside sip_registration_data. Non-secret metadata (provider keys, usernames, accountSid, connected_at, calendar names) is still returned so you can see what’s configured.

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
    "name": "Updated Agent Name",
    "description": "Handles customer inquiries",
    "greeting_message": "Hello! How can I help you today?",
    "system_prompt": "Updated system prompt...",
    "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.1},
    "config": {},
    "extensions": {},
    "integrations": {},
    "transfer_enabled": true,
    "transfer_rules": "Transfer to +15559876543 for technical issues",
    "language": "multi",
    "timezone": "Europe/London",
    "enable_recording": false,
    "echo_detection": false,
    "call_detection": false,
    "knowledgebase_links": ["https://example.com/updated-faq"],
    "email": null,
    "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-16T14:20:00Z"
  }
}

Update Behavior

Only provided fields are updated; omitted fields retain their current values
The updated_at timestamp is automatically set to the current time
The provider field cannot be changed after creation

Get Agent Delete Agent

​Path Parameters

​Request Body

​Basic Information

​AI/Voice Model Configuration

​Call Features

​Localization

​Knowledge Base

​Business (Google Place)

​Warm Transfer

​Pronunciations

​Advanced Configuration

​Integrations

​Update Behavior

Path Parameters

Request Body

Basic Information

AI/Voice Model Configuration

Call Features

Localization

Knowledge Base

Business (Google Place)

Warm Transfer

Pronunciations

Advanced Configuration

Integrations

Update Behavior