telnyx 5.69.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.
@@ -224,6 +233,15 @@ module Telnyx
       sig { params(prevent_double_bridge: T::Boolean).void }
       attr_writer :prevent_double_bridge
 
+      # Indicates the privacy level to be used for the call. When set to `id`, caller ID
+      # information (name and number) will be hidden from the called party. When set to
+      # `none` or omitted, caller ID will be shown normally.
+      sig { returns(T.nilable(Telnyx::CallDialParams::Privacy::OrSymbol)) }
+      attr_reader :privacy
+
+      sig { params(privacy: Telnyx::CallDialParams::Privacy::OrSymbol).void }
+      attr_writer :privacy
+
       # Start recording automatically after an event. Disabled by default.
       sig { returns(T.nilable(Telnyx::CallDialParams::Record::OrSymbol)) }
       attr_reader :record
@@ -553,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,
@@ -570,6 +589,7 @@ module Telnyx
           park_after_unbridge: String,
           preferred_codecs: String,
           prevent_double_bridge: T::Boolean,
+          privacy: Telnyx::CallDialParams::Privacy::OrSymbol,
           record: Telnyx::CallDialParams::Record::OrSymbol,
           record_channels: Telnyx::CallDialParams::RecordChannels::OrSymbol,
           record_custom_file_name: String,
@@ -642,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.
@@ -694,6 +718,10 @@ module Telnyx
         # Prevents bridging and hangs up the call if the target is already bridged.
         # Disabled by default.
         prevent_double_bridge: nil,
+        # Indicates the privacy level to be used for the call. When set to `id`, caller ID
+        # information (name and number) will be hidden from the called party. When set to
+        # `none` or omitted, caller ID will be shown normally.
+        privacy: nil,
         # Start recording automatically after an event. Disabled by default.
         record: nil,
         # Defines which channel should be recorded ('single' or 'dual') when `record` is
@@ -801,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,
@@ -818,6 +847,7 @@ module Telnyx
             park_after_unbridge: String,
             preferred_codecs: String,
             prevent_double_bridge: T::Boolean,
+            privacy: Telnyx::CallDialParams::Privacy::OrSymbol,
             record: Telnyx::CallDialParams::Record::OrSymbol,
             record_channels: Telnyx::CallDialParams::RecordChannels::OrSymbol,
             record_custom_file_name: String,
@@ -1479,6 +1509,28 @@ module Telnyx
         end
       end
 
+      # Indicates the privacy level to be used for the call. When set to `id`, caller ID
+      # information (name and number) will be hidden from the called party. When set to
+      # `none` or omitted, caller ID will be shown normally.
+      module Privacy
+        extend Telnyx::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, Telnyx::CallDialParams::Privacy) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        ID = T.let(:id, Telnyx::CallDialParams::Privacy::TaggedSymbol)
+        NONE = T.let(:none, Telnyx::CallDialParams::Privacy::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[Telnyx::CallDialParams::Privacy::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+
       # Start recording automatically after an event. Disabled by default.
       module Record
         extend Telnyx::Internal::Type::Enum

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,