Update an AI Assistant

Update an assistant by ID. This endpoint is the main way to configure through API everything available in the AI assistant configuration page.

Endpoint

PATCH

/ai-assistants/:id

Basic Settings

Use connection: "specific" only when you want this assistant to use a dedicated provider key:

json

Instructions and Guided Mode

Advanced instructions are stored in instructions.

Guided Mode stores both the structured easy_mode_config and the generated instructions.

Human Handoff

Use human_handoff_config to define when the assistant should transfer a conversation or voice call to a human.

AI Assistant Handoff

Use ai_assistant_handoff_config to transfer work to another specialized assistant.

Follow-Up Rules

Follow-up rules are used by conversation and support ticket assistants.

Automations and Entity Access

Enable automations the assistant can execute:

Accepted access values used by the assistant configuration UI are none and read. Some installations may also support read_write.

Advanced Options

Schedule

Internal Tools

Internal tools let the assistant use AchieveApex actions directly.

Common internal tool keys include:

Category	Tool keys
CRM	`create_contact`, `find_contact`, `get_contact`, `update_contact`, `create_deal`, `find_deals`, `get_deal`, `update_deal`, `add_deal_products`, `create_company`, `find_company`, `get_company`, `update_company`, `add_note`, `update_note`, `create_activity`, `update_activity`, `get_pipelines`, `get_currencies`, `get_custom_fields`, `get_notes`, `get_activities`, `find_organization_members`
Messaging	`find_conversations`, `get_conversation`, `initiate_whatsapp_conversation`, `find_whatsapp_template`, `send_whatsapp_template`, `send_conversation_message`, `get_email_broadcast_senders`, `send_email_broadcast`
Products	`get_product`, `search_products`
Automations	`find_automations`, `execute_automation`
Reservations	`find_reservations`, `create_reservation`, `update_reservation`, `get_reservation_services`, `get_available_slots` — see Reservations API and related reservation endpoints
Project Management	`find_projects`, `get_project`, `create_project`, `update_project`, `find_project_tasks`, `get_project_task`, `create_project_task`, `update_project_task`, `add_task_comment`, `get_task_statuses`, `find_project_deliverables`, `create_project_deliverable`, `update_project_deliverable`, `find_task_lists`, `create_task_list`, `find_collections`, `create_collection`, `find_project_members`, `add_project_member`, `find_team_members`, `find_teams`, `assign_task_user`, `unassign_task_user`, `add_task_dependency`, `find_project_documents`, `create_project_document`, `create_scope_change`, `add_collection_member`
Strategy	`find_strategies`, `find_strategy_cycles`, `find_objectives`, `create_objective`, `update_objective`, `find_key_results`, `create_key_result`, `update_key_result`, `find_okr_tasks`, `create_okr_task`, `update_okr_task`
Billing	`get_document_settings`, `find_estimates`, `create_estimate`, `add_estimate_item`, `update_estimate_item`, `update_estimate`, `find_invoices`, `create_invoice`, `add_invoice_item`, `convert_estimate_to_invoice`
Database	`get_database_schema`, `run_database_query`
Integrations	`http_request`
Series	`subscribe_to_series`, `unsubscribe_from_series`

API Tool Associations

Create reusable API tools through the API Tools API, then associate them with an assistant:

MCP Tool Connections

Validate MCP servers through the MCP Tool Connections API, then store the selected MCP server configuration on the assistant.

Voice Settings

Voice assistants use assistant_type: "voice" and store voice runtime settings in telnyx_ai_assistant_config.

See Voice Assistant Helpers for model, transcription language, voice listing, and Telnyx sync endpoints.

Response

json

Request Parameters

Parameter	Type	Description
`name`	String	Assistant display name
`ai_model_id`	Number	AI model used by the assistant
`connection`	String	`system`, `organization`, or `specific`
`specific_openai_secret_key`	String	Provider key used when `connection` is `specific`
`timezone`	String	IANA timezone used by schedules and time-aware behavior
`instructions`	String	Full advanced instructions
`instructions_language`	String	`ENG` or `ESP`
`is_easy_mode`	Boolean	Whether Guided Mode is enabled
`easy_mode_config`	Object or null	Guided Mode structured configuration
`human_handoff_config`	Object	Human handoff rules
`ai_assistant_handoff_config`	Object	AI assistant handoff rules
`external_handoff_targets`	Object	Voice external handoff target rules
`follow_up_config`	Object	Follow-up rule configuration
`access_permissions_automations`	Array	Automations the assistant can execute
`access_permissions_contact`	String	Contact access level
`access_permissions_deals`	String	Deal access level
`access_permissions_customer_support`	String	Customer support access level
`advanced_options`	Object	Model, tool, web search, and summary options
`additional_json_keys`	Array	Custom structured output keys
`disable_reply`	Boolean	Prevent assistant replies while keeping analysis/config active
`analyze_images`	Boolean	Allow image analysis
`enable_message_burst_handling`	Boolean	Group rapid incoming messages before replying
`can_send_images`	Boolean	Allow the assistant to send image responses
`response_config`	Object	Single or multi-message response behavior
`schedule_config`	Object	Availability schedule and out-of-schedule action
`internal_tools`	Object	AchieveApex internal tool permissions
`api_tools`	Array	Associated custom API tools
`mcp_tools`	Array	Connected MCP server configurations
`telnyx_ai_assistant_config`	Object	Voice assistant runtime configuration
`acting_user_id`	Number or null	User identity used by voice assistant write actions

Report an issue with this documentation

Please log in to report issues with our documentation.