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

PATCH
/ai-assistants/:id

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.

NameTypeDescription
namestringDisplay name.
descriptionstringShort description.
ai_model_idintegerModel from AI Models.
connectionstringsystem, organization or specific (forced to system unless your plan includes your own credentials).
specific_openai_secret_keystring | nullProvider key used when connection is specific.
timezonestring | nullIANA timezone.
instructionsstring | nullFull system instructions.
instructions_languagestringENG or ESP.
is_easy_modebooleanGuided mode.
easy_mode_configobject | nullGuided-mode source.
human_handoff_configobject | nullHandoff to team members.
ai_assistant_handoff_configobject | nullHandoff to another assistant.
external_handoff_targetsobject | nullVoice only: transfers to external numbers or SIP URIs.
follow_up_configobjectFollow-up rules.
access_permissions_automationsarray | nullAutomations the assistant can run.
access_permissions_contactstring | nullnone, read or read_write.
access_permissions_dealsstring | nullnone, read or read_write.
access_permissions_customer_supportstring | nullnone, read or read_write.
advanced_optionsobjectVerbosity, reasoning effort, tools and conversation summaries.
additional_json_keysarrayExtra structured-output keys.
disable_replybooleanStop sending replies.
analyze_imagesbooleanRead images sent by the contact.
enable_message_burst_handlingbooleanGroup rapid incoming messages.
can_send_imagesbooleanAllow sending images.
can_send_audiobooleanAllow sending audio.
can_send_videobooleanAllow sending video.
can_send_documentsbooleanAllow sending documents.
response_configobject | nullSingle or multi-message replies.
agent_loop_configobject | nullTool-calling loop limits.
ai_safeguardsobject | nullSafeguard overrides.
schedule_configobject | nullAvailability schedule.
internal_toolsobject | nullAchieveApex actions the assistant may use.
api_toolsarray | nullAssociated API tools.
mcp_toolsarray | nullConnected MCP servers.
telnyx_ai_assistant_configobject | nullVoice configuration. See Configure a voice assistant.
acting_user_idinteger | nullVoice 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 fieldTypeDescription
namestringRequired. 1-10 lowercase letters, numbers or underscores, unique per assistant.
instructionsstringRequired. When to use this rule.
team_membersarrayRequired. { 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_messagestring | nullMessage sent when handing off.
keep_assigned_team_memberboolean | nullKeep the currently assigned person.
assign_to_contact_ownerboolean | nullAssign to the contact owner.
unassign_ai_agentboolean | nullRemove the assistant from the conversation.
mark_conversation_unreadboolean | nullMark the conversation unread.
pipeline_id / stage_idinteger | nullMove the related deal to this pipeline stage.
respect_advisor_availabilityboolean | nullOnly assign to available advisors. Requires availability_fallback.type.
availability_fallbackobject | nulltype: 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.

KeyTypeRange
max_executions_per_hourinteger20-200
max_executions_per_dayinteger50-1000
max_responses_per_minuteinteger2-30
min_response_time_secondsnumber0-10
max_tokens_per_minuteinteger50000-2000000
anomaly_detection_enabledboolean
lookback_minutesinteger5-60
min_total_messagesinteger10-300
min_ai_outgoing_messagesinteger5-150
min_active_minutesinteger1-60
min_alternation_rationumber0.3-1
alternation_burst_window_msinteger0-10000
max_human_agent_messagesinteger0-50
min_repeated_incoming_text_countinteger0-100
strong_repeated_incoming_text_countinteger0-200
min_unsupported_incoming_messagesinteger0-100
require_secondary_signalboolean
ignored_repeated_incoming_textsstring[]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:

CategoryTool keys
CRMcreate_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 deskcreate_helpdesk_ticket, get_helpdesk_ticket, find_helpdesk_tickets, search_helpdesk_knowledge
Messagingfind_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 ordersget_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 financeget_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 linkslist_loyalty_programs, get_loyalty_card, enroll_loyalty_member, redeem_loyalty_reward, create_smart_link
Voicesget_organization_ai_voices, synthesize_ai_voice
Automationsfind_automations, execute_automation
Reservationsfind_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

StatusWhen
400Invalid value, unknown top-level field, invalid human handoff rule, schedule handoff or external handoff target.
404The assistant does not exist, is deleted or belongs to another organization.
500An 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.