telnyx 5.70.0 → 5.71.0

data/rbi/telnyx/models/call_assistant_request.rbi

@@ -0,0 +1,322 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    class CallAssistantRequest < Telnyx::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Telnyx::CallAssistantRequest, Telnyx::Internal::AnyHash)
+        end
+
+      # The identifier of the AI assistant to use.
+      sig { returns(String) }
+      attr_accessor :id
+
+      # Map of dynamic variables and their default values. Dynamic variables can be
+      # referenced in instructions, greeting, and tool definitions using the
+      # `{{variable_name}}` syntax. Call-control-agent automatically merges in
+      # `telnyx_call_*` variables (telnyx_call_to, telnyx_call_from,
+      # telnyx_conversation_channel, telnyx_agent_target, telnyx_end_user_target,
+      # telnyx_call_caller_id_name) and custom header variables.
+      sig do
+        returns(
+          T.nilable(
+            T::Hash[
+              Symbol,
+              Telnyx::CallAssistantRequest::DynamicVariable::Variants
+            ]
+          )
+        )
+      end
+      attr_reader :dynamic_variables
+
+      sig do
+        params(
+          dynamic_variables:
+            T::Hash[
+              Symbol,
+              Telnyx::CallAssistantRequest::DynamicVariable::Variants
+            ]
+        ).void
+      end
+      attr_writer :dynamic_variables
+
+      # External LLM configuration for bringing your own LLM endpoint.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :external_llm
+
+      sig { params(external_llm: T::Hash[Symbol, T.anything]).void }
+      attr_writer :external_llm
+
+      # Fallback LLM configuration used when the primary LLM provider is unavailable.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :fallback_config
+
+      sig { params(fallback_config: T::Hash[Symbol, T.anything]).void }
+      attr_writer :fallback_config
+
+      # Initial greeting text spoken when the assistant starts. Can be plain text for
+      # any voice or SSML for `AWS.Polly.<voice_id>` voices. There is a 3,000 character
+      # limit.
+      sig { returns(T.nilable(String)) }
+      attr_reader :greeting
+
+      sig { params(greeting: String).void }
+      attr_writer :greeting
+
+      # System instructions for the voice assistant. Can be templated with
+      # [dynamic variables](https://developers.telnyx.com/docs/inference/ai-assistants/dynamic-variables).
+      # This will overwrite the instructions set in the assistant configuration.
+      sig { returns(T.nilable(String)) }
+      attr_reader :instructions
+
+      sig { params(instructions: String).void }
+      attr_writer :instructions
+
+      # Integration secret identifier for the LLM provider API key. Use this field to
+      # reference an
+      # [integration secret](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret)
+      # containing your LLM provider API key. Supports any LLM provider (OpenAI,
+      # Anthropic, etc.).
+      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
+
+      # MCP (Model Context Protocol) server configurations for extending the assistant's
+      # capabilities with external tools and data sources.
+      sig { returns(T.nilable(T::Array[T::Hash[Symbol, T.anything]])) }
+      attr_reader :mcp_servers
+
+      sig { params(mcp_servers: T::Array[T::Hash[Symbol, T.anything]]).void }
+      attr_writer :mcp_servers
+
+      # LLM model override for this call. If omitted, the assistant's configured model
+      # is used.
+      sig { returns(T.nilable(String)) }
+      attr_reader :model
+
+      sig { params(model: String).void }
+      attr_writer :model
+
+      # Assistant name override for this call.
+      sig { returns(T.nilable(String)) }
+      attr_reader :name
+
+      sig { params(name: String).void }
+      attr_writer :name
+
+      # Observability configuration for the assistant session, including Langfuse
+      # integration for tracing and monitoring.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :observability_settings
+
+      sig { params(observability_settings: T::Hash[Symbol, T.anything]).void }
+      attr_writer :observability_settings
+
+      # Deprecated — use `llm_api_key_ref` instead. Integration secret identifier for
+      # the OpenAI API key. This field is maintained for backward compatibility;
+      # `llm_api_key_ref` is the canonical field name and supports all LLM providers.
+      sig { returns(T.nilable(String)) }
+      attr_reader :openai_api_key_ref
+
+      sig { params(openai_api_key_ref: String).void }
+      attr_writer :openai_api_key_ref
+
+      # Inline tool definitions available to the assistant (webhook, retrieval,
+      # transfer, hangup, etc.). Overrides the assistant's stored tools if provided.
+      sig do
+        returns(
+          T.nilable(
+            T::Array[
+              T.any(
+                Telnyx::BookAppointmentTool,
+                Telnyx::CheckAvailabilityTool,
+                Telnyx::AI::WebhookTool,
+                Telnyx::AI::HangupTool,
+                Telnyx::AI::TransferTool,
+                Telnyx::CallControlRetrievalTool
+              )
+            ]
+          )
+        )
+      end
+      attr_reader :tools
+
+      sig do
+        params(
+          tools:
+            T::Array[
+              T.any(
+                Telnyx::BookAppointmentTool::OrHash,
+                Telnyx::CheckAvailabilityTool::OrHash,
+                Telnyx::AI::WebhookTool::OrHash,
+                Telnyx::AI::HangupTool::OrHash,
+                Telnyx::AI::TransferTool::OrHash,
+                Telnyx::CallControlRetrievalTool::OrHash
+              )
+            ]
+        ).void
+      end
+      attr_writer :tools
+
+      # AI Assistant configuration. All fields except `id` are optional — the
+      # assistant's stored configuration will be used as fallback for any omitted
+      # fields.
+      sig do
+        params(
+          id: String,
+          dynamic_variables:
+            T::Hash[
+              Symbol,
+              Telnyx::CallAssistantRequest::DynamicVariable::Variants
+            ],
+          external_llm: T::Hash[Symbol, T.anything],
+          fallback_config: T::Hash[Symbol, T.anything],
+          greeting: String,
+          instructions: String,
+          llm_api_key_ref: String,
+          mcp_servers: T::Array[T::Hash[Symbol, T.anything]],
+          model: String,
+          name: String,
+          observability_settings: T::Hash[Symbol, T.anything],
+          openai_api_key_ref: String,
+          tools:
+            T::Array[
+              T.any(
+                Telnyx::BookAppointmentTool::OrHash,
+                Telnyx::CheckAvailabilityTool::OrHash,
+                Telnyx::AI::WebhookTool::OrHash,
+                Telnyx::AI::HangupTool::OrHash,
+                Telnyx::AI::TransferTool::OrHash,
+                Telnyx::CallControlRetrievalTool::OrHash
+              )
+            ]
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The identifier of the AI assistant to use.
+        id:,
+        # Map of dynamic variables and their default values. Dynamic variables can be
+        # referenced in instructions, greeting, and tool definitions using the
+        # `{{variable_name}}` syntax. Call-control-agent automatically merges in
+        # `telnyx_call_*` variables (telnyx_call_to, telnyx_call_from,
+        # telnyx_conversation_channel, telnyx_agent_target, telnyx_end_user_target,
+        # telnyx_call_caller_id_name) and custom header variables.
+        dynamic_variables: nil,
+        # External LLM configuration for bringing your own LLM endpoint.
+        external_llm: nil,
+        # Fallback LLM configuration used when the primary LLM provider is unavailable.
+        fallback_config: nil,
+        # Initial greeting text spoken when the assistant starts. Can be plain text for
+        # any voice or SSML for `AWS.Polly.<voice_id>` voices. There is a 3,000 character
+        # limit.
+        greeting: nil,
+        # System instructions for the voice assistant. Can be templated with
+        # [dynamic variables](https://developers.telnyx.com/docs/inference/ai-assistants/dynamic-variables).
+        # This will overwrite the instructions set in the assistant configuration.
+        instructions: nil,
+        # Integration secret identifier for the LLM provider API key. Use this field to
+        # reference an
+        # [integration secret](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret)
+        # containing your LLM provider API key. Supports any LLM provider (OpenAI,
+        # Anthropic, etc.).
+        llm_api_key_ref: nil,
+        # MCP (Model Context Protocol) server configurations for extending the assistant's
+        # capabilities with external tools and data sources.
+        mcp_servers: nil,
+        # LLM model override for this call. If omitted, the assistant's configured model
+        # is used.
+        model: nil,
+        # Assistant name override for this call.
+        name: nil,
+        # Observability configuration for the assistant session, including Langfuse
+        # integration for tracing and monitoring.
+        observability_settings: nil,
+        # Deprecated — use `llm_api_key_ref` instead. Integration secret identifier for
+        # the OpenAI API key. This field is maintained for backward compatibility;
+        # `llm_api_key_ref` is the canonical field name and supports all LLM providers.
+        openai_api_key_ref: nil,
+        # Inline tool definitions available to the assistant (webhook, retrieval,
+        # transfer, hangup, etc.). Overrides the assistant's stored tools if provided.
+        tools: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            id: String,
+            dynamic_variables:
+              T::Hash[
+                Symbol,
+                Telnyx::CallAssistantRequest::DynamicVariable::Variants
+              ],
+            external_llm: T::Hash[Symbol, T.anything],
+            fallback_config: T::Hash[Symbol, T.anything],
+            greeting: String,
+            instructions: String,
+            llm_api_key_ref: String,
+            mcp_servers: T::Array[T::Hash[Symbol, T.anything]],
+            model: String,
+            name: String,
+            observability_settings: T::Hash[Symbol, T.anything],
+            openai_api_key_ref: String,
+            tools:
+              T::Array[
+                T.any(
+                  Telnyx::BookAppointmentTool,
+                  Telnyx::CheckAvailabilityTool,
+                  Telnyx::AI::WebhookTool,
+                  Telnyx::AI::HangupTool,
+                  Telnyx::AI::TransferTool,
+                  Telnyx::CallControlRetrievalTool
+                )
+              ]
+          }
+        )
+      end
+      def to_hash
+      end
+
+      module DynamicVariable
+        extend Telnyx::Internal::Type::Union
+
+        Variants = T.type_alias { T.any(String, Float, T::Boolean) }
+
+        sig do
+          override.returns(
+            T::Array[Telnyx::CallAssistantRequest::DynamicVariable::Variants]
+          )
+        end
+        def self.variants
+        end
+      end
+
+      module Tool
+        extend Telnyx::Internal::Type::Union
+
+        Variants =
+          T.type_alias do
+            T.any(
+              Telnyx::BookAppointmentTool,
+              Telnyx::CheckAvailabilityTool,
+              Telnyx::AI::WebhookTool,
+              Telnyx::AI::HangupTool,
+              Telnyx::AI::TransferTool,
+              Telnyx::CallControlRetrievalTool
+            )
+          end
+
+        sig do
+          override.returns(
+            T::Array[Telnyx::CallAssistantRequest::Tool::Variants]
+          )
+        end
+        def self.variants
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/models/call_control_bucket_ids.rbi

