telnyx 5.130.1 → 5.131.0

data/rbi/telnyx/models.rbi

@@ -51,6 +51,9 @@ module Telnyx
 
   AIRetrieveModelsParams = Telnyx::Models::AIRetrieveModelsParams
 
+  AISearchConversationHistoriesParams =
+    Telnyx::Models::AISearchConversationHistoriesParams
+
   AISummarizeParams = Telnyx::Models::AISummarizeParams
 
   AlphanumericSenderID = Telnyx::Models::AlphanumericSenderID

data/rbi/telnyx/resources/ai.rbi

@@ -2,7 +2,6 @@
 
 module Telnyx
   module Resources
-    # Generate text with LLMs
     class AI
       # Configure AI assistant specifications
       sig { returns(Telnyx::Resources::AI::Assistants) }
@@ -78,6 +77,123 @@ module Telnyx
       def retrieve_models(request_options: {})
       end
 
+      # Performs semantic vector search across conversation history records.
+      #
+      # **How it works:**
+      #
+      # 1. The query text is embedded into a 1024-dimensional vector using the
+      #    multilingual-e5-large model.
+      # 2. The vector is sent to regional OpenSearch clusters for kNN search using HNSW
+      #    cosine similarity.
+      # 3. When no region is specified, all regions are queried in parallel (fan-out)
+      #    and results are merged by score.
+      # 4. Results are ranked by cosine similarity score (descending) and truncated to
+      #    `top_k`.
+      #
+      # **Authentication:** Requires a Telnyx API key via `Authorization: Bearer <key>`.
+      # Results are automatically scoped to the caller's organization —
+      # `organization_id` is injected from the auth token and cannot be overridden.
+      #
+      # **Chunking:** Records are split into chunks of up to 480 tokens with 64-token
+      # overlap at ingestion time. Each search result represents a single chunk, with
+      # `chunk_index` and `chunk_total` indicating its position within the original
+      # record.
+      #
+      # **Filtering:** Use `filter[field][operator]=value` query parameters to narrow
+      # results before vector search.
+      #
+      # Top-level filterable fields: `user_id`, `record_type`, `region`, `document_id`,
+      # `record_id`, `record_created_at`, `ingested_at`, `retention`
+      #
+      # Note: `retention` is filter-only — it can be used to narrow results but is not
+      # returned in the response body.
+      #
+      # Metadata fields: any field not in the list above is resolved to
+      # `data.metadata.<field>` in OpenSearch (e.g., `filter[language]=en` →
+      # `data.metadata.language`).
+      #
+      # Supported filter operators:
+      #
+      # - `eq` — exact match (default when no operator specified)
+      # - `in` — match any of comma-separated values
+      # - `gte`, `gt`, `lte`, `lt` — range comparisons (useful for date filtering)
+      # - `contains` — wildcard substring match
+      #
+      # **Examples:**
+      #
+      # ```
+      # GET /v2/ai/conversation_histories?q=billing+issue&record_type=voice&top_k=10
+      # GET /v2/ai/conversation_histories?q=setup+guide&record_type=knowledge_base&region=USA&min_score=0.5
+      # GET /v2/ai/conversation_histories?q=refund&record_type=voice&filter[record_created_at][gte]=2026-01-01T00:00:00Z
+      # GET /v2/ai/conversation_histories?q=outage&record_type=voice&filter[region][in]=USA,DEU
+      # GET /v2/ai/conversation_histories?q=hold+time&record_type=voice&filter[language]=en
+      # ```
+      sig do
+        params(
+          q: String,
+          record_type:
+            Telnyx::AISearchConversationHistoriesParams::RecordType::OrSymbol,
+          filter_document_id: String,
+          filter_ingested_at_gte: Time,
+          filter_ingested_at_lte: Time,
+          filter_record_created_at_gte: Time,
+          filter_record_created_at_lte: Time,
+          filter_record_id: String,
+          filter_region_in: String,
+          filter_retention: String,
+          filter_user_id: String,
+          min_score: Float,
+          region: Telnyx::AISearchConversationHistoriesParams::Region::OrSymbol,
+          top_k: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::AISearchConversationHistoriesResponse)
+      end
+      def search_conversation_histories(
+        # Natural language search query. The text is embedded into a 1024-dimensional
+        # vector and compared against indexed record chunks using kNN cosine similarity.
+        q:,
+        # The type of records to search. Each record type is stored in a separate vector
+        # index.
+        record_type:,
+        # Filter by document identifier (exact match). Populated for knowledge_base
+        # records.
+        filter_document_id: nil,
+        # Only include records ingested (chunked, embedded, and indexed) on or after this
+        # ISO 8601 timestamp.
+        filter_ingested_at_gte: nil,
+        # Only include records ingested (chunked, embedded, and indexed) on or before this
+        # ISO 8601 timestamp.
+        filter_ingested_at_lte: nil,
+        # Only include records whose original creation time is on or after this ISO 8601
+        # timestamp.
+        filter_record_created_at_gte: nil,
+        # Only include records whose original creation time is on or before this ISO 8601
+        # timestamp.
+        filter_record_created_at_lte: nil,
+        # Filter to chunks belonging to a specific parent record (exact match).
+        filter_record_id: nil,
+        # Filter by the region stored on the record. Comma-separated to match multiple
+        # regions (USA, DEU, AUS, UAE). Distinct from the `region` parameter, which
+        # selects which cluster(s) are queried.
+        filter_region_in: nil,
+        # Filter by retention policy (exact match). Filter-only: not returned in the
+        # response body.
+        filter_retention: nil,
+        # Filter to records owned by a specific user (exact match).
+        filter_user_id: nil,
+        # Minimum cosine similarity score threshold (0.0 to 1.0). Results below this
+        # threshold are excluded.
+        min_score: nil,
+        # Restrict search to a specific region's OpenSearch cluster. When omitted, all
+        # regions are queried in parallel (fan-out) and results are merged by cosine
+        # similarity score.
+        region: nil,
+        # Maximum number of results to return. Defaults to 20, maximum 100.
+        top_k: nil,
+        request_options: {}
+      )
+      end
+
       # Generate a summary of a file's contents.
       #
       # Supports the following text formats:

