Assistants

Update an assistant

Changed on

Updates the specified AI assistant's attributes and returns the updated assistant. The request can also control how the change is promoted across assistant versions. Every update saves a new version, and an assistant keeps at most 10 versions: once it has more, the oldest versions are permanently deleted, except the main version and any version referenced by a traffic distribution rule.

post/ai/assistants/{assistant_id}

Request

  • Base URL: https://api.telnyx.com/v2
  • URL: https://api.telnyx.com/v2/ai/assistants/{assistant_id}
  • Auth: HTTP bearer

Path parameters

assistant_idstring required

Unique identifier of the assistant.

Request body

namestring
modelstring

ID of the model to use when external_llm is not set. You can use the Get models API to see available models. If external_llm is provided, the assistant uses external_llm instead of this field. If neither model nor external_llm is provided, Telnyx applies the default model.

instructionsstring

System instructions for the assistant. These may be templated with dynamic variables

tool_idsstring[]

IDs of shared tools to attach to the assistant. New integrations should prefer tool_ids over inline tools. On update, a sent tool_ids array fully replaces the assistant's attached shared tools; omit the field to leave them unchanged. Single-instance tool types are counted across inline tools and tool_ids combined, so attaching a shared tool of such a type when an instance already exists returns HTTP 400 with error code 10015.

descriptionstring
greetingstring

Text that the assistant will use to start the conversation. This may be templated with dynamic variables. Use an empty string to have the assistant wait for the user to speak first. Use the special value <assistant-speaks-first-with-model-generated-message> to have the assistant generate the greeting based on the system instructions.

llm_api_key_refstring

This is only needed when using third-party inference providers selected by model. The identifier for an integration secret /v2/integration_secrets that refers to your LLM provider's API key. For bring-your-own endpoint authentication, use external_llm.llm_api_key_ref instead. Warning: Free plans are unlikely to work with this integration.

enabled_featuresEnabledFeatures[]
dynamic_variables_webhook_urlstring

If dynamic_variables_webhook_url is set, Telnyx sends a POST request to this URL at the start of the conversation to resolve dynamic variables. Gotcha: the webhook response must wrap variables under a top-level dynamic_variables object, e.g. {"dynamic_variables": {"customer_name": "Jane"}}. Returning a flat object will be ignored and variables will fall back to their defaults. See the dynamic variables guide for the full request/response format and timeout behavior.

dynamic_variables_webhook_timeout_msinteger

Timeout in milliseconds for the dynamic variables webhook. Must be between 1 and 10000 ms. If the webhook does not respond within this timeout, the call proceeds with default values. See the dynamic variables guide.

dynamic_variablesobject

Map of dynamic variables and their default values

tagsstring[]

Tags associated with the assistant. Tags can also be managed with the assistant tag endpoints.

version_namestring

Human-readable name for the assistant version.

promote_to_mainboolean

Indicates whether the assistant should be promoted to the main version. Defaults to true.

Example request

