Update an AI assistant
Partially update an assistant. This is how you configure through the API everything the assistant settings page offers. Send only the fields you want to change; object fields such as human_handoff_config are replaced as a whole.
Endpoint
Body
Any writable field of the AI assistant object. Unknown top-level fields are rejected; do not send read-only fields such as id, version_id or ai_safeguards_system.
| Name | Type | Description |
|---|---|---|
name | string | Display name. |
description | string | Short description. |
ai_model_id | integer | Model from AI Models. |
connection | string | system, organization or specific (forced to system unless your plan includes your own credentials). |
specific_openai_secret_key | string | null | Provider key used when connection is specific. |
timezone | string | null | IANA timezone. |
instructions | string | null | Full system instructions. |
instructions_language | string | ENG or ESP. |
is_easy_mode | boolean | Guided mode. |
easy_mode_config | object | null | Guided-mode source. |
human_handoff_config | object | null | Handoff to team members. |
ai_assistant_handoff_config | object | null | Handoff to another assistant. |
external_handoff_targets | object | null | Voice only: transfers to external numbers or SIP URIs. |
follow_up_config | object | Follow-up rules. |
access_permissions_automations | array | null | Automations the assistant can run. |
access_permissions_contact | string | null | none, read or read_write. |
access_permissions_deals | string | null | none, read or read_write. |
access_permissions_customer_support | string | null | none, read or read_write. |
advanced_options | object | Verbosity, reasoning effort, tools and conversation summaries. |
additional_json_keys | array | Extra structured-output keys. |
disable_reply | boolean | Stop sending replies. |
analyze_images | boolean | Read images sent by the contact. |
enable_message_burst_handling | boolean | Group rapid incoming messages. |
can_send_images | boolean | Allow sending images. |
can_send_audio | boolean | Allow sending audio. |
can_send_video | boolean | Allow sending video. |
can_send_documents | boolean | Allow sending documents. |
response_config | object | null | Single or multi-message replies. |
agent_loop_config | object | null | Tool-calling loop limits. |
ai_safeguards | object | null | Safeguard overrides. |
schedule_config | object | null | Availability schedule. |
internal_tools | object | null | AchieveApex actions the assistant may use. |
api_tools | array | null | Associated API tools. |
mcp_tools | array | null | Connected MCP servers. |
telnyx_ai_assistant_config | object | null | Voice configuration. See Configure a voice assistant. |
acting_user_id | integer | null | Voice only: user identity for write actions. |
Every update generates a new version_id and, for voice assistants, re-syncs the voice agent with the voice provider. Updates made with an API key are not recorded in the change history.
Request
Response
The updated AI assistant object, including the read-only ai_safeguards_system object (shortened):
json
Instructions and guided mode
Advanced mode: write instructions yourself.
Guided mode stores the structured easy_mode_config and the prompt generated from it in instructions. The server does not generate the prompt for you: send both.
json
Human handoff
human_handoff_config.rules[] define when the assistant hands the conversation (or call) to people.
json
| Rule field | Type | Description |
|---|---|---|
name | string | Required. 1-10 lowercase letters, numbers or underscores, unique per assistant. |
instructions | string | Required. When to use this rule. |
team_members | array | Required. { user_id, weight }; users must be members of your organization and weights must add up to 100. For voice assistants each user must be an active voice agent. Can be empty only when assign_to_contact_owner is true. |
handoff_message | string | null | Message sent when handing off. |
keep_assigned_team_member | boolean | null | Keep the currently assigned person. |
assign_to_contact_owner | boolean | null | Assign to the contact owner. |
unassign_ai_agent | boolean | null | Remove the assistant from the conversation. |
mark_conversation_unread | boolean | null | Mark the conversation unread. |
pipeline_id / stage_id | integer | null | Move the related deal to this pipeline stage. |
respect_advisor_availability | boolean | null | Only assign to available advisors. Requires availability_fallback.type. |
availability_fallback | object | null | type: unassigned, keep_ai, fallback_user (requires user_id of a member) or contact_owner. |
AI assistant handoff
ai_assistant_handoff_config.rules[] hand the conversation to another assistant of your organization. A voice assistant can only hand off to voice assistants and vice versa, and never to itself.
json
name, instructions and ai_assistant_id are required. trigger_ai_reply makes the target assistant reply right away; also_send_current_ai_reply also sends the current assistant's reply.
Follow-up rules
json
Each rule requires id, when_to_assign and follow_up_actions. Action type is template (with template.type email, whatsapp or predefined_message and template.template_id), automation (automation_id) or ai_generated_message (instruction).
Automations and entity access
json
automation_id and when_to_use are required. wait_for_response waits for the automation result; default_response is used otherwise.
Advanced options
json
web_search_config.user_location.country is a 2-letter code and allowed_domains holds up to 20 domains. persist_tool_context keeps previous tool results in the conversation context.
AI safeguards
ai_safeguards overrides the protection that stops an assistant from looping or replying too fast. Omit a key (or set it to null) to use the system value; out-of-range values are clamped. Get the assistant to see the current system defaults in ai_safeguards_system.
| Key | Type | Range |
|---|---|---|
max_executions_per_hour | integer | 20-200 |
max_executions_per_day | integer | 50-1000 |
max_responses_per_minute | integer | 2-30 |
min_response_time_seconds | number | 0-10 |
max_tokens_per_minute | integer | 50000-2000000 |
anomaly_detection_enabled | boolean | |
lookback_minutes | integer | 5-60 |
min_total_messages | integer | 10-300 |
min_ai_outgoing_messages | integer | 5-150 |
min_active_minutes | integer | 1-60 |
min_alternation_ratio | number | 0.3-1 |
alternation_burst_window_ms | integer | 0-10000 |
max_human_agent_messages | integer | 0-50 |
min_repeated_incoming_text_count | integer | 0-100 |
strong_repeated_incoming_text_count | integer | 0-200 |
min_unsupported_incoming_messages | integer | 0-100 |
require_secondary_signal | boolean | |
ignored_repeated_incoming_texts | string[] | up to 50 texts of 60 characters |
json
Schedule
json
out_of_schedule_action is message (default) or handoff. schedule_handoff_config also accepts availability_fallback with the same shape as in human handoff rules.
Internal tools
json
Common tool keys:
| Category | Tool keys |
|---|---|
| CRM | create_contact, find_contact, get_contact, update_contact, set_contact_dnd, 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, delete_activity, get_pipelines, get_currencies, get_custom_fields |
| Help desk | create_helpdesk_ticket, get_helpdesk_ticket, find_helpdesk_tickets, search_helpdesk_knowledge |
| Messaging | find_conversations, get_conversation, update_conversation, get_conversation_messages, search_conversation_messages, initiate_whatsapp_conversation, find_whatsapp_template, send_whatsapp_template, send_conversation_message, get_email_broadcast_senders, send_email_broadcast, track_conversation_event |
| Products and orders | get_product, search_products, find_orders, get_order, create_order, update_order, add_order_item, update_order_item, delete_order_item, cancel_order, get_order_payment_link, update_order_fulfillment, convert_estimate_to_order, convert_order_to_invoice, create_checkout_link |
| Billing and finance | get_estimate_pdf, get_invoice_pdf, find_finance_plans, get_finance_plan, calculate_finance_scenario, create_finance_plan, update_finance_plan, save_finance_plan_version |
| Loyalty and links | list_loyalty_programs, get_loyalty_card, enroll_loyalty_member, redeem_loyalty_reward, create_smart_link |
| Voices | get_organization_ai_voices, synthesize_ai_voice |
| Automations | find_automations, execute_automation |
| Reservations | find_reservations, create_reservation, update_reservation, delete_reservation, get_reservation_services |
API tool associations
Create the tool with the API Tools API, then attach it:
json
api_tool_id is required.
MCP servers
Check the server with the MCP connection test, then store it:
json
Errors
| Status | When |
|---|---|
400 | Invalid value, unknown top-level field, invalid human handoff rule, schedule handoff or external handoff target. |
404 | The assistant does not exist, is deleted or belongs to another organization. |
500 | An AI assistant handoff rule points to a missing assistant, the wrong assistant type, or the assistant itself (the message explains which). |
Report an issue with this documentation
Please log in to report issues with our documentation.