Assistants

Update an assistant

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.

post/ai/assistants/{assistant_id}

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
    }
  ],
  "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
    }
  ],
  "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

Changed in 17 of the 99 revisions of this API.1821134

  • 88a6ea09277744See the full diff
    • ●

      removed the request property /////

      request-property-removed

    • ●

      removed the optional property ///////// from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property //////// from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property //// from the response with the status

      response-optional-property-removed

    • ○

      added the new optional request property ////

      new-optional-request-property

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      new-optional-request-property

    • ○

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

      new-optional-request-property

    • ○

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

      new-optional-request-property

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

  • 1581f4d4456622See the full diff
    • ●

      added the new omi-health/omi-med-stt-v1 enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new omi-health/omi-med-stt-v1 enum value to the / response property for the response status

      response-property-enum-value-added

    • ○

      added the new omi-health/omi-med-stt-v1 enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new omi-health/omi-med-stt-v1 enum value to the request property //

      request-property-enum-value-added

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 4 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4596ec306e5922See the full diff
    • ●

      added the new assemblyai/universal-3-5-pro enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new assemblyai/universal-3-5-pro enum value to the / response property for the response status

      response-property-enum-value-added

    • ○

      added the new assemblyai/universal-3-5-pro enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new assemblyai/universal-3-5-pro enum value to the request property //

      request-property-enum-value-added

  • c44ea87f727b440See the full diff
    • ▲

      removed from the // request property oneOf list

      request-property-one-of-removed

    • ▲

      added to the ////// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added to the ///// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added to the / response property oneOf list for the response status

      response-property-one-of-added

    • ○

      added to the // request property oneOf list

      request-property-one-of-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

      removed from the ////// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed from the ///// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed from the / response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • a6a61a29ecdd549See the full diff
    • ●

      added the new aicoustics enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new cohere/ar-stt enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new cohere/ar-stt enum value to the / response property for the response status

      response-property-enum-value-added

    • ●

      added the new soniox/stt-rt-v5 enum value to the ///// response property for the response status

      response-property-enum-value-added

    • ●

      added the new soniox/stt-rt-v5 enum value to the / response property for the response status

      response-property-enum-value-added

    • ○

      added the new optional request property /

      new-optional-request-property

    • ○

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

      new-optional-request-property

    • ○

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

      new-optional-request-property

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the new optional request property /////

      new-optional-request-property

    • ○

      added the new optional request property /////

      new-optional-request-property

    • ○

      added the new optional request property /////

      new-optional-request-property

    • ○

      added the new optional request property /////

      new-optional-request-property

    • ○

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

      new-optional-request-property

    • ○

      added the new optional request property /////

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new optional request property ///

      new-optional-request-property

    • ○

      added the new aicoustics enum value to the request property //

      request-property-enum-value-added

    • ○

      added the new cohere/ar-stt enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new cohere/ar-stt enum value to the request property //

      request-property-enum-value-added

    • ○

      added the new soniox/stt-rt-v5 enum value to the request property //////

      request-property-enum-value-added

    • ○

      added the new soniox/stt-rt-v5 enum value to the request property //

      request-property-enum-value-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    • ○

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

      response-optional-property-added

    This revision also has 34 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

    • ▲

      added to the ////// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added to the ///// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added to the / response property oneOf list for the response status

      response-property-one-of-added

    • ○

      added to the // request property oneOf list

      request-property-one-of-added

Of the 99 revisions, 1 has no diff computed.