data/sig/telnyx/models/ai_search_conversation_histories_params.rbs

@@ -0,0 +1,144 @@
+module Telnyx
+  module Models
+    type ai_search_conversation_histories_params =
+      {
+        q: String,
+        record_type: Telnyx::Models::AISearchConversationHistoriesParams::record_type,
+        filter_document_id: String,
+        filter_ingested_at_gte: Time,
+        filter_ingested_at_lte: Time,
+        filter_record_created_at_gte: Time,
+        filter_record_created_at_lte: Time,
+        filter_record_id: String,
+        filter_region_in: String,
+        filter_retention: String,
+        filter_user_id: String,
+        min_score: Float,
+        region: Telnyx::Models::AISearchConversationHistoriesParams::region,
+        top_k: Integer
+      }
+      & Telnyx::Internal::Type::request_parameters
+
+    class AISearchConversationHistoriesParams < Telnyx::Internal::Type::BaseModel
+      extend Telnyx::Internal::Type::RequestParameters::Converter
+      include Telnyx::Internal::Type::RequestParameters
+
+      attr_accessor q: String
+
+      attr_accessor record_type: Telnyx::Models::AISearchConversationHistoriesParams::record_type
+
+      attr_reader filter_document_id: String?
+
+      def filter_document_id=: (String) -> String
+
+      attr_reader filter_ingested_at_gte: Time?
+
+      def filter_ingested_at_gte=: (Time) -> Time
+
+      attr_reader filter_ingested_at_lte: Time?
+
+      def filter_ingested_at_lte=: (Time) -> Time
+
+      attr_reader filter_record_created_at_gte: Time?
+
+      def filter_record_created_at_gte=: (Time) -> Time
+
+      attr_reader filter_record_created_at_lte: Time?
+
+      def filter_record_created_at_lte=: (Time) -> Time
+
+      attr_reader filter_record_id: String?
+
+      def filter_record_id=: (String) -> String
+
+      attr_reader filter_region_in: String?
+
+      def filter_region_in=: (String) -> String
+
+      attr_reader filter_retention: String?
+
+      def filter_retention=: (String) -> String
+
+      attr_reader filter_user_id: String?
+
+      def filter_user_id=: (String) -> String
+
+      attr_reader min_score: Float?
+
+      def min_score=: (Float) -> Float
+
+      attr_reader region: Telnyx::Models::AISearchConversationHistoriesParams::region?
+
+      def region=: (
+        Telnyx::Models::AISearchConversationHistoriesParams::region
+      ) -> Telnyx::Models::AISearchConversationHistoriesParams::region
+
+      attr_reader top_k: Integer?
+
+      def top_k=: (Integer) -> Integer
+
+      def initialize: (
+        q: String,
+        record_type: Telnyx::Models::AISearchConversationHistoriesParams::record_type,
+        ?filter_document_id: String,
+        ?filter_ingested_at_gte: Time,
+        ?filter_ingested_at_lte: Time,
+        ?filter_record_created_at_gte: Time,
+        ?filter_record_created_at_lte: Time,
+        ?filter_record_id: String,
+        ?filter_region_in: String,
+        ?filter_retention: String,
+        ?filter_user_id: String,
+        ?min_score: Float,
+        ?region: Telnyx::Models::AISearchConversationHistoriesParams::region,
+        ?top_k: Integer,
+        ?request_options: Telnyx::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        q: String,
+        record_type: Telnyx::Models::AISearchConversationHistoriesParams::record_type,
+        filter_document_id: String,
+        filter_ingested_at_gte: Time,
+        filter_ingested_at_lte: Time,
+        filter_record_created_at_gte: Time,
+        filter_record_created_at_lte: Time,
+        filter_record_id: String,
+        filter_region_in: String,
+        filter_retention: String,
+        filter_user_id: String,
+        min_score: Float,
+        region: Telnyx::Models::AISearchConversationHistoriesParams::region,
+        top_k: Integer,
+        request_options: Telnyx::RequestOptions
+      }
+
+      type record_type =
+        :voice | :message | :ai_pipeline_storage | :knowledge_base
+
+      module RecordType
+        extend Telnyx::Internal::Type::Enum
+
+        VOICE: :voice
+        MESSAGE: :message
+        AI_PIPELINE_STORAGE: :ai_pipeline_storage
+        KNOWLEDGE_BASE: :knowledge_base
+
+        def self?.values: -> ::Array[Telnyx::Models::AISearchConversationHistoriesParams::record_type]
+      end
+
+      type region = :USA | :DEU | :AUS | :UAE
+
+      module Region
+        extend Telnyx::Internal::Type::Enum
+
+        USA: :USA
+        DEU: :DEU
+        AUS: :AUS
+        UAE: :UAE
+
+        def self?.values: -> ::Array[Telnyx::Models::AISearchConversationHistoriesParams::region]
+      end
+    end
+  end
+end

