curl https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.telzino.com/v1/agents/${agentId}`, {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
});
const { data } = await response.json();
console.log(data.name, data.status);
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.telzino.com/v1/agents/{agent_id}',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
agent = response.json()['data']
print(f"Agent: {agent['name']} - Status: {agent['status']}")
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"greeting_message": "Hello! Thank you for calling. How can I help you today?",
"system_prompt": "You are a helpful customer support agent for Acme Corp. Be friendly, professional, and concise.",
"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": {
"enable_recording": true,
"user_timezone": "America/New_York",
"inactivity_timeout": 15
},
"extensions": {
"tools": [
{
"type": "webhook",
"name": "check_order",
"description": "Check order status",
"url": "https://api.example.com/orders",
"method": "GET"
}
],
"mcp_servers": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"connection_name": "Example MCP",
"mcp_endpoint_url": "https://mcp.example.com/mcp",
"transport_type": "http",
"auth_headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"initialization_options": {},
"fingerprint": "sha256:abc123",
"tools": [
{
"name": "get_order_status",
"description": "Look up order status by order id"
}
]
}
]
},
"integrations": {
"googleCalendar": {
"email": "[email protected]",
"expires_at": "2026-06-13T10:30:00Z",
"selected_calendar_name": "Bookings",
"timezone": "America/New_York"
}
},
"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"],
"email": ["[email protected]"],
"email_tool_enabled": false,
"email_tool_instructions": null,
"status": "active",
"is_active": true,
"sip_registration_data": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Agents
Get Agent
Retrieves details of a specific agent by ID
GET
/
v1
/
agents
/
{agentId}
curl https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.telzino.com/v1/agents/${agentId}`, {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
});
const { data } = await response.json();
console.log(data.name, data.status);
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.telzino.com/v1/agents/{agent_id}',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
agent = response.json()['data']
print(f"Agent: {agent['name']} - Status: {agent['status']}")
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"greeting_message": "Hello! Thank you for calling. How can I help you today?",
"system_prompt": "You are a helpful customer support agent for Acme Corp. Be friendly, professional, and concise.",
"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": {
"enable_recording": true,
"user_timezone": "America/New_York",
"inactivity_timeout": 15
},
"extensions": {
"tools": [
{
"type": "webhook",
"name": "check_order",
"description": "Check order status",
"url": "https://api.example.com/orders",
"method": "GET"
}
],
"mcp_servers": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"connection_name": "Example MCP",
"mcp_endpoint_url": "https://mcp.example.com/mcp",
"transport_type": "http",
"auth_headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"initialization_options": {},
"fingerprint": "sha256:abc123",
"tools": [
{
"name": "get_order_status",
"description": "Look up order status by order id"
}
]
}
]
},
"integrations": {
"googleCalendar": {
"email": "[email protected]",
"expires_at": "2026-06-13T10:30:00Z",
"selected_calendar_name": "Bookings",
"timezone": "America/New_York"
}
},
"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"],
"email": ["[email protected]"],
"email_tool_enabled": false,
"email_tool_instructions": null,
"status": "active",
"is_active": true,
"sip_registration_data": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Path Parameters
string
required
The unique identifier of the agent (UUID format)
curl https://api.telzino.com/v1/agents/123e4567-e89b-12d3-a456-426614174000 \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const agentId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.telzino.com/v1/agents/${agentId}`, {
headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' }
});
const { data } = await response.json();
console.log(data.name, data.status);
import requests
agent_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.telzino.com/v1/agents/{agent_id}',
headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
agent = response.json()['data']
print(f"Agent: {agent['name']} - Status: {agent['status']}")
{
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"organization_id": "987fcdeb-51a2-3bc4-d567-890123456789",
"name": "Customer Support Agent",
"description": "Handles customer inquiries and support requests",
"greeting_message": "Hello! Thank you for calling. How can I help you today?",
"system_prompt": "You are a helpful customer support agent for Acme Corp. Be friendly, professional, and concise.",
"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": {
"enable_recording": true,
"user_timezone": "America/New_York",
"inactivity_timeout": 15
},
"extensions": {
"tools": [
{
"type": "webhook",
"name": "check_order",
"description": "Check order status",
"url": "https://api.example.com/orders",
"method": "GET"
}
],
"mcp_servers": [
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"connection_name": "Example MCP",
"mcp_endpoint_url": "https://mcp.example.com/mcp",
"transport_type": "http",
"auth_headers": {
"Authorization": "Bearer YOUR_TOKEN"
},
"initialization_options": {},
"fingerprint": "sha256:abc123",
"tools": [
{
"name": "get_order_status",
"description": "Look up order status by order id"
}
]
}
]
},
"integrations": {
"googleCalendar": {
"email": "[email protected]",
"expires_at": "2026-06-13T10:30:00Z",
"selected_calendar_name": "Bookings",
"timezone": "America/New_York"
}
},
"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"],
"email": ["[email protected]"],
"email_tool_enabled": false,
"email_tool_instructions": null,
"status": "active",
"is_active": true,
"sip_registration_data": null,
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
{
"error": "not_found",
"error_description": "Agent not found or access denied"
}
Response Fields
Core Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique agent identifier (UUID) |
organization_id | string | Organization the agent belongs to |
name | string | Display name of the agent |
description | string | What the agent does |
status | string | active, inactive, cancelled, or pending |
is_active | boolean | Computed from status (true if status is active) |
Conversation Configuration
| Field | Type | Description |
|---|---|---|
greeting_message | string | First message spoken when call connects |
outbound_greeting_message | string | Greeting spoken when the agent places an outbound call |
outbound_static_greeting | string | Fixed, non-AI line spoken before the outbound greeting |
voicemail_message | string | Message left when Answering Machine Detection reaches a voicemail box |
voicemail_message_audio_url | string | Pre-recorded voicemail audio, played instead of the message when set |
warm_transfer_handoff_instructions | string | What the AI says to the human on a warm transfer consult leg |
system_prompt | string | AI instructions defining behavior |
agent_type | string | simple, advanced, custom, appointment_scheduler, receptionist, message_taker, blank_slate, outbound, opentable_reservation or translator |
interpreter_config | object or null | Interpreter settings, in the shape documented under interpreterConfig on Create Agent. null unless interpreter settings are stored for this agent — sending interpreterConfig stores it on any agent type, an agent changed away from translator keeps its last settings here, unused, and sending interpreterConfig: null to a non-translator agent clears it. speaker_identification is absent from the object unless it is voice or both |
AI/Voice Models
| Field | Type | Description |
|---|---|---|
model | string | LLM model: gpt-4.1, gpt-4o, gpt-4o-mini, gpt-4.1-mini, gpt-4.1-nano, grok-3-fast, moonshotai/Kimi-K2.6, claude-sonnet-4-6, google/gemma-4-31b-it (see List LLM Models) |
voice_model | string | Voice model for realtime speech |
stt_model | string | Speech-to-text: deepgram |
tts_model | string | Text-to-speech: cartesia, minimax, deepgram |
voice_settings | object | TTS-specific voice configuration |
Configuration Objects
| Field | Type | Description |
|---|---|---|
config | object | General settings (enable_recording, user_timezone, etc.) |
extensions | object | Webhook tools (tools) and MCP connections (mcp_servers) — see below |
integrations | object | Third-party integrations keyed by provider (modmed, googleCalendar, outlookCalendar, twilio, netsapiens). Secret fields are never returned — see below. twilio holds the agent’s fromNumber; Twilio credentials belong to the organization’s Twilio connection; agents whose own credentials have not been removed yet still return them (accountSid, apiKeySid) |
Secrets are redacted from all agent responses. Integration secret fields — passwords,
twilio.authToken / twilio.apiKeySecret (agents whose own Twilio credentials have not been removed yet), netsapiens.client_secret, and calendar access/refresh tokens — and the SIP password inside sip_registration_data are omitted (not masked) from this and every other agent endpoint. Non-secret metadata (provider keys, usernames, accountSid, connected_at, calendar names) is still returned. Secrets are write-only: set them via Update Agent, whose field-level merge means a GET → modify → PUT round-trip won’t wipe stored secrets.Stored MCP Connection Shape
Each item inextensions.mcp_servers is returned exactly as stored — no field remapping occurs on GET. After saving via the Dashboard or the API, each entry uses the snake_case shape documented below.
Both "sse" and "http" transports use the same field set. transport_type is always stored lowercase. For "http", provide your streamable HTTP MCP endpoint in mcp_endpoint_url; for "sse" provide your SSE endpoint URL. The mcp_endpoint_url field accepts https:// (production) or http:// (e.g. local dev) as the URL scheme.
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Present once the connection has been saved |
connection_name | string | Human-readable connection label |
mcp_endpoint_url | string | Full MCP endpoint URL. Use your SSE endpoint when transport_type is "sse", or your streamable HTTP endpoint when transport_type is "http". Accepts https:// or http:// scheme |
transport_type | string | "sse" or "http", lowercase only |
auth_headers | object | Optional. Object of header names to string values, sent to the MCP server |
initialization_options | object | Optional. Arbitrary JSON passed at MCP client initialization |
fingerprint | string | Present only after the connection has been tested (via Dashboard or API test). Absent for connections created via the API that have never been tested from the Portal. |
tools | array | Cached list of tools discovered during the last connection test. Each item has name and description only — full JSON schemas are not stored. Empty for API-created connections that have not yet been tested. |
allowed_tool_names | array | Optional. Names of the tools the agent may use from this server. Absent or empty means every tool the server publishes. Set from the Tools checkboxes in the MCP dialog or via the API. |
pre_answer_calls | array | Optional. Tools the platform calls while the phone is ringing (Pre-Answer). Each item has tool_name, arguments (may contain {{caller_id}} and the other call placeholders) and, when set from the Portal, input_schema — the chosen tool’s input schema, kept so the form can be redrawn (the only place a full tool schema is stored). Absent or empty means none; the Portal saves [] when no tools are chosen. |
extensions on POST or PUT, the API validates a different request shape. See Create Agent — MCP Servers Request Body for the accepted fields. Do not paste a GET mcp_servers array into a create or update body without transforming the entries.
Call Features
| Field | Type | Description |
|---|---|---|
transfer_enabled | boolean | Whether call transfer function is available |
transfer_rules | string | Rules/conditions for call transfers |
enable_recording | boolean | Whether call recording is enabled |
echo_detection | boolean | Whether echo detection is enabled |
call_detection | boolean | Whether mobile calls detection (number lookup) is enabled — not answering machine detection |
web_transfer_enabled | boolean | Whether a caller on the web-embedded agent can be transferred |
amd_config | object | Answering Machine Detection settings (enabled, sensitivity, on_machine, on_silence, …). Write it back as amdConfig |
ivr_navigation | object | IVR Menu Navigation settings. Write it back as ivrNavigation |
default_retry_policy_id | string | The retry policy the agent’s outbound calls follow. Write it back as defaultRetryPolicyId |
contact_policy | object | Compliance controls: require_consent_basis, calling_windows, abandon_rate_alert_threshold. Write it back as contactPolicy |
screenshare_enabled | boolean | Whether this agent may ask a web caller to share their screen. See Screenshare |
email_tool_enabled | boolean | Whether the email tool is enabled |
email_tool_instructions | string | Instructions for email tool usage |
email | array | Email addresses for notifications and email tool |
sip_registration_data | object | SIP registration configuration (if set) |
Localization
| Field | Type | Description |
|---|---|---|
language | string | Agent language (en-US, es-US, or multi) |
timezone | string | Agent timezone in IANA format (e.g., America/New_York) |
Knowledge Base
| Field | Type | Description |
|---|---|---|
knowledgebase_links | array | URLs the agent references for knowledge |
Business (Google Place)
| Field | Type | Description |
|---|---|---|
google_place_id | string | Linked Google Business Profile listing. Set via googlePlaceId on Create / Update |
google_place_data | object | Raw listing details from Google (service-managed, read-only) |
google_place_context | string | Curated business facts the agent uses on calls (service-managed, read-only) |
google_place_fetched_at | string | When the listing was last fetched. Data older than 30 days is never used on calls |
Timestamps
| Field | Type | Description |
|---|---|---|
created_at | datetime | When the agent was created |
updated_at | datetime | When the agent was last modified |
