AI Assistants
An AI assistant answers conversations, support tickets, internal AI chat or voice calls on behalf of your organization. Everything you can configure on the assistant settings page (instructions, handoff, follow-ups, tools, schedule, voice) is stored on the assistant record, so you can manage it entirely through this resource.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /ai-assistants | List AI assistants |
GET | /ai-assistants/:id | Get an AI assistant |
POST | /ai-assistants | Create an AI assistant |
PATCH | /ai-assistants/:id | Update an AI assistant |
PATCH | /ai-assistants/:id | Configure a voice assistant |
DELETE | /ai-assistants/:id | Delete an AI assistant |
GET | /ai-assistants-change-history | List configuration history |
GET | /ai-assistants-change-history/:id | Get a history entry |
POST | /ai-assistants-restore-from-changes-history | Restore a configuration version |
GET | /telnyx-ai-models | List voice LLM models |
GET | /telnyx-ai-voices | List voices |
GET | /telnyx-ai-transcription-languages | List transcription languages |
Your API key is scoped to one organization: list and get only return assistants of that organization, and organization_id must be your organization's ID when you create one.
The AI assistant object
json
Fields
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Required on create. Organization that owns the assistant; must be your API key's organization. |
created_by_user_id | integer | ID of the user who created the assistant. Not set automatically for API key requests. |
name | string | Required on create. Display name. |
description | string | Short description. |
assistant_type | string | One of conversation, support-ticket, helpdesk, ai-chat, voice. |
ai_model_id | integer | Required on create. ID from AI Models. Use a model whose active_in_* flag matches the assistant type. |
connection | string | Required on create. Model credential source: system, organization or specific. The server forces system unless your plan includes your own provider credentials. |
specific_openai_secret_key | string | null | Provider key used when connection is specific. Treat it as a secret: it is returned as stored. |
timezone | string | null | IANA timezone used by schedules and time-aware behavior. Default UTC, max 50 characters. |
instructions | string | null | Full system instructions (prompt). In guided mode this holds the generated prompt. |
instructions_language | string | ENG or ESP. |
is_easy_mode | boolean | Whether guided mode is used. Default true. |
easy_mode_config | object | null | Guided-mode source: brand, assistantName, role, and the arrays objectives, restrictions, additionalInstructions, products, promotions, conversationFlows, companyLocations, dialectSections, dynamicSections. |
version_id | string | null | Read-only. New UUID generated on every create and update. |
disable_reply | boolean | When true the assistant does not send replies. Default false. |
analyze_images | boolean | Let the assistant read images sent by the contact. Default true. |
enable_message_burst_handling | boolean | Group rapid incoming messages before replying. Default false. |
can_send_images | boolean | Let the assistant send image media. Default false. Turned on automatically when instructions reference an image from the assistant media library. |
can_send_audio | boolean | Let the assistant send audio media. Default false. Auto-enabled like can_send_images. |
can_send_video | boolean | Let the assistant send video media. Default false. Auto-enabled like can_send_images. |
can_send_documents | boolean | Let the assistant send documents. Default false. Auto-enabled like can_send_images. |
additional_json_keys | array | Extra structured-output keys the assistant fills on each reply. |
advanced_options | object | verbosity (low, medium, high), reasoning_effort (none, minimal, low, medium, high), tools (search_product, web_search, web_search_config) and conversation_summary_config (enabled, instructions). Summaries are enabled by default for conversation, support-ticket and ai-chat assistants. |
access_permissions_contact | string | null | Contact access: none, read or read_write. Default none. |
access_permissions_deals | string | null | Deal access: none, read or read_write. Default none. |
access_permissions_customer_support | string | null | Ticket access: none, read or read_write. Default none. |
access_permissions_automations | array | null | Automations the assistant may run: { automation_id, when_to_use } (both required). |
human_handoff_config | object | null | rules for handing off to team members. Each rule requires name, instructions and team_members ({ user_id, weight }, weight 0-100). See Update. |
external_handoff_targets | object | null | Voice only. rules that transfer calls to an external number or SIP URI. Each rule requires id, name, instructions, label, destination_type (external_number or sip_uri). |
ai_assistant_handoff_config | object | null | rules for handing off to another assistant. Each rule requires name, instructions, ai_assistant_id. |
ai_safeguards | object | null | Per-assistant overrides of the loop and rate-limit safeguards. Missing or null keys use the system values. See Update. |
follow_up_config | object | enabled, follow_up_limit (default 3) and rules that send follow-ups when the contact stops replying. |
api_tools | array | null | API tools the assistant can call: { api_tool_id, description, when_to_use, config }. |
internal_tools | object | null | enabled, a tools map of AchieveApex actions (find_contact: true, ...) and track_conversation_event_config.event_definition_ids. ai-chat and helpdesk assistants get a default tool set on create. |
response_config | object | null | response_mode (single or multi), max_messages_per_response (1-10), delay_between_messages_ms (500-5000), allow_no_reply, no_reply_instructions. |
agent_loop_config | object | null | Tool-calling loop limits: max_iterations (default 100) and enable_clarification (default true). |
schedule_config | object | null | Availability: always_on, weekly_schedule, out_of_schedule_action (message or handoff), schedule_not_available_message, schedule_handoff_config. |
mcp_tools | array | null | External MCP servers. See MCP Tool Connections. |
voice_enabled | boolean | null | Read as true for every voice assistant (set automatically). |
telnyx_ai_assistant_config | object | null | Voice runtime configuration. See Configure a voice assistant. |
acting_user_id | integer | null | Voice only. User whose identity the assistant uses for write actions during calls. |
created_at | string (date-time) | Read-only. Creation timestamp. |
updated_at | string (date-time) | Read-only. Last update timestamp. |
deleted_at | string (date-time) | null | Read-only. Set when the assistant is deleted. |
GET/ai-assistants/:id and PATCH/ai-assistants/:id responses also include a computed, read-only ai_safeguards_system object (defaults and ranges of every safeguard). Do not send it back.
Related
Report an issue with this documentation
Please log in to report issues with our documentation.