telnyx 5.159.0 → 5.161.0

data/rbi/telnyx/resources/ai/collections.rbi

@@ -0,0 +1,208 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      # Create and manage logical collections of your Telnyx data, tune retrieval
+      # settings, manage sources, and run collection-scoped semantic search.
+      class Collections
+        # Create and manage logical collections of your Telnyx data, tune retrieval
+        # settings, manage sources, and run collection-scoped semantic search.
+        sig { returns(Telnyx::Resources::AI::Collections::Settings) }
+        attr_reader :settings
+
+        # Create and manage logical collections of your Telnyx data, tune retrieval
+        # settings, manage sources, and run collection-scoped semantic search.
+        sig { returns(Telnyx::Resources::AI::Collections::Sources) }
+        attr_reader :sources
+
+        # Creates a new collection scoped to your organization. Optionally attach sources
+        # and retrieval settings at creation time. If `slug` is omitted, one is derived
+        # from `name` and must be unique within your organization.
+        sig do
+          params(
+            name: String,
+            description: String,
+            settings: Telnyx::AI::Collections::RetrievalSettingsWrapper::OrHash,
+            slug: String,
+            sources: T::Array[Telnyx::AI::Collections::SourceRequest::OrHash],
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::AI::CollectionEnvelope)
+        end
+        def create(
+          # Human-readable collection name.
+          name:,
+          # Optional description.
+          description: nil,
+          # Optional retrieval settings.
+          settings: nil,
+          # Optional slug (unique per organization). Derived from `name` when omitted.
+          slug: nil,
+          # Optional sources to attach at creation time.
+          sources: nil,
+          request_options: {}
+        )
+        end
+
+        # Fetches a single collection by its `slug`.
+        sig do
+          params(
+            slug: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::AI::CollectionEnvelope)
+        end
+        def retrieve(
+          # The collection's slug (unique within your organization).
+          slug,
+          request_options: {}
+        )
+        end
+
+        # Updates a collection's metadata (`name` and/or `description`). Sources and
+        # settings are managed through their own sub-resources.
+        sig do
+          params(
+            uuid: String,
+            description: String,
+            name: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::AI::CollectionEnvelope)
+        end
+        def update(
+          # The collection's unique identifier.
+          uuid,
+          description: nil,
+          name: nil,
+          request_options: {}
+        )
+        end
+
+        # Returns a paginated list of collections in your organization.
+        sig do
+          params(
+            page_number: Integer,
+            page_size: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(
+            Telnyx::Internal::DefaultFlatPagination[Telnyx::AI::Collection]
+          )
+        end
+        def list(
+          # Page number to return (1-based). Defaults to 1.
+          page_number: nil,
+          # Number of results per page. Defaults to 20.
+          page_size: nil,
+          request_options: {}
+        )
+        end
+
+        # Soft-deletes a collection. Its `slug` is freed and may be reused by a new
+        # collection.
+        sig do
+          params(
+            uuid: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).void
+        end
+        def delete(
+          # The collection's unique identifier.
+          uuid,
+          request_options: {}
+        )
+        end
+
+        # Fetches a single collection by its `uuid`.
+        sig do
+          params(
+            uuid: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::AI::CollectionEnvelope)
+        end
+        def retrieve_by_id(
+          # The collection's unique identifier.
+          uuid,
+          request_options: {}
+        )
+        end
+
+        # Runs search over the documents in a collection, ranked by relevance to `query`.
+        # The collection's `retrieval_type` setting selects the strategy: `vector`
+        # (semantic similarity), `hybrid` (vector similarity fused with keyword matching),
+        # or `keyword` (lexical BM25 matching). When `query` is omitted, returns a plain
+        # catalog listing of the collection's documents.
+        #
+        # **How it works:**
+        #
+        # 1. For `vector` and `hybrid`, the `query` text is embedded into a
+        #    1024-dimensional vector using the multilingual-e5-large model.
+        # 2. For `vector`, the embedding is compared against the collection's indexed
+        #    document chunks using semantic similarity; for `hybrid`, those similarity
+        #    scores are fused with keyword-match scores; for `keyword`, only lexical BM25
+        #    matching is applied.
+        # 3. Results are ranked by `score` (descending) and paginated via `page[number]` /
+        #    `page[size]`.
+        #
+        # **Authentication:** Requires a Telnyx API key via `Authorization: Bearer <key>`.
+        # Results are automatically scoped to your organization and cannot be overridden.
+        #
+        # **Filtering:** Use `filter[field][operator]=value` query parameters to narrow
+        # results before search. Supported operators: `eq` (default), `in`, `gte`, `gt`,
+        # `lte`, `lt`, `contains`. Metadata fields resolve to `metadata.<field>`.
+        #
+        # **Examples:**
+        #
+        # - `GET /v2/ai/collections/my-collection/documents?query=billing+issue&top_k=10`
+        # - `GET /v2/ai/collections/my-collection/documents?query=refund&sources=voice,message`
+        # - `GET /v2/ai/collections/my-collection/documents?query=outage&filter[record_created_at][gte]=2026-01-01T00:00:00Z`
+        sig do
+          params(
+            slug: String,
+            filter: T::Hash[Symbol, T.anything],
+            page_number: Integer,
+            page_size: Integer,
+            query: String,
+            retrieval_type:
+              Telnyx::AI::CollectionRetrieveDocumentsParams::RetrievalType::OrSymbol,
+            sources: String,
+            top_k: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::AI::CollectionRetrieveDocumentsResponse)
+        end
+        def retrieve_documents(
+          # The collection's slug (unique within your organization).
+          slug,
+          # Field filters applied before ranking, using `filter[field][operator]=value`.
+          # Supported operators: `eq` (default), `in`, `gte`, `gt`, `lte`, `lt`, `contains`.
+          # Known fields: `record_type`, `record_id`, `user_id`, `record_created_at`,
+          # `ingested_at`; any other name resolves to a `metadata.<field>` filter. Example:
+          # `filter[record_id][eq]=rec_123`.
+          filter: nil,
+          # Page number to return (1-based). Defaults to 1.
+          page_number: nil,
+          # Number of results per page. Defaults to 20.
+          page_size: nil,
+          # Natural-language search query. When provided, the text is matched against the
+          # collection's document chunks using the collection's `retrieval_type` (vector or
+          # hybrid). When omitted, documents are returned as a plain catalog listing.
+          query: nil,
+          # Override the collection's configured retrieval strategy for this request. Echoed
+          # back in `meta.retrieval_type`.
+          retrieval_type: nil,
+          # Comma-separated list of source types to restrict the search to. When omitted,
+          # all of the collection's sources are searched.
+          sources: nil,
+          # Maximum number of ranked results to consider. When omitted, the collection's
+          # configured `top_k` setting is used.
+          top_k: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/tools.rbi

@@ -5,7 +5,7 @@ module Telnyx
     class AI
       # Configure AI assistant specifications
       class Tools
-        # Create Tool
+        # Create a new custom AI tool that can be attached to AI assistants.
         sig do
           params(
             display_name: String,
@@ -17,6 +17,8 @@ module Telnyx
             pay: Telnyx::AI::PayToolParams::OrHash,
             retrieval: T::Hash[Symbol, T.anything],
             timeout_ms: Integer,
+            update_dynamic_variables:
+              Telnyx::AI::UpdateDynamicVariablesToolParams::OrHash,
             webhook: T::Hash[Symbol, T.anything],
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::AI::SharedToolResponse)
@@ -31,12 +33,14 @@ module Telnyx
           pay: nil,
           retrieval: nil,
           timeout_ms: nil,
+          # Configuration for an update_dynamic_variables tool.
+          update_dynamic_variables: nil,
           webhook: nil,
           request_options: {}
         )
         end
 
-        # Get Tool
+        # Retrieve the details of a specific AI tool.
         sig do
           params(
             tool_id: String,
@@ -50,7 +54,7 @@ module Telnyx
         )
         end
 
-        # Update Tool
+        # Update the configuration of an existing AI tool.
         sig do
           params(
             tool_id: String,
@@ -63,6 +67,8 @@ module Telnyx
             retrieval: T::Hash[Symbol, T.anything],
             timeout_ms: Integer,
             type: String,
+            update_dynamic_variables:
+              Telnyx::AI::UpdateDynamicVariablesToolParams::OrHash,
             webhook: T::Hash[Symbol, T.anything],
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::AI::SharedToolResponse)
@@ -79,12 +85,14 @@ module Telnyx
           retrieval: nil,
           timeout_ms: nil,
           type: nil,
+          # Configuration for an update_dynamic_variables tool.
+          update_dynamic_variables: nil,
           webhook: nil,
           request_options: {}
         )
         end
 