data/sig/telnyx/models/ai_search_conversation_histories_response.rbs

@@ -0,0 +1,168 @@
+module Telnyx
+  module Models
+    type ai_search_conversation_histories_response =
+      {
+        data: ::Array[Telnyx::Models::AISearchConversationHistoriesResponse::Data],
+        meta: Telnyx::Models::AISearchConversationHistoriesResponse::Meta
+      }
+
+    class AISearchConversationHistoriesResponse < Telnyx::Internal::Type::BaseModel
+      attr_accessor data: ::Array[Telnyx::Models::AISearchConversationHistoriesResponse::Data]
+
+      attr_accessor meta: Telnyx::Models::AISearchConversationHistoriesResponse::Meta
+
+      def initialize: (
+        data: ::Array[Telnyx::Models::AISearchConversationHistoriesResponse::Data],
+        meta: Telnyx::Models::AISearchConversationHistoriesResponse::Meta
+      ) -> void
+
+      def to_hash: -> {
+        data: ::Array[Telnyx::Models::AISearchConversationHistoriesResponse::Data],
+        meta: Telnyx::Models::AISearchConversationHistoriesResponse::Meta
+      }
+
+      type data =
+        {
+          id: String,
+          chunk_index: Integer,
+          chunk_total: Integer,
+          document_id: String?,
+          ingested_at: Time,
+          organization_id: String,
+          record_created_at: Time,
+          record_id: String,
+          record_type: Telnyx::Models::AISearchConversationHistoriesResponse::Data::record_type,
+          region: Telnyx::Models::AISearchConversationHistoriesResponse::Data::region,
+          score: Float,
+          text: String,
+          user_id: String,
+          metadata: ::Hash[Symbol, top]
+        }
+
+      class Data < Telnyx::Internal::Type::BaseModel
+        attr_accessor id: String
+
+        attr_accessor chunk_index: Integer
+
+        attr_accessor chunk_total: Integer
+
+        attr_accessor document_id: String?
+
+        attr_accessor ingested_at: Time
+
+        attr_accessor organization_id: String
+
+        attr_accessor record_created_at: Time
+
+        attr_accessor record_id: String
+
+        attr_accessor record_type: Telnyx::Models::AISearchConversationHistoriesResponse::Data::record_type
+
+        attr_accessor region: Telnyx::Models::AISearchConversationHistoriesResponse::Data::region
+
+        attr_accessor score: Float
+
+        attr_accessor text: String
+
+        attr_accessor user_id: String
+
+        attr_reader metadata: ::Hash[Symbol, top]?
+
+        def metadata=: (::Hash[Symbol, top]) -> ::Hash[Symbol, top]
+
+        def initialize: (
+          id: String,
+          chunk_index: Integer,
+          chunk_total: Integer,
+          document_id: String?,
+          ingested_at: Time,
+          organization_id: String,
+          record_created_at: Time,
+          record_id: String,
+          record_type: Telnyx::Models::AISearchConversationHistoriesResponse::Data::record_type,
+          region: Telnyx::Models::AISearchConversationHistoriesResponse::Data::region,
+          score: Float,
+          text: String,
+          user_id: String,
+          ?metadata: ::Hash[Symbol, top]
+        ) -> void
+
+        def to_hash: -> {
+          id: String,
+          chunk_index: Integer,
+          chunk_total: Integer,
+          document_id: String?,
+          ingested_at: Time,
+          organization_id: String,
+          record_created_at: Time,
+          record_id: String,
+          record_type: Telnyx::Models::AISearchConversationHistoriesResponse::Data::record_type,
+          region: Telnyx::Models::AISearchConversationHistoriesResponse::Data::region,
+          score: Float,
+          text: String,
+          user_id: String,
+          metadata: ::Hash[Symbol, top]
+        }
+
+        type record_type =
+          :voice | :message | :ai_pipeline_storage | :knowledge_base
+
+        module RecordType
+          extend Telnyx::Internal::Type::Enum
+
+          VOICE: :voice
+          MESSAGE: :message
+          AI_PIPELINE_STORAGE: :ai_pipeline_storage
+          KNOWLEDGE_BASE: :knowledge_base
+
+          def self?.values: -> ::Array[Telnyx::Models::AISearchConversationHistoriesResponse::Data::record_type]
+        end
+
+        type region = :USA | :DEU | :AUS | :UAE
+
+        module Region
+          extend Telnyx::Internal::Type::Enum
+
+          USA: :USA
+          DEU: :DEU
+          AUS: :AUS
+          UAE: :UAE
+
+          def self?.values: -> ::Array[Telnyx::Models::AISearchConversationHistoriesResponse::Data::region]
+        end
+      end
+
+      type meta =
+        {
+          page_number: Integer,
+          page_size: Integer,
+          total_pages: Integer,
+          total_results: Integer
+        }
+
+      class Meta < Telnyx::Internal::Type::BaseModel
+        attr_accessor page_number: Integer
+
+        attr_accessor page_size: Integer
+
+        attr_accessor total_pages: Integer
+
+        attr_accessor total_results: Integer
+
+        def initialize: (
+          page_number: Integer,
+          page_size: Integer,
+          total_pages: Integer,
+          total_results: Integer
+        ) -> void
+
+        def to_hash: -> {
+          page_number: Integer,
+          page_size: Integer,
+          total_pages: Integer,
+          total_results: Integer
+        }
+      end
+    end
+  end
+end