{
  "tools": [
    {
      "webhook": {
        "url": "https://example.com/api/v1/function",
        "body_parameters": {
          "properties": {
            "age": {
              "description": "The age of the customer.",
              "type": "integer"
            },
            "location": {
              "description": "The location of the customer.",
              "type": "string"
            }
          },
          "required": [
            "age",
            "location"
          ],
          "type": "object"
        },
        "path_parameters": {
          "properties": {
            "id": {
              "description": "The id of the customer.",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        },
        "query_parameters": {
          "properties": {
            "page": {
              "description": "The page number.",
              "type": "integer"
            }
          },
          "required": [
            "page"
          ],
          "type": "object"
        },
        "preset_body_fields": {
          "account_id": "{{customer_id}}",
          "source": "telnyx-assistant"
        },
        "preset_query_params": {
          "caller": "{{telnyx_end_user_target}}",
          "channel": "voice"
        },
        "messages": [
          {
            "type": "request_start",
            "content": "Let me look that up for you."
          },
          {
            "type": "request_response_delayed",
            "content": "Still working on that.",
            "timing_ms": 5000
          }
        ]
      }
    }
  ],
  "a2a_agents": [
    {
      "name": "billing_agent",
      "url": "https://agents.example.com",
      "headers": [
        {
          "name": "X-Api-Key",
          "value": "{{#integration_secret}}my_agent_api_key{{/integration_secret}}"
        }
      ],
      "timeout_ms": 30000,
      "poll_interval_ms": 500
    }
  ],
  "avatar_settings": {
    "provider": "telnyx",
    "avatar_id": "elena",
    "background_id": "office",
    "model": "foxtrot-1"
  },
  "transcription": {
    "fallback_models": [
      {
        "model": "deepgram/nova-3",
        "language": "en"
      },
      {
        "model": "soniox/stt-rt-v5",
        "settings": {
          "context": "Telnyx,VoIP,SIP"
        }
      }
    ],
    "challenger": {
      "model": "deepgram/nova-3",
      "language": "en",
      "rule": "best_turn"
    }
  },
  "insight_settings": {
    "model": "zai-org/GLM-5.3-Flash"
  },
  "conversation_flow": {
    "edges": [
      {
        "condition": {
          "prompt": "The caller is asking about a bill or charge.",
          "type": "llm"
        },
        "id": "e_intake_to_billing",
        "start_node_id": "n_intake",
        "target": {
          "node_id": "n_billing",
          "type": "node"
        }
      },
      {
        "condition": {
          "prompt": "The caller has explicitly asked for a human.",
          "type": "llm"
        },
        "id": "e_intake_to_escalation_assistant",
        "start_node_id": "n_intake",
        "target": {
          "assistant_id": "assistant-human-handoff",
          "position": {
            "x": 600,
            "y": 80
          },
          "type": "assistant",
          "voice_mode": "distinct"
        }
      }
    ],
    "nodes": [
      {
        "type": "prompt",
        "id": "n_intake",
        "instructions": "Greet the caller and ask what they're calling about.",
        "name": "Intake",
        "position": {
          "x": 120,
          "y": 80
        },
        "shared_tool_ids": [
          "tool-faq-kb"
        ]
      },
      {
        "type": "prompt",
        "id": "n_billing",
        "instructions": "Focus on billing questions. Look up the caller's latest invoice with the billing tool before answering.",
        "instructions_mode": "append",
        "model": "moonshotai/Kimi-K2.6",
        "name": "Billing",
        "position": {
          "x": 420,
          "y": 80
        },
        "shared_tool_ids": [
          "tool-billing-lookup"
        ],
        "tools_mode": "append"
      }
    ],
    "start_node_id": "n_intake"
  }
}

Response

Successful Response

idstring required
namestring required
created_atstring date-time required
version_idstring

Identifier for the assistant version returned by version-aware assistant endpoints.

version_created_atstring date-time

Timestamp when this assistant version was created.

descriptionstring
modelstring required

ID of the model to use when external_llm is not set. You can use the Get models API to see available models. If external_llm is provided, the assistant uses external_llm instead of this field. If neither model nor external_llm is provided, Telnyx applies the default model.

instructionsstring required

System instructions for the assistant. These may be templated with dynamic variables

greetingstring

Text that the assistant will use to start the conversation. This may be templated with dynamic variables. Use an empty string to have the assistant wait for the user to speak first. Use the special value <assistant-speaks-first-with-model-generated-message> to have the assistant generate the greeting based on the system instructions.

llm_api_key_refstring

This is only needed when using third-party inference providers selected by model. The identifier for an integration secret /v2/integration_secrets that refers to your LLM provider's API key. For bring-your-own endpoint authentication, use external_llm.llm_api_key_ref instead. Warning: Free plans are unlikely to work with this integration.

enabled_featuresEnabledFeatures[]
dynamic_variables_webhook_urlstring

If dynamic_variables_webhook_url is set, Telnyx sends a POST request to this URL at the start of the conversation to resolve dynamic variables. Gotcha: the webhook response must wrap variables under a top-level dynamic_variables object, e.g. {"dynamic_variables": {"customer_name": "Jane"}}. Returning a flat object will be ignored and variables will fall back to their defaults. See the dynamic variables guide for the full request/response format and timeout behavior.

dynamic_variables_webhook_timeout_msinteger

Timeout in milliseconds for the dynamic variables webhook. Must be between 1 and 10000 ms. If the webhook does not respond within this timeout, the call proceeds with default values. See the dynamic variables guide.

dynamic_variablesobject

Map of dynamic variables and their values

version_namestring

Human-readable name for the assistant version.

related_mission_idsstring[]

IDs of missions related to this assistant.

tagsstring[]

Tags associated with the assistant. Tags can also be managed with the assistant tag endpoints.

Example response

{
  "tools": [
    {
      "webhook": {
        "url": "https://example.com/api/v1/function",
        "body_parameters": {
          "properties": {
            "age": {
              "description": "The age of the customer.",
              "type": "integer"
            },
            "location": {
              "description": "The location of the customer.",
              "type": "string"
            }
          },
          "required": [
            "age",
            "location"
          ],
          "type": "object"
        },
        "path_parameters": {
          "properties": {
            "id": {
              "description": "The id of the customer.",
              "type": "string"
            }
          },
          "required": [
            "id"
          ],
          "type": "object"
        },
        "query_parameters": {
          "properties": {
            "page": {
              "description": "The page number.",
              "type": "integer"
            }
          },
          "required": [
            "page"
          ],
          "type": "object"
        },
        "preset_body_fields": {
          "account_id": "{{customer_id}}",
          "source": "telnyx-assistant"
        },
        "preset_query_params": {
          "caller": "{{telnyx_end_user_target}}",
          "channel": "voice"
        },
        "messages": [
          {
            "type": "request_start",
            "content": "Let me look that up for you."
          },
          {
            "type": "request_response_delayed",
            "content": "Still working on that.",
            "timing_ms": 5000
          }
        ]
      }
    }
  ],
  "a2a_agents": [
    {
      "name": "billing_agent",
      "url": "https://agents.example.com",
      "headers": [
        {
          "name": "X-Api-Key",
          "value": "{{#integration_secret}}my_agent_api_key{{/integration_secret}}"
        }
      ],
      "timeout_ms": 30000,
      "poll_interval_ms": 500
    }
  ],
  "avatar_settings": {
    "provider": "telnyx",
    "avatar_id": "elena",
    "background_id": "office",
    "model": "foxtrot-1"
  },
  "transcription": {
    "fallback_models": [
      {
        "model": "deepgram/nova-3",
        "language": "en"
      },
      {
        "model": "soniox/stt-rt-v5",
        "settings": {
          "context": "Telnyx,VoIP,SIP"
        }
      }
    ],
    "challenger": {
      "model": "deepgram/nova-3",
      "language": "en",
      "rule": "best_turn"
    }
  },
  "insight_settings": {
    "model": "zai-org/GLM-5.3-Flash"
  },
  "conversation_flow": {
    "edges": [
      {
        "condition": {
          "prompt": "The caller is asking about a bill or charge.",
          "type": "llm"
        },
        "id": "e_intake_to_billing",
        "start_node_id": "n_intake",
        "target": {
          "node_id": "n_billing",
          "type": "node"
        }
      },
      {
        "condition": {
          "prompt": "The caller has explicitly asked for a human.",
          "type": "llm"
        },
        "id": "e_intake_to_escalation_assistant",
        "start_node_id": "n_intake",
        "target": {
          "assistant_id": "assistant-human-handoff",
          "position": {
            "x": 600,
            "y": 80
          },
          "type": "assistant",
          "voice_mode": "distinct"
        }
      }
    ],
    "nodes": [
      {
        "type": "prompt",
        "id": "n_intake",
        "instructions": "Greet the caller and ask what they're calling about.",
        "name": "Intake",
        "position": {
          "x": 120,
          "y": 80
        },
        "shared_tool_ids": [
          "tool-faq-kb"
        ]
      },
      {
        "type": "prompt",
        "id": "n_billing",
        "instructions": "Focus on billing questions. Look up the caller's latest invoice with the billing tool before answering.",
        "instructions_mode": "append",
        "model": "moonshotai/Kimi-K2.6",
        "name": "Billing",
        "position": {
          "x": 420,
          "y": 80
        },
        "shared_tool_ids": [
          "tool-billing-lookup"
        ],
        "tools_mode": "append"
      }
    ],
    "start_node_id": "n_intake"
  }
}

Changes

  • d27fdd1cefb6Revision changes
    • info

      added the new optional request property //

    • info

      added the optional property / to the response with the status

  • 279d149de88fRevision changes
    • warning

      added the new speechmatics/linden-1 enum value to the ///// response property for the response status

    • warning

      added the new speechmatics/linden-1 enum value to the / response property for the response status

    • warning

      added the new speechmatics/standard enum value to the ///// response property for the response status

    • warning

      added the new speechmatics/standard enum value to the / response property for the response status

    • info

      added the new optional request property //////////

    • info

      added the new optional request property //////////

    • info

      added the new optional request property ///////

    • info

      added the new optional request property //////

    • info

      added the new optional request property //////

    • info

      added the new optional request property ///

    • info

      added the new speechmatics/linden-1 enum value to the request property //////

    • info

      added the new speechmatics/linden-1 enum value to the request property //

    • info

      added the new speechmatics/standard enum value to the request property //////

    • info

      added the new speechmatics/standard enum value to the request property //

    • info

      added the optional property ///////// to the response with the status

    • info

      added the optional property ///////// to the response with the status

    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property // to the response with the status