-        # List Tools
+        # Retrieve a list of the custom AI tools configured on your account.
         sig do
           params(
             filter_name: String,
@@ -111,7 +119,7 @@ module Telnyx
         )
         end
 
-        # Delete Tool
+        # Delete a custom AI tool.
         sig do
           params(
             tool_id: String,

data/rbi/telnyx/resources/ai.rbi

@@ -17,6 +17,11 @@ module Telnyx
       sig { returns(Telnyx::Resources::AI::Clusters) }
       attr_reader :clusters
 
+      # Create and manage logical collections of your Telnyx data, tune retrieval
+      # settings, manage sources, and run collection-scoped semantic search.
+      sig { returns(Telnyx::Resources::AI::Collections) }
+      attr_reader :collections
+
       # Manage historical AI assistant conversations
       sig { returns(Telnyx::Resources::AI::Conversations) }
       attr_reader :conversations
@@ -91,13 +96,11 @@ module Telnyx
       #
       # **Examples:**
       #
-      # ```
-      # GET /v2/ai/conversation_histories?q=billing+issue&page[size]=10
-      # GET /v2/ai/conversation_histories?q=setup+guide&region=USA&min_score=0.5
-      # GET /v2/ai/conversation_histories?q=refund&filter[record_created_at][gte]=2026-01-01T00:00:00Z
-      # GET /v2/ai/conversation_histories?q=outage&filter[region][in]=USA,DEU
-      # GET /v2/ai/conversation_histories?q=hold+time&filter[language]=en
-      # ```
+      # - `GET /v2/ai/conversation_histories?q=billing+issue&page[size]=10`
+      # - `GET /v2/ai/conversation_histories?q=setup+guide&region=USA&min_score=0.5`
+      # - `GET /v2/ai/conversation_histories?q=refund&filter[record_created_at][gte]=2026-01-01T00:00:00Z`
+      # - `GET /v2/ai/conversation_histories?q=outage&filter[region][in]=USA,DEU`
+      # - `GET /v2/ai/conversation_histories?q=hold+time&filter[language]=en`
       sig do
         params(
           q: String,

data/rbi/telnyx/resources/available_phone_number_blocks.rbi

@@ -4,7 +4,9 @@ module Telnyx
   module Resources
     # Number search
     class AvailablePhoneNumberBlocks
-      # List available phone number blocks
+      # Searches the Telnyx inventory for available contiguous phone-number blocks.
+      # Results can be filtered by locality, country, national destination code, and
+      # number type.
       sig do
         params(
           filter: Telnyx::AvailablePhoneNumberBlockListParams::Filter::OrHash,

data/rbi/telnyx/resources/available_phone_numbers.rbi

@@ -4,7 +4,10 @@ module Telnyx
   module Resources
     # Number search
     class AvailablePhoneNumbers
-      # List available phone numbers
+      # Searches the Telnyx inventory for available phone numbers. Filters support
+      # number patterns, location, number type, features, reservability, and other
+      # inventory constraints; the response includes matching numbers and search
+      # metadata.
       sig do
         params(
           filter: Telnyx::AvailablePhoneNumberListParams::Filter::OrHash,

data/rbi/telnyx/resources/balance.rbi

@@ -4,7 +4,8 @@ module Telnyx
   module Resources
     # Billing operations
     class Balance
-      # Get user balance details
+      # Retrieve the current balance, available credit, and credit limit for your
+      # account.
       sig do
         params(request_options: Telnyx::RequestOptions::OrHash).returns(
           Telnyx::Models::BalanceRetrieveResponse

data/rbi/telnyx/resources/billing_groups.rbi

@@ -4,7 +4,8 @@ module Telnyx
   module Resources
     # Billing groups operations
     class BillingGroups
-      # Create a billing group
+      # Create a new billing group, which can be used to organize resources for billing
+      # purposes.
       sig do
         params(
           name: String,
@@ -18,7 +19,7 @@ module Telnyx
       )
       end
 
-      # Get a billing group
+      # Retrieve the details of a specific billing group.
       sig do
         params(
           id: String,
@@ -32,7 +33,7 @@ module Telnyx
       )
       end
 
-      # Update a billing group
+      # Update the properties of an existing billing group.
       sig do
         params(
           id: String,
@@ -49,7 +50,7 @@ module Telnyx
       )
       end
 
-      # List all billing groups
+      # Retrieve a paginated list of billing groups on your account.
       sig do
         params(
           page_number: Integer,
@@ -60,7 +61,7 @@ module Telnyx
       def list(page_number: nil, page_size: nil, request_options: {})
       end
 
-      # Delete a billing group
+      # Delete a billing group from your account.
       sig do
         params(
           id: String,

data/rbi/telnyx/resources/calls/actions.rbi

@@ -109,7 +109,7 @@ module Telnyx
             webhook_url: String,
             webhook_url_method:
               Telnyx::Calls::ActionAnswerParams::WebhookURLMethod::OrSymbol,
-            webhook_urls: T::Hash[Symbol, String],
+            webhook_urls: T::Hash[Symbol, T::Array[String]],
             webhook_urls_method:
               Telnyx::Calls::ActionAnswerParams::WebhookURLsMethod::OrSymbol,
             request_options: Telnyx::RequestOptions::OrHash
@@ -208,9 +208,10 @@ module Telnyx
           webhook_url: nil,
           # HTTP request type used for `webhook_url`.
           webhook_url_method: nil,
-          # A map of event types to webhook URLs. When an event of the specified type
-          # occurs, the webhook URL associated with that event type will be called instead
-          # of `webhook_url`. Events not mapped here will use the default `webhook_url`.
+          # A map of event types to arrays of webhook URLs. When an event of the specified
+          # type occurs, the webhook URLs associated with that event type will be called
+          # instead of `webhook_url`. Events not mapped here will use the default
+          # `webhook_url`.
           webhook_urls: nil,
           # HTTP request method to invoke `webhook_urls`.
           webhook_urls_method: nil,
@@ -1579,7 +1580,8 @@ module Telnyx
         )
         end
 
-        # Noise Suppression Start (BETA)
+        # Start noise suppression on an active call to reduce background noise. This
+        # feature is currently in beta.
         sig do
           params(
             call_control_id: String,
@@ -2064,7 +2066,8 @@ module Telnyx
         )
         end
 
-        # Noise Suppression Stop (BETA)
+        # Stop noise suppression previously started on an active call. This feature is
+        # currently in beta.
         sig do
           params(
             call_control_id: String,
@@ -2319,7 +2322,7 @@ module Telnyx
             webhook_url: String,
             webhook_url_method:
               Telnyx::Calls::ActionTransferParams::WebhookURLMethod::OrSymbol,
-            webhook_urls: T::Hash[Symbol, String],
+            webhook_urls: T::Hash[Symbol, T::Array[String]],
             webhook_urls_method:
               Telnyx::Calls::ActionTransferParams::WebhookURLsMethod::OrSymbol,
             request_options: Telnyx::RequestOptions::OrHash
@@ -2481,9 +2484,10 @@ module Telnyx
           webhook_url: nil,
           # HTTP request type used for `webhook_url`.
           webhook_url_method: nil,
-          # A map of event types to webhook URLs. When an event of the specified type
-          # occurs, the webhook URL associated with that event type will be called instead
-          # of `webhook_url`. Events not mapped here will use the default `webhook_url`.
+          # A map of event types to arrays of webhook URLs. When an event of the specified
+          # type occurs, the webhook URLs associated with that event type will be called
+          # instead of `webhook_url`. Events not mapped here will use the default
+          # `webhook_url`.
           webhook_urls: nil,
           # HTTP request method to invoke `webhook_urls`.
           webhook_urls_method: nil,

data/rbi/telnyx/resources/calls.rbi

@@ -108,7 +108,7 @@ module Telnyx
           webhook_url: String,
           webhook_url_method:
             Telnyx::CallDialParams::WebhookURLMethod::OrSymbol,
-          webhook_urls: T::Hash[Symbol, String],
+          webhook_urls: T::Hash[Symbol, T::Array[String]],
           webhook_urls_method:
             Telnyx::CallDialParams::WebhookURLsMethod::OrSymbol,
           request_options: Telnyx::RequestOptions::OrHash
@@ -350,10 +350,10 @@ module Telnyx
         webhook_url: nil,
         # HTTP request type used for `webhook_url`.
         webhook_url_method: nil,
-        # A map of event types to webhook URLs. When an event of the specified type
-        # occurs, the webhook URL associated with that event type will be called instead
-        # of the default webhook URL. Events not mapped here will use the default webhook
-        # URL.
+        # A map of event types to arrays of webhook URLs. When an event of the specified
+        # type occurs, the webhook URLs associated with that event type will be called
+        # instead of the default webhook URL. Events not mapped here will use the default
+        # webhook URL.
         webhook_urls: nil,
         # HTTP request method to invoke `webhook_urls`.
         webhook_urls_method: nil,

data/rbi/telnyx/resources/comments.rbi

@@ -4,7 +4,8 @@ module Telnyx
   module Resources
     # Number orders
     class Comments
-      # Create a comment
+      # Creates a comment associated with a supported number-order record. The response
+      # contains the created comment.
       sig do
         params(
           body: String,
@@ -21,7 +22,8 @@ module Telnyx
       )
       end
 
-      # Retrieve a comment
+      # Returns the comment identified by `id`, including its associated record and
+      # comment metadata.
       sig do
         params(
           id: String,
@@ -35,7 +37,8 @@ module Telnyx
       )
       end
 
-      # Retrieve all comments
+      # Returns comments associated with number-order records. Results can be filtered
+      # by record type and record ID and include pagination metadata.
       sig do
         params(
           filter: Telnyx::CommentListParams::Filter::OrHash,
@@ -50,7 +53,8 @@ module Telnyx
       )
       end
 
-      # Mark a comment as read
+      # Marks the specified comment as read. The response contains the updated read
+      # state for the comment.
       sig do
         params(
           id: String,

data/rbi/telnyx/resources/credential_connections.rbi

@@ -146,6 +146,7 @@ module Telnyx
           android_push_credential_id: T.nilable(String),
           call_cost_in_webhooks: T::Boolean,
           connection_name: String,
+          conversation_persistence: T::Boolean,
           default_on_hold_comfort_noise_enabled: T::Boolean,
           dtmf_type: Telnyx::DtmfType::OrSymbol,
           encode_contact_header_enabled: T::Boolean,
@@ -187,6 +188,10 @@ module Telnyx
         call_cost_in_webhooks: nil,
         # A user-assigned name to help manage the connection.
         connection_name: nil,
+        # Whether conversation persistence is enabled for this connection. When enabled,
+        # calls handled by the connection are transcribed, stored, and indexed. Defaults
+        # to false.
+        conversation_persistence: nil,
         # When enabled, Telnyx will generate comfort noise when you place the call on
         # hold. If disabled, you will need to generate comfort noise or on hold music to
         # avoid RTP timeout.

data/rbi/telnyx/resources/email_blocks.rbi

@@ -39,7 +39,8 @@ module Telnyx
       )
       end
 
-      # Retrieve a suppression
+      # Returns the account-owned suppression identified by ID. Cross-account lookups
+      # and malformed IDs return `404` without exposing another account’s data.
       sig do
         params(
           id: String,

data/rbi/telnyx/resources/email_domains/webhooks.rbi

@@ -27,7 +27,8 @@ module Telnyx
         )
         end
 
-        # Retrieve a webhook
+        # Returns the webhook subscription identified by ID within the specified email
+        # domain.
         sig do
           params(
             id: String,
@@ -68,7 +69,8 @@ module Telnyx
         )
         end
 
-        # List webhooks for an email domain
+        # Returns a paginated list of webhook subscriptions scoped to the email domain.
+        # Results can be sorted by creation time.
         sig do
           params(
             domain_id: String,
@@ -95,7 +97,8 @@ module Telnyx
         )
         end
 
-        # Delete a webhook
+        # Deletes the webhook subscription identified by ID within the specified email
+        # domain and returns the deleted subscription.
         sig do
           params(
             id: String,

data/rbi/telnyx/resources/email_domains.rbi

@@ -7,7 +7,8 @@ module Telnyx
       sig { returns(Telnyx::Resources::EmailDomains::Webhooks) }
       attr_reader :webhooks
 
-      # Create an email domain
+      # Registers a domain for email sending and optional inbound delivery. The response
+      # includes the domain configuration and current verification state.
       sig do
         params(
           domain: String,
@@ -46,7 +47,9 @@ module Telnyx
       )
       end
 
-      # Update an email domain
+      # Updates mutable settings for an existing email domain, including inbound
+      # delivery and tracking configuration. Shared domains are read-only for non-owner
+      # accounts.
       sig do
         params(
           id: String,
@@ -112,7 +115,8 @@ module Telnyx
       )
       end
 
-      # Delete an email domain
+      # Deletes an email domain configuration. Verified domains require `force=true`,
+      # and shared domains are read-only for non-owner accounts.
       sig do
         params(
           id: String,
@@ -129,7 +133,8 @@ module Telnyx
       )
       end
 
-      # List DNS records for an email domain
+      # Returns the DNS records Telnyx generated for domain ownership and DKIM
+      # verification, plus MX records when inbound delivery is enabled.
       sig do
         params(
           domain_id: String,
@@ -157,7 +162,8 @@ module Telnyx
       )
       end
 
-      # Verify DNS records for an email domain
+      # Checks the published DNS records against the records required for the email
+      # domain and returns the latest verification results.
       sig do
         params(
           domain_id: String,

data/rbi/telnyx/resources/email_templates.rbi

@@ -41,7 +41,8 @@ module Telnyx
       )
       end
 
-      # Get an email template
+      # Returns the account-owned template identified by ID, including its Liquid
+      # subject and bodies, declared variables, and timestamps.
       sig do
         params(
           id: String,
@@ -100,7 +101,8 @@ module Telnyx
       )
       end
 
-      # Delete an email template
+      # Deletes the account-owned template. The operation returns `204` with no body and
+      # prevents future sends or renders from using the deleted template ID.
       sig do
         params(id: String, request_options: Telnyx::RequestOptions::OrHash).void
       end

data/rbi/telnyx/resources/email_unsubscribe_groups.rbi

@@ -8,7 +8,8 @@ module Telnyx
       sig { returns(Telnyx::Resources::EmailUnsubscribeGroups::Suppressions) }
       attr_reader :suppressions
 
-      # Create an unsubscribe group
+      # Creates an account-owned unsubscribe group for associating email categories with
+      # separate recipient suppression lists.
       sig do
         params(
           name: String,
@@ -19,7 +20,7 @@ module Telnyx
       def create(name:, description: nil, request_options: {})
       end
 
-      # Retrieve an unsubscribe group
+      # Returns the account-owned unsubscribe group identified by ID.
       sig do
         params(
           id: String,