Assistants

Create an assistant

Creates a new AI assistant from the provided configuration, including its model, instructions, and attached tools, and returns the created assistant.

post/ai/assistants

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.

Request body

namestring required
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 required

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.

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.

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 18 of the 99 revisions of this API.1924139

  • 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

    • ●

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

      response-property-enum-value-added

    • ●

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

      response-property-enum-value-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 optional property / to the response with the status

      response-optional-property-added

  • a6a61a29ecdd1655See the full diff
    • ▲

      the response's body type changed from object to no type for status

      response-body-type-changed

    • ●

      removed the optional property from the response with the status

      response-optional-property-removed

    • ●

      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 header request parameter Idempotency-Key

      new-optional-request-parameter

    • ○

      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 to the response body anyOf list for the response status

      response-body-any-of-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      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

    • ○

      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

Of the 99 revisions, 1 has no diff computed.