Sign in
Assistants

Clone Assistant

Clone an existing assistant, excluding telephony and messaging settings.

post/ai/assistants/{assistant_id}/clone

Path parameters

assistant_idstring required

Unique identifier of the assistant.

Headers

Idempotency-Keystring

Optional opaque, unquoted key for safely retrying the same logical request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores. Generate a unique UUID v4 for each operation and reuse it only when retrying that operation with the same request. Invalid headers—including duplicate, empty, malformed, or overlong values—return 400 with error code 10015. A request already in progress with the same key returns 409; reusing the key with a different request returns 422. Only successful responses are replayed, for up to 24 hours. Do not include sensitive data in the key.

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