telnyx 5.170.0 → 5.171.0

data/rbi/telnyx/models/ai/avatar_settings_request.rbi

@@ -0,0 +1,186 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    module AI
+      class AvatarSettingsRequest < Telnyx::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(Telnyx::AI::AvatarSettingsRequest, Telnyx::Internal::AnyHash)
+          end
+
+        # The Telnyx avatar to render.
+        sig { returns(Telnyx::AI::AvatarSettingsRequest::AvatarID::OrSymbol) }
+        attr_accessor :avatar_id
+
+        # The background to render.
+        sig do
+          returns(Telnyx::AI::AvatarSettingsRequest::BackgroundID::OrSymbol)
+        end
+        attr_accessor :background_id
+
+        # Required avatar model identifier, separate from `avatar_id`. The supported value
+        # is `foxtrot-1`. Omission, null, and unsupported model identifiers are rejected.
+        sig { returns(Telnyx::AI::AvatarSettingsRequest::Model::OrSymbol) }
+        attr_accessor :model
+
+        # Selects the Telnyx open-source avatar provider.
+        sig { returns(Symbol) }
+        attr_accessor :provider
+
+        # **Beta:** Configuration for the Telnyx open-source avatar provider. The launch
+        # catalog supports six avatars and office, studio, or reception backgrounds.
+        sig do
+          params(
+            avatar_id: Telnyx::AI::AvatarSettingsRequest::AvatarID::OrSymbol,
+            background_id:
+              Telnyx::AI::AvatarSettingsRequest::BackgroundID::OrSymbol,
+            model: Telnyx::AI::AvatarSettingsRequest::Model::OrSymbol,
+            provider: Symbol
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The Telnyx avatar to render.
+          avatar_id:,
+          # The background to render.
+          background_id:,
+          # Required avatar model identifier, separate from `avatar_id`. The supported value
+          # is `foxtrot-1`. Omission, null, and unsupported model identifiers are rejected.
+          model:,
+          # Selects the Telnyx open-source avatar provider.
+          provider: :telnyx
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              avatar_id: Telnyx::AI::AvatarSettingsRequest::AvatarID::OrSymbol,
+              background_id:
+                Telnyx::AI::AvatarSettingsRequest::BackgroundID::OrSymbol,
+              model: Telnyx::AI::AvatarSettingsRequest::Model::OrSymbol,
+              provider: Symbol
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # The Telnyx avatar to render.
+        module AvatarID
+          extend Telnyx::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Telnyx::AI::AvatarSettingsRequest::AvatarID)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          ELENA =
+            T.let(
+              :elena,
+              Telnyx::AI::AvatarSettingsRequest::AvatarID::TaggedSymbol
+            )
+          BEN =
+            T.let(
+              :ben,
+              Telnyx::AI::AvatarSettingsRequest::AvatarID::TaggedSymbol
+            )
+          JORDAN =
+            T.let(
+              :jordan,
+              Telnyx::AI::AvatarSettingsRequest::AvatarID::TaggedSymbol
+            )
+          LIN =
+            T.let(
+              :lin,
+              Telnyx::AI::AvatarSettingsRequest::AvatarID::TaggedSymbol
+            )
+          AVERY =
+            T.let(
+              :avery,
+              Telnyx::AI::AvatarSettingsRequest::AvatarID::TaggedSymbol
+            )
+          RAPHAEL =
+            T.let(
+              :raphael,
+              Telnyx::AI::AvatarSettingsRequest::AvatarID::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Telnyx::AI::AvatarSettingsRequest::AvatarID::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+
+        # The background to render.
+        module BackgroundID
+          extend Telnyx::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Telnyx::AI::AvatarSettingsRequest::BackgroundID)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          OFFICE =
+            T.let(
+              :office,
+              Telnyx::AI::AvatarSettingsRequest::BackgroundID::TaggedSymbol
+            )
+          STUDIO =
+            T.let(
+              :studio,
+              Telnyx::AI::AvatarSettingsRequest::BackgroundID::TaggedSymbol
+            )
+          RECEPTION =
+            T.let(
+              :reception,
+              Telnyx::AI::AvatarSettingsRequest::BackgroundID::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Telnyx::AI::AvatarSettingsRequest::BackgroundID::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+
+        # Required avatar model identifier, separate from `avatar_id`. The supported value
+        # is `foxtrot-1`. Omission, null, and unsupported model identifiers are rejected.
+        module Model
+          extend Telnyx::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, Telnyx::AI::AvatarSettingsRequest::Model)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          FOXTROT_1 =
+            T.let(
+              :"foxtrot-1",
+              Telnyx::AI::AvatarSettingsRequest::Model::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[Telnyx::AI::AvatarSettingsRequest::Model::TaggedSymbol]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/models/ai/chat_completion_request.rbi

@@ -72,12 +72,28 @@ module Telnyx
         sig { params(logprobs: T::Boolean).void }
         attr_writer :logprobs
 
-        # Maximum number of completion tokens the model should generate.
+        # Maximum number of completion (output) tokens, including reasoning and answer
+        # tokens combined. An omitted or null limit defaults to 8192 unless the model is
+        # excluded from that default; excluded models leave the limit to the serving
+        # engine. Explicit values and applied defaults are clamped to the model's
+        # max_completion_tokens metadata when that ceiling is set (see GET
+        # /v2/ai/openai/models). An omitted limit on an excluded model remains unset even
+        # when metadata declares a ceiling. Input and output together must fit the model's
+        # context window. Set an explicit limit when a bounded generation budget is
+        # required. For current Telnyx-hosted models, omitted or null limits default to
+        # 8192 for `zai-org/GLM-5.3`, `zai-org/GLM-5.3-Flash` and
+        # `deepseek-ai/DeepSeek-V4.1-Flash`. The hosted exclusions are
+        # `moonshotai/Kimi-K3`, `moonshotai/Kimi-K2.6`, `moonshotai/Kimi-K2.5`,
+        # `zai-org/GLM-5.2`, `zai-org/GLM-5.1-FP8`, `MiniMaxAI/MiniMax-M3-MXFP8`,
+        # `MiniMaxAI/MiniMax-M2.7`, `Qwen/Qwen3.8-27B`, `Qwen/Qwen3-235B-A22B`,
+        # `deepseek-ai/DeepSeek-V4-Flash-0731`, `meta-llama/Llama-3.3-70B-Instruct`,
+        # `meta-llama/Meta-Llama-3.1-70B-Instruct`,
+        # `meta-llama/Meta-Llama-3.1-8B-Instruct` and `google/gemma-2b-it`. Legacy
+        # external and fine-tuned model IDs can also bypass the default; model discovery
+        # reports completion ceilings, not whether this default applies. Set an explicit
+        # limit for predictable behavior across models.
         sig { returns(T.nilable(Integer)) }
-        attr_reader :max_tokens
-
-        sig { params(max_tokens: Integer).void }
-        attr_writer :max_tokens
+        attr_accessor :max_tokens
 
         # This is an alternative to `top_p` that
         # [many prefer](https://github.com/huggingface/transformers/issues/27670). Must be
@@ -323,7 +339,7 @@ module Telnyx
             frequency_penalty: Float,
             length_penalty: Float,
             logprobs: T::Boolean,
-            max_tokens: Integer,
+            max_tokens: T.nilable(Integer),
             min_p: Float,
             mode: Telnyx::AI::ChatCompletionRequest::Mode::OrSymbol,
             model: String,
@@ -384,7 +400,26 @@ module Telnyx
           # returns the log probabilities of each output token returned in the `content` of
           # `message`.
           logprobs: nil,
-          # Maximum number of completion tokens the model should generate.
+          # Maximum number of completion (output) tokens, including reasoning and answer
+          # tokens combined. An omitted or null limit defaults to 8192 unless the model is
+          # excluded from that default; excluded models leave the limit to the serving
+          # engine. Explicit values and applied defaults are clamped to the model's
+          # max_completion_tokens metadata when that ceiling is set (see GET
+          # /v2/ai/openai/models). An omitted limit on an excluded model remains unset even
+          # when metadata declares a ceiling. Input and output together must fit the model's
+          # context window. Set an explicit limit when a bounded generation budget is
+          # required. For current Telnyx-hosted models, omitted or null limits default to
+          # 8192 for `zai-org/GLM-5.3`, `zai-org/GLM-5.3-Flash` and
+          # `deepseek-ai/DeepSeek-V4.1-Flash`. The hosted exclusions are
+          # `moonshotai/Kimi-K3`, `moonshotai/Kimi-K2.6`, `moonshotai/Kimi-K2.5`,
+          # `zai-org/GLM-5.2`, `zai-org/GLM-5.1-FP8`, `MiniMaxAI/MiniMax-M3-MXFP8`,
+          # `MiniMaxAI/MiniMax-M2.7`, `Qwen/Qwen3.8-27B`, `Qwen/Qwen3-235B-A22B`,
+          # `deepseek-ai/DeepSeek-V4-Flash-0731`, `meta-llama/Llama-3.3-70B-Instruct`,
+          # `meta-llama/Meta-Llama-3.1-70B-Instruct`,
+          # `meta-llama/Meta-Llama-3.1-8B-Instruct` and `google/gemma-2b-it`. Legacy
+          # external and fine-tuned model IDs can also bypass the default; model discovery
+          # reports completion ceilings, not whether this default applies. Set an explicit
+          # limit for predictable behavior across models.
           max_tokens: nil,
           # This is an alternative to `top_p` that
           # [many prefer](https://github.com/huggingface/transformers/issues/27670). Must be
@@ -468,7 +503,7 @@ module Telnyx
               frequency_penalty: Float,
               length_penalty: Float,
               logprobs: T::Boolean,
-              max_tokens: Integer,
+              max_tokens: T.nilable(Integer),
               min_p: Float,
               mode: Telnyx::AI::ChatCompletionRequest::Mode::OrSymbol,
               model: String,

data/rbi/telnyx/models/ai/conversation_flow_req.rbi

@@ -10,7 +10,7 @@ module Telnyx
           end
 
         # All nodes in the flow. Must contain `start_node_id`. Each node is a prompt node
-        # (`type: prompt`) or a tool node (`type: tool`).
+        # (`type: prompt`), a tool node (`type: tool`), or a speak node (`type: speak`).
         sig do
           returns(
             T::Array[
@@ -56,7 +56,7 @@ module Telnyx
         end
         def self.new(
           # All nodes in the flow. Must contain `start_node_id`. Each node is a prompt node
-          # (`type: prompt`) or a tool node (`type: tool`).
+          # (`type: prompt`), a tool node (`type: tool`), or a speak node (`type: speak`).
           nodes:,
           # ID of the node where the conversation begins.
           start_node_id:,

data/rbi/telnyx/models/ai/conversation_list_params.rbi

@@ -47,6 +47,17 @@ module Telnyx
         sig { params(metadata_assistant_id: String).void }
         attr_writer :metadata_assistant_id
 
+        # Filter by assistant version ID (e.g.,
+        # `metadata->assistant_version_id=eq.20250812T114318034399`). The version that
+        # handled the conversation is stored in metadata when the conversation starts;
+        # conversations created before this field was tracked, or that never resolved a
+        # version, have no `assistant_version_id` and do not match this filter.
+        sig { returns(T.nilable(String)) }
+        attr_reader :metadata_assistant_version_id
+
+        sig { params(metadata_assistant_version_id: String).void }
+        attr_writer :metadata_assistant_version_id
+
         # Filter by call control ID (e.g., `metadata->call_control_id=eq.v3:123`)
         sig { returns(T.nilable(String)) }
         attr_reader :metadata_call_control_id
@@ -108,6 +119,7 @@ module Telnyx
             last_message_at: String,
             limit: Integer,
             metadata_assistant_id: String,
+            metadata_assistant_version_id: String,
             metadata_call_control_id: String,
             metadata_telnyx_agent_target: String,
             metadata_telnyx_conversation_channel: String,
@@ -129,6 +141,12 @@ module Telnyx
           limit: nil,
           # Filter by assistant ID (e.g., `metadata->assistant_id=eq.assistant-123`)
           metadata_assistant_id: nil,
+          # Filter by assistant version ID (e.g.,
+          # `metadata->assistant_version_id=eq.20250812T114318034399`). The version that
+          # handled the conversation is stored in metadata when the conversation starts;
+          # conversations created before this field was tracked, or that never resolved a
+          # version, have no `assistant_version_id` and do not match this filter.
+          metadata_assistant_version_id: nil,
           # Filter by call control ID (e.g., `metadata->call_control_id=eq.v3:123`)
           metadata_call_control_id: nil,
           # Filter by the phone number, SIP URI, or other identifier for the agent (e.g.,
@@ -160,6 +178,7 @@ module Telnyx
               last_message_at: String,
               limit: Integer,
               metadata_assistant_id: String,
+              metadata_assistant_version_id: String,
               metadata_call_control_id: String,
               metadata_telnyx_agent_target: String,
               metadata_telnyx_conversation_channel: String,

data/rbi/telnyx/models/ai/delegation_settings.rbi

@@ -0,0 +1,190 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    module AI
+      class DelegationSettings < Telnyx::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(Telnyx::AI::DelegationSettings, Telnyx::Internal::AnyHash)
+          end
+
+        # Whether the assistant delegates work to a backend model. Defaults to `true`: a
+        # GPT-Live assistant with delegation disabled can hold a conversation but can
+        # never look anything up or run a tool.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :enabled
+
+        sig { params(enabled: T::Boolean).void }
+        attr_writer :enabled
+
+        # Run the backend on your own OpenAI-compatible endpoint instead of a
+        # Telnyx-hosted model. As above, a raw `api_key` here is rejected — reference an
+        # integration secret with `external_llm.llm_api_key_ref` instead.
+        sig { returns(T.nilable(Telnyx::AI::ExternalLlm)) }
+        attr_reader :external_llm
+
+        sig { params(external_llm: Telnyx::AI::ExternalLlm::OrHash).void }
+        attr_writer :external_llm
+
+        # Extra instructions for the backend model, in addition to the assistant's own.
+        # Use this for the business rules the backend needs and the talking model does
+        # not.
+        sig { returns(T.nilable(String)) }
+        attr_reader :instructions
+
+        sig { params(instructions: String).void }
+        attr_writer :instructions
+
+        # Integration secret identifier for the backend model's API key. Required for
+        # models from providers other than Telnyx, OpenAI and Anthropic. A raw `api_key`
+        # is rejected rather than ignored, so that no plaintext credential is stored on
+        # the assistant.
+        sig { returns(T.nilable(String)) }
+        attr_reader :llm_api_key_ref
+
+        sig { params(llm_api_key_ref: String).void }
+        attr_writer :llm_api_key_ref
+
+        # Who answers a delegation. `telnyx` runs the backend model on Telnyx with the
+        # assistant's own tools, MCP servers and observability. `client` relays the
+        # delegation to a server you host over the WebSocket configured in
+        # `websocket_settings`: Telnyx sends a `session.delegation.created` frame and
+        # waits for your `session.delegation.completed` answer. That answer is text only,
+        # since the socket offers no tool vocabulary. If no socket is connected the
+        # delegation is refused and the assistant tells the caller it cannot look things
+        # up right now. Defaults to `telnyx`.
+        sig do
+          returns(T.nilable(Telnyx::AI::DelegationSettings::Mode::OrSymbol))
+        end
+        attr_reader :mode
+
+        sig do
+          params(mode: Telnyx::AI::DelegationSettings::Mode::OrSymbol).void
+        end
+        attr_writer :mode
+
+        # The backend model that answers delegations. Must be a model available for AI
+        # Assistants. When enabling `telnyx` delegation, explicitly set this field or
+        # `external_llm.model`; a configuration without either backend model is rejected.
+        # Only applies when `mode` is `telnyx`.
+        sig { returns(T.nilable(String)) }
+        attr_reader :model
+
+        sig { params(model: String).void }
+        attr_writer :model
+
+        # Whether the backend's answer is spoken to the caller. When `true` the result is
+        # appended as commentary and paraphrased aloud; when `false` it is kept as silent
+        # context that informs later answers without being read out. Defaults to `true`.
+        sig { returns(T.nilable(T::Boolean)) }
+        attr_reader :speak_results
+
+        sig { params(speak_results: T::Boolean).void }
+        attr_writer :speak_results
+
+        # Splits the conversation between a frontend model that talks to the caller and a
+        # backend model that does the work. On the GPT-Live route the frontend model
+        # cannot call tools at all — when it needs something done it raises a delegation
+        # and waits. On the chat completion route the frontend keeps a single `delegate`
+        # tool that returns immediately, so the conversation carries on while the backend
+        # works. Either way the backend's answer is spoken as commentary or kept as silent
+        # context, depending on `speak_results`. Beta feature.
+        sig do
+          params(
+            enabled: T::Boolean,
+            external_llm: Telnyx::AI::ExternalLlm::OrHash,
+            instructions: String,
+            llm_api_key_ref: String,
+            mode: Telnyx::AI::DelegationSettings::Mode::OrSymbol,
+            model: String,
+            speak_results: T::Boolean
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Whether the assistant delegates work to a backend model. Defaults to `true`: a
+          # GPT-Live assistant with delegation disabled can hold a conversation but can
+          # never look anything up or run a tool.
+          enabled: nil,
+          # Run the backend on your own OpenAI-compatible endpoint instead of a
+          # Telnyx-hosted model. As above, a raw `api_key` here is rejected — reference an
+          # integration secret with `external_llm.llm_api_key_ref` instead.
+          external_llm: nil,
+          # Extra instructions for the backend model, in addition to the assistant's own.
+          # Use this for the business rules the backend needs and the talking model does
+          # not.
+          instructions: nil,
+          # Integration secret identifier for the backend model's API key. Required for
+          # models from providers other than Telnyx, OpenAI and Anthropic. A raw `api_key`
+          # is rejected rather than ignored, so that no plaintext credential is stored on
+          # the assistant.
+          llm_api_key_ref: nil,
+          # Who answers a delegation. `telnyx` runs the backend model on Telnyx with the
+          # assistant's own tools, MCP servers and observability. `client` relays the
+          # delegation to a server you host over the WebSocket configured in
+          # `websocket_settings`: Telnyx sends a `session.delegation.created` frame and
+          # waits for your `session.delegation.completed` answer. That answer is text only,
+          # since the socket offers no tool vocabulary. If no socket is connected the
+          # delegation is refused and the assistant tells the caller it cannot look things
+          # up right now. Defaults to `telnyx`.
+          mode: nil,
+          # The backend model that answers delegations. Must be a model available for AI
+          # Assistants. When enabling `telnyx` delegation, explicitly set this field or
+          # `external_llm.model`; a configuration without either backend model is rejected.
+          # Only applies when `mode` is `telnyx`.
+          model: nil,
+          # Whether the backend's answer is spoken to the caller. When `true` the result is
+          # appended as commentary and paraphrased aloud; when `false` it is kept as silent
+          # context that informs later answers without being read out. Defaults to `true`.
+          speak_results: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              enabled: T::Boolean,
+              external_llm: Telnyx::AI::ExternalLlm,
+              instructions: String,
+              llm_api_key_ref: String,
+              mode: Telnyx::AI::DelegationSettings::Mode::OrSymbol,
+              model: String,
+              speak_results: T::Boolean
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # Who answers a delegation. `telnyx` runs the backend model on Telnyx with the
+        # assistant's own tools, MCP servers and observability. `client` relays the
+        # delegation to a server you host over the WebSocket configured in
+        # `websocket_settings`: Telnyx sends a `session.delegation.created` frame and
+        # waits for your `session.delegation.completed` answer. That answer is text only,
+        # since the socket offers no tool vocabulary. If no socket is connected the
+        # delegation is refused and the assistant tells the caller it cannot look things
+        # up right now. Defaults to `telnyx`.
+        module Mode
+          extend Telnyx::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias { T.all(Symbol, Telnyx::AI::DelegationSettings::Mode) }
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          TELNYX =
+            T.let(:telnyx, Telnyx::AI::DelegationSettings::Mode::TaggedSymbol)
+          CLIENT =
+            T.let(:client, Telnyx::AI::DelegationSettings::Mode::TaggedSymbol)
+
+          sig do
+            override.returns(
+              T::Array[Telnyx::AI::DelegationSettings::Mode::TaggedSymbol]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/models/ai/external_llm.rbi

@@ -18,9 +18,7 @@ module Telnyx
         attr_accessor :model
 
         # Authentication method used when connecting to the external LLM endpoint.
-        sig do
-          returns(T.nilable(Telnyx::AI::AuthenticationMethod::TaggedSymbol))
-        end
+        sig { returns(T.nilable(Telnyx::AI::AuthenticationMethod::OrSymbol)) }
         attr_reader :authentication_method
 
         sig do
@@ -106,8 +104,7 @@ module Telnyx
             {
               base_url: String,
               model: String,
-              authentication_method:
-                Telnyx::AI::AuthenticationMethod::TaggedSymbol,
+              authentication_method: Telnyx::AI::AuthenticationMethod::OrSymbol,
               certificate_ref: String,
               forward_metadata: T::Boolean,
               llm_api_key_ref: String,

data/rbi/telnyx/models/ai/flow_edge.rbi

@@ -45,9 +45,14 @@ module Telnyx
         # Directed transition from one node to a target, gated by a condition.
         #
         # The target is either another node in the same flow (`NodeTarget`) or a different
-        # assistant (`AssistantTarget`). Multiple edges may share a `start_node_id`; the
-        # runtime evaluates them in the order they're declared and takes the first whose
-        # condition is true.
+        # assistant (`AssistantTarget`). Multiple edges may share a `start_node_id`. On
+        # calls, `expression` conditions are evaluated before the model turn and take
+        # precedence over `llm` conditions regardless of declaration order, while `llm`
+        # conditions are offered to the assistant's model as transition tools and fire
+        # when the model selects one. On chat channels, an `expression` condition that is
+        # true when the turn begins routes before the reply is generated; all conditioned
+        # edges that remain are considered together in declaration order after the reply,
+        # and the first true one wins.
         sig do
           params(
             id: String,
@@ -124,23 +129,32 @@ module Telnyx
                 )
               end
 
-            # Natural-language criterion the LLM judges as true/false.
+            # Natural-language criterion the model routes on. On calls this is offered to the
+            # model as the transition tool's description; on chat channels it is judged as a
+            # statement in the post-reply evaluation call.
             sig { returns(String) }
             attr_accessor :prompt
 
             sig { returns(Symbol) }
             attr_accessor :type
 
-            # Edge condition evaluated by the LLM from a natural-language prompt.
+            # Edge condition routed by the assistant's LLM from a natural-language prompt.
             #
-            # The model is asked to judge the prompt against conversation context and returns
-            # true/false. Use this for fuzzy intents that aren't expressible as a
-            # deterministic expression (e.g. 'user wants to escalate to a human').
+            # How the edge is decided depends on the channel. On calls, each outgoing `llm`
+            # condition is offered to the assistant's model as a transition tool alongside the
+            # assistant's tools, and the edge fires when the model selects it; the platform
+            # does not evaluate the prompt itself, and instructions that forbid or discourage
+            # tool calls can stop these edges from firing. On chat channels, the edge prompts
+            # are evaluated in a separate model call after the reply, which does not use the
+            # assistant's instructions. Use this for fuzzy intents that aren't expressible as
+            # a deterministic expression (e.g. 'user wants to escalate to a human').
             sig do
               params(prompt: String, type: Symbol).returns(T.attached_class)
             end
             def self.new(
-              # Natural-language criterion the LLM judges as true/false.
+              # Natural-language criterion the model routes on. On calls this is offered to the
+              # model as the transition tool's description; on chat channels it is judged as a
+              # statement in the post-reply evaluation call.
               prompt:,
               type: :llm
             )

data/rbi/telnyx/models/ai/flow_node_req.rbi

@@ -101,7 +101,11 @@ module Telnyx
         attr_writer :tools_mode
 
         # Per-node transcription override (model/language/region). Unset fields cascade
-        # from the assistant-level transcription.
+        # from the assistant-level transcription. A node that sets `model`,
+        # `fallback_models`, or `challenger` doesn't inherit the assistant's
+        # `fallback_models` or `challenger`; it uses only the ones it sets. Otherwise it
+        # inherits them, and they must fit the model and language the node runs; a change
+        # they no longer fit is rejected.
         sig { returns(T.nilable(Telnyx::AI::TranscriptionSettings)) }
         attr_reader :transcription
 
@@ -111,7 +115,8 @@ module Telnyx
         attr_writer :transcription
 
         # Node kind discriminator. `prompt` (default) is an LLM-driven step; `tool` is a
-        # standalone tool execution (see `ToolNodeReq`).
+        # standalone tool execution and `speak` a scripted message (see `ToolNodeReq` /
+        # `SpeakNodeReq`).
         sig { returns(T.nilable(Telnyx::AI::FlowNodeReq::Type::OrSymbol)) }
         attr_reader :type
 
@@ -190,10 +195,15 @@ module Telnyx
           # added to the assistant's tools. Ignored when `shared_tool_ids` is null.
           tools_mode: nil,
           # Per-node transcription override (model/language/region). Unset fields cascade
-          # from the assistant-level transcription.
+          # from the assistant-level transcription. A node that sets `model`,
+          # `fallback_models`, or `challenger` doesn't inherit the assistant's
+          # `fallback_models` or `challenger`; it uses only the ones it sets. Otherwise it
+          # inherits them, and they must fit the model and language the node runs; a change
+          # they no longer fit is rejected.
           transcription: nil,
           # Node kind discriminator. `prompt` (default) is an LLM-driven step; `tool` is a
-          # standalone tool execution (see `ToolNodeReq`).
+          # standalone tool execution and `speak` a scripted message (see `ToolNodeReq` /
+          # `SpeakNodeReq`).
           type: nil,
           # Per-node voice override. Only fields set here override the assistant-level voice
           # settings; unset fields cascade.
@@ -281,7 +291,8 @@ module Telnyx
         end
 
         # Node kind discriminator. `prompt` (default) is an LLM-driven step; `tool` is a
-        # standalone tool execution (see `ToolNodeReq`).
+        # standalone tool execution and `speak` a scripted message (see `ToolNodeReq` /
+        # `SpeakNodeReq`).
         module Type
           extend Telnyx::Internal::Type::Enum