Sign in
Assistants

Create an assistant

Create a new AI Assistant.

post/ai/assistants

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"
        }
      }
    }
  ],
  "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"
        }
      }
    }
  ],
  "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 15 of the 47 revisions of this API.22895

  • 8a8c40f458c588See the full diff
    • ▲

      removed subschema #1: targets_list from the //// request property oneOf list

      request-property-one-of-removed

    • ▲

      removed subschema #1: targets_list from the //// request property oneOf list

      request-property-one-of-removed

    • ▲

      added subschema #1 to the ///////// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1 to the ///////// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1 to the //////// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1 to the //////// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1 to the //// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1 to the //// response property oneOf list for the response status

      response-property-one-of-added

    • ○

      added subschema #1 to the //// request property oneOf list

      request-property-one-of-added

    • ○

      added subschema #1 to the //// request property oneOf list

      request-property-one-of-added

    • ○

      removed subschema #1: targets_list from the ///////// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1: targets_list from the ///////// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1: targets_list from the //////// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1: targets_list from the //////// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1: targets_list from the //// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1: targets_list from the //// response property oneOf list for the response status

      response-property-one-of-removed

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

  • 3f3befefc60726See the full diff
    • ▲

      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 default discriminator mapping keys to the /// request property

      request-property-discriminator-mapping-added

    • ○

      added speak discriminator mapping keys to the // request property

      request-property-discriminator-mapping-added

    • ○

      added to the /// request property oneOf list

      request-property-one-of-added

    • ○

      added to the // request property oneOf list

      request-property-one-of-added

    • ○

      added default discriminator mapping keys to the /// response property for the response status

      response-property-discriminator-mapping-added

    • ○

      added speak discriminator mapping keys to the // response property for the response status

      response-property-discriminator-mapping-added

  • 8a56feba71904See the full diff
    • ○

      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

  • 3390803c3bb02See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property to the response with the status

      response-optional-property-added

  • ac6be9fa50c12See the full diff
    • ○

      added the new optional request property //

      new-optional-request-property

    • ○

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

      response-optional-property-added

  • 157ea860b82e2See the full diff
    • ○

      added the new optional request property ////

      new-optional-request-property

    • ○

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

      response-optional-property-added

  • c260e29f149619See the full diff
    • ●

      added the new soniox/stt-rt-v4 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 soniox/stt-rt-v4 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

  • 50870cc0561444See the full diff
    • ▲

      removed subschema #1 from the //// request property oneOf list

      request-property-one-of-removed

    • ▲

      removed subschema #1 from the //// request property oneOf list

      request-property-one-of-removed

    • ▲

      added subschema #1: targets_list to the //// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1: targets_list to the //// response property oneOf list for the response status

      response-property-one-of-added

    • ○

      added subschema #1: targets_list to the //// request property oneOf list

      request-property-one-of-added

    • ○

      added subschema #1: targets_list to the //// request property oneOf list

      request-property-one-of-added

    • ○

      removed subschema #1 from the //// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1 from the //// response property oneOf list for the response status

      response-property-one-of-removed

  • a144ff96b4ac44See the full diff
    • ▲

      removed subschema #1: targets_list from the //// request property oneOf list

      request-property-one-of-removed

    • ▲

      removed subschema #1: targets_list from the //// request property oneOf list

      request-property-one-of-removed

    • ▲

      added subschema #1 to the //// response property oneOf list for the response status

      response-property-one-of-added

    • ▲

      added subschema #1 to the //// response property oneOf list for the response status

      response-property-one-of-added

    • ○

      added subschema #1 to the //// request property oneOf list

      request-property-one-of-added

    • ○

      added subschema #1 to the //// request property oneOf list

      request-property-one-of-added

    • ○

      removed subschema #1: targets_list from the //// response property oneOf list for the response status

      response-property-one-of-removed

    • ○

      removed subschema #1: targets_list from the //// response property oneOf list for the response status

      response-property-one-of-removed

  • 24057b25c3f52See the full diff
    • ○

      the request property default value changed from 0.4 to 0.8

      request-property-default-value-changed

    • ○

      the response's property default value changed from 0.4 to 0.8 for the status

      response-property-default-value-changed