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

MethodPathDescription
GET/ai-assistantsList AI assistants
GET/ai-assistants/:idGet an AI assistant
POST/ai-assistantsCreate an AI assistant
PATCH/ai-assistants/:idUpdate an AI assistant
PATCH/ai-assistants/:idConfigure a voice assistant
DELETE/ai-assistants/:idDelete an AI assistant
GET/ai-assistants-change-historyList configuration history
GET/ai-assistants-change-history/:idGet a history entry
POST/ai-assistants-restore-from-changes-historyRestore a configuration version
GET/telnyx-ai-modelsList voice LLM models
GET/telnyx-ai-voicesList voices
GET/telnyx-ai-transcription-languagesList 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

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerRequired on create. Organization that owns the assistant; must be your API key's organization.
created_by_user_idintegerID of the user who created the assistant. Not set automatically for API key requests.
namestringRequired on create. Display name.
descriptionstringShort description.
assistant_typestringOne of conversation, support-ticket, helpdesk, ai-chat, voice.
ai_model_idintegerRequired on create. ID from AI Models. Use a model whose active_in_* flag matches the assistant type.
connectionstringRequired on create. Model credential source: system, organization or specific. The server forces system unless your plan includes your own provider credentials.
specific_openai_secret_keystring | nullProvider key used when connection is specific. Treat it as a secret: it is returned as stored.
timezonestring | nullIANA timezone used by schedules and time-aware behavior. Default UTC, max 50 characters.
instructionsstring | nullFull system instructions (prompt). In guided mode this holds the generated prompt.
instructions_languagestringENG or ESP.
is_easy_modebooleanWhether guided mode is used. Default true.
easy_mode_configobject | nullGuided-mode source: brand, assistantName, role, and the arrays objectives, restrictions, additionalInstructions, products, promotions, conversationFlows, companyLocations, dialectSections, dynamicSections.
version_idstring | nullRead-only. New UUID generated on every create and update.
disable_replybooleanWhen true the assistant does not send replies. Default false.
analyze_imagesbooleanLet the assistant read images sent by the contact. Default true.
enable_message_burst_handlingbooleanGroup rapid incoming messages before replying. Default false.
can_send_imagesbooleanLet the assistant send image media. Default false. Turned on automatically when instructions reference an image from the assistant media library.
can_send_audiobooleanLet the assistant send audio media. Default false. Auto-enabled like can_send_images.
can_send_videobooleanLet the assistant send video media. Default false. Auto-enabled like can_send_images.
can_send_documentsbooleanLet the assistant send documents. Default false. Auto-enabled like can_send_images.
additional_json_keysarrayExtra structured-output keys the assistant fills on each reply.
advanced_optionsobjectverbosity (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_contactstring | nullContact access: none, read or read_write. Default none.
access_permissions_dealsstring | nullDeal access: none, read or read_write. Default none.
access_permissions_customer_supportstring | nullTicket access: none, read or read_write. Default none.
access_permissions_automationsarray | nullAutomations the assistant may run: { automation_id, when_to_use } (both required).
human_handoff_configobject | nullrules for handing off to team members. Each rule requires name, instructions and team_members ({ user_id, weight }, weight 0-100). See Update.
external_handoff_targetsobject | nullVoice 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_configobject | nullrules for handing off to another assistant. Each rule requires name, instructions, ai_assistant_id.
ai_safeguardsobject | nullPer-assistant overrides of the loop and rate-limit safeguards. Missing or null keys use the system values. See Update.
follow_up_configobjectenabled, follow_up_limit (default 3) and rules that send follow-ups when the contact stops replying.
api_toolsarray | nullAPI tools the assistant can call: { api_tool_id, description, when_to_use, config }.
internal_toolsobject | nullenabled, 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_configobject | nullresponse_mode (single or multi), max_messages_per_response (1-10), delay_between_messages_ms (500-5000), allow_no_reply, no_reply_instructions.
agent_loop_configobject | nullTool-calling loop limits: max_iterations (default 100) and enable_clarification (default true).
schedule_configobject | nullAvailability: always_on, weekly_schedule, out_of_schedule_action (message or handoff), schedule_not_available_message, schedule_handoff_config.
mcp_toolsarray | nullExternal MCP servers. See MCP Tool Connections.
voice_enabledboolean | nullRead as true for every voice assistant (set automatically).
telnyx_ai_assistant_configobject | nullVoice runtime configuration. See Configure a voice assistant.
acting_user_idinteger | nullVoice only. User whose identity the assistant uses for write actions during calls.
created_atstring (date-time)Read-only. Creation timestamp.
updated_atstring (date-time)Read-only. Last update timestamp.
deleted_atstring (date-time) | nullRead-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.