@@ -0,0 +1,42 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    class CallControlBucketIDs < Telnyx::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Telnyx::CallControlBucketIDs, Telnyx::Internal::AnyHash)
+        end
+
+      sig { returns(T::Array[String]) }
+      attr_accessor :bucket_ids
+
+      # The maximum number of results to retrieve as context for the language model.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :max_num_results
+
+      sig { params(max_num_results: Integer).void }
+      attr_writer :max_num_results
+
+      sig do
+        params(bucket_ids: T::Array[String], max_num_results: Integer).returns(
+          T.attached_class
+        )
+      end
+      def self.new(
+        bucket_ids:,
+        # The maximum number of results to retrieve as context for the language model.
+        max_num_results: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          { bucket_ids: T::Array[String], max_num_results: Integer }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/telnyx/models/call_control_retrieval_tool.rbi

@@ -0,0 +1,63 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    class CallControlRetrievalTool < Telnyx::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Telnyx::CallControlRetrievalTool, Telnyx::Internal::AnyHash)
+        end
+
+      sig { returns(Telnyx::CallControlBucketIDs) }
+      attr_reader :retrieval
+
+      sig { params(retrieval: Telnyx::CallControlBucketIDs::OrHash).void }
+      attr_writer :retrieval
+
+      sig { returns(Telnyx::CallControlRetrievalTool::Type::OrSymbol) }
+      attr_accessor :type
+
+      sig do
+        params(
+          retrieval: Telnyx::CallControlBucketIDs::OrHash,
+          type: Telnyx::CallControlRetrievalTool::Type::OrSymbol
+        ).returns(T.attached_class)
+      end
+      def self.new(retrieval:, type:)
+      end
+
+      sig do
+        override.returns(
+          {
+            retrieval: Telnyx::CallControlBucketIDs,
+            type: Telnyx::CallControlRetrievalTool::Type::OrSymbol
+          }
+        )
+      end
+      def to_hash
+      end
+
+      module Type
+        extend Telnyx::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Telnyx::CallControlRetrievalTool::Type) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        RETRIEVAL =
+          T.let(
+            :retrieval,
+            Telnyx::CallControlRetrievalTool::Type::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[Telnyx::CallControlRetrievalTool::Type::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/models/call_dial_params.rbi

@@ -75,6 +75,15 @@ module Telnyx
       end
       attr_writer :answering_machine_detection_config
 
+      # AI Assistant configuration. All fields except `id` are optional — the
+      # assistant's stored configuration will be used as fallback for any omitted
+      # fields.
+      sig { returns(T.nilable(Telnyx::CallAssistantRequest)) }
+      attr_reader :assistant
+
+      sig { params(assistant: Telnyx::CallAssistantRequest::OrHash).void }
+      attr_writer :assistant
+
       # The URL of a file to be played back to the callee when the call is answered. The
       # URL can point to either a WAV or MP3 file. media_name and audio_url cannot be
       # used together in one request.
@@ -562,6 +571,7 @@ module Telnyx
             Telnyx::CallDialParams::AnsweringMachineDetection::OrSymbol,
           answering_machine_detection_config:
             Telnyx::CallDialParams::AnsweringMachineDetectionConfig::OrHash,
+          assistant: Telnyx::CallAssistantRequest::OrHash,
           audio_url: String,
           billing_group_id: String,
           bridge_intent: T::Boolean,
@@ -652,6 +662,10 @@ module Telnyx
         # Optional configuration parameters to modify 'answering_machine_detection'
         # performance.
         answering_machine_detection_config: nil,
+        # AI Assistant configuration. All fields except `id` are optional — the
+        # assistant's stored configuration will be used as fallback for any omitted
+        # fields.
+        assistant: nil,
         # The URL of a file to be played back to the callee when the call is answered. The
         # URL can point to either a WAV or MP3 file. media_name and audio_url cannot be
         # used together in one request.
@@ -815,6 +829,7 @@ module Telnyx
               Telnyx::CallDialParams::AnsweringMachineDetection::OrSymbol,
             answering_machine_detection_config:
               Telnyx::CallDialParams::AnsweringMachineDetectionConfig,
+            assistant: Telnyx::CallAssistantRequest,
             audio_url: String,
             billing_group_id: String,
             bridge_intent: T::Boolean,

data/rbi/telnyx/models/calls/action_answer_params.rbi

@@ -15,6 +15,15 @@ module Telnyx
         sig { returns(String) }
         attr_accessor :call_control_id
 
+        # AI Assistant configuration. All fields except `id` are optional — the
+        # assistant's stored configuration will be used as fallback for any omitted
+        # fields.
+        sig { returns(T.nilable(Telnyx::CallAssistantRequest)) }
+        attr_reader :assistant
+
+        sig { params(assistant: Telnyx::CallAssistantRequest::OrHash).void }
+        attr_writer :assistant
+
         # Use this field to set the Billing Group ID for the call. Must be a valid and
         # existing Billing Group ID.
         sig { returns(T.nilable(String)) }
@@ -372,6 +381,7 @@ module Telnyx
         sig do
           params(
             call_control_id: String,
+            assistant: Telnyx::CallAssistantRequest::OrHash,
             billing_group_id: String,
             client_state: String,
             command_id: String,
@@ -422,6 +432,10 @@ module Telnyx
         end
         def self.new(
           call_control_id:,
+          # AI Assistant configuration. All fields except `id` are optional — the
+          # assistant's stored configuration will be used as fallback for any omitted
+          # fields.
+          assistant: nil,
           # Use this field to set the Billing Group ID for the call. Must be a valid and
           # existing Billing Group ID.
           billing_group_id: nil,
@@ -510,6 +524,7 @@ module Telnyx
           override.returns(
             {
               call_control_id: String,
+              assistant: Telnyx::CallAssistantRequest,
               billing_group_id: String,
               client_state: String,
               command_id: String,

data/rbi/telnyx/models/calls/action_start_ai_assistant_params.rbi

@@ -18,20 +18,13 @@ module Telnyx
         sig { returns(String) }
         attr_accessor :call_control_id
 
-        # AI Assistant configuration
-        sig do
-          returns(
-            T.nilable(Telnyx::Calls::ActionStartAIAssistantParams::Assistant)
-          )
-        end
+        # AI Assistant configuration. All fields except `id` are optional — the
+        # assistant's stored configuration will be used as fallback for any omitted
+        # fields.
+        sig { returns(T.nilable(Telnyx::CallAssistantRequest)) }
         attr_reader :assistant
 
-        sig do
-          params(
-            assistant:
-              Telnyx::Calls::ActionStartAIAssistantParams::Assistant::OrHash
-          ).void
-        end
+        sig { params(assistant: Telnyx::CallAssistantRequest::OrHash).void }
         attr_writer :assistant
 
         # Use this field to add state to every subsequent webhook. It must be a valid
@@ -210,8 +203,7 @@ module Telnyx
         sig do
           params(
             call_control_id: String,
-            assistant:
-              Telnyx::Calls::ActionStartAIAssistantParams::Assistant::OrHash,
+            assistant: Telnyx::CallAssistantRequest::OrHash,
             client_state: String,
             command_id: String,
             greeting: String,
@@ -247,7 +239,9 @@ module Telnyx
         end
         def self.new(
           call_control_id:,
-          # AI Assistant configuration
+          # AI Assistant configuration. All fields except `id` are optional — the
+          # assistant's stored configuration will be used as fallback for any omitted
+          # fields.
           assistant: nil,
           # Use this field to add state to every subsequent webhook. It must be a valid
           # Base-64 encoded string.
@@ -309,7 +303,7 @@ module Telnyx
           override.returns(
             {
               call_control_id: String,
-              assistant: Telnyx::Calls::ActionStartAIAssistantParams::Assistant,
+              assistant: Telnyx::CallAssistantRequest,
               client_state: String,
               command_id: String,
               greeting: String,
@@ -347,67 +341,6 @@ module Telnyx
         def to_hash
         end
 
-        class Assistant < Telnyx::Internal::Type::BaseModel
-          OrHash =
-            T.type_alias do
-              T.any(
-                Telnyx::Calls::ActionStartAIAssistantParams::Assistant,
-                Telnyx::Internal::AnyHash
-              )
-            end
-
-          # The identifier of the AI assistant to use
-          sig { returns(T.nilable(String)) }
-          attr_reader :id
-
-          sig { params(id: String).void }
-          attr_writer :id
-
-          # The system instructions that the voice assistant uses during the start assistant
-          # command. This will overwrite the instructions set in the assistant
-          # configuration.
-          sig { returns(T.nilable(String)) }
-          attr_reader :instructions
-
-          sig { params(instructions: String).void }
-          attr_writer :instructions
-
-          # Reference to the OpenAI API key. Required only when using OpenAI models
-          sig { returns(T.nilable(String)) }
-          attr_reader :openai_api_key_ref
-
-          sig { params(openai_api_key_ref: String).void }
-          attr_writer :openai_api_key_ref
-
-          # AI Assistant configuration
-          sig do
-            params(
-              id: String,
-              instructions: String,
-              openai_api_key_ref: String
-            ).returns(T.attached_class)
-          end
-          def self.new(
-            # The identifier of the AI assistant to use
-            id: nil,
-            # The system instructions that the voice assistant uses during the start assistant
-            # command. This will overwrite the instructions set in the assistant
-            # configuration.
-            instructions: nil,
-            # Reference to the OpenAI API key. Required only when using OpenAI models
-            openai_api_key_ref: nil
-          )
-          end
-
-          sig do
-            override.returns(
-              { id: String, instructions: String, openai_api_key_ref: String }
-            )
-          end
-          def to_hash
-          end
-        end
-
         # Messages sent by an end user
         module MessageHistory
           extend Telnyx::Internal::Type::Union

data/rbi/telnyx/models/check_availability_tool.rbi

@@ -0,0 +1,67 @@
+# typed: strong
+
+module Telnyx
+  module Models
+    class CheckAvailabilityTool < Telnyx::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Telnyx::CheckAvailabilityTool, Telnyx::Internal::AnyHash)
+        end
+
+      sig { returns(Telnyx::CheckAvailabilityToolParams) }
+      attr_reader :check_availability
+
+      sig do
+        params(
+          check_availability: Telnyx::CheckAvailabilityToolParams::OrHash
+        ).void
+      end
+      attr_writer :check_availability
+
+      sig { returns(Telnyx::CheckAvailabilityTool::Type::OrSymbol) }
+      attr_accessor :type
+
+      sig do
+        params(
+          check_availability: Telnyx::CheckAvailabilityToolParams::OrHash,
+          type: Telnyx::CheckAvailabilityTool::Type::OrSymbol
+        ).returns(T.attached_class)
+      end
+      def self.new(check_availability:, type:)
+      end
+
+      sig do
+        override.returns(
+          {
+            check_availability: Telnyx::CheckAvailabilityToolParams,
+            type: Telnyx::CheckAvailabilityTool::Type::OrSymbol
+          }
+        )
+      end
+      def to_hash
+      end
+
+      module Type
+        extend Telnyx::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Telnyx::CheckAvailabilityTool::Type) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        CHECK_AVAILABILITY =
+          T.let(
+            :check_availability,
+            Telnyx::CheckAvailabilityTool::Type::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[Telnyx::CheckAvailabilityTool::Type::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end