data/sig/telnyx/models.rbs

@@ -47,6 +47,8 @@ module Telnyx
 
   class AIRetrieveModelsParams = Telnyx::Models::AIRetrieveModelsParams
 
+  class AISearchConversationHistoriesParams = Telnyx::Models::AISearchConversationHistoriesParams
+
   class AISummarizeParams = Telnyx::Models::AISummarizeParams
 
   class AlphanumericSenderID = Telnyx::Models::AlphanumericSenderID

data/sig/telnyx/resources/ai.rbs

@@ -34,6 +34,24 @@ module Telnyx
         ?request_options: Telnyx::request_opts
       ) -> Telnyx::Models::AIRetrieveModelsResponse
 
+      def search_conversation_histories: (
+        q: String,
+        record_type: Telnyx::Models::AISearchConversationHistoriesParams::record_type,
+        ?filter_document_id: String,
+        ?filter_ingested_at_gte: Time,
+        ?filter_ingested_at_lte: Time,
+        ?filter_record_created_at_gte: Time,
+        ?filter_record_created_at_lte: Time,
+        ?filter_record_id: String,
+        ?filter_region_in: String,
+        ?filter_retention: String,
+        ?filter_user_id: String,
+        ?min_score: Float,
+        ?region: Telnyx::Models::AISearchConversationHistoriesParams::region,
+        ?top_k: Integer,
+        ?request_options: Telnyx::request_opts
+      ) -> Telnyx::Models::AISearchConversationHistoriesResponse
+
       def summarize: (
         bucket: String,
         filename: String,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: telnyx
 version: !ruby/object:Gem::Version
-  version: 5.130.1
+  version: 5.131.0
 platform: ruby
 authors:
 - Telnyx
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi
@@ -419,6 +419,8 @@ files:
 - lib/telnyx/models/ai_create_response_deprecated_response.rb
 - lib/telnyx/models/ai_retrieve_models_params.rb
 - lib/telnyx/models/ai_retrieve_models_response.rb
+- lib/telnyx/models/ai_search_conversation_histories_params.rb
+- lib/telnyx/models/ai_search_conversation_histories_response.rb
 - lib/telnyx/models/ai_summarize_params.rb
 - lib/telnyx/models/ai_summarize_response.rb
 - lib/telnyx/models/alphanumeric_sender_id.rb
@@ -3226,6 +3228,8 @@ files:
 - rbi/telnyx/models/ai_create_response_deprecated_response.rbi
 - rbi/telnyx/models/ai_retrieve_models_params.rbi
 - rbi/telnyx/models/ai_retrieve_models_response.rbi
+- rbi/telnyx/models/ai_search_conversation_histories_params.rbi
+- rbi/telnyx/models/ai_search_conversation_histories_response.rbi
 - rbi/telnyx/models/ai_summarize_params.rbi
 - rbi/telnyx/models/ai_summarize_response.rbi
 - rbi/telnyx/models/alphanumeric_sender_id.rbi
@@ -6024,6 +6028,8 @@ files:
 - sig/telnyx/models/ai_create_response_deprecated_response.rbs
 - sig/telnyx/models/ai_retrieve_models_params.rbs
 - sig/telnyx/models/ai_retrieve_models_response.rbs
+- sig/telnyx/models/ai_search_conversation_histories_params.rbs
+- sig/telnyx/models/ai_search_conversation_histories_response.rbs
 - sig/telnyx/models/ai_summarize_params.rbs
 - sig/telnyx/models/ai_summarize_response.rbs
 - sig/telnyx/models/alphanumeric_sender_id.rbs