telnyx 5.162.0 → 5.164.0

data/lib/telnyx/resources/ai/assistants.rb

@@ -36,65 +36,68 @@ module Telnyx
         # Some parameter documentations has been truncated, see
         # {Telnyx::Models::AI::AssistantCreateParams} for more details.
         #
-        # Create a new AI Assistant.
+        # Creates a new AI assistant from the provided configuration, including its model,
+        # instructions, and attached tools, and returns the created assistant.
         #
-        # @overload create(instructions:, name:, conversation_flow: nil, description: nil, dynamic_variables: nil, dynamic_variables_webhook_timeout_ms: nil, dynamic_variables_webhook_url: nil, enabled_features: nil, external_llm: nil, fallback_config: nil, greeting: nil, insight_settings: nil, integrations: nil, interruption_settings: nil, llm_api_key_ref: nil, mcp_servers: nil, messaging_settings: nil, model: nil, observability_settings: nil, post_conversation_settings: nil, privacy_settings: nil, tags: nil, telephony_settings: nil, tool_ids: nil, tools: nil, transcription: nil, voice_settings: nil, widget_settings: nil, request_options: {})
+        # @overload create(instructions:, name:, conversation_flow: nil, description: nil, dynamic_variables: nil, dynamic_variables_webhook_timeout_ms: nil, dynamic_variables_webhook_url: nil, enabled_features: nil, external_llm: nil, fallback_config: nil, greeting: nil, insight_settings: nil, integrations: nil, interruption_settings: nil, llm_api_key_ref: nil, mcp_servers: nil, messaging_settings: nil, model: nil, observability_settings: nil, post_conversation_settings: nil, privacy_settings: nil, tags: nil, telephony_settings: nil, tool_ids: nil, tools: nil, transcription: nil, voice_settings: nil, widget_settings: nil, idempotency_key: nil, request_options: {})
         #
-        # @param instructions [String] System instructions for the assistant. These may be templated with [dynamic vari
+        # @param instructions [String] Body param: System instructions for the assistant. These may be templated with [
         #
-        # @param name [String]
+        # @param name [String] Body param
         #
-        # @param conversation_flow [Telnyx::Models::AI::ConversationFlowReq] Conversation flow as supplied by API clients (create / update).
+        # @param conversation_flow [Telnyx::Models::AI::ConversationFlowReq] Body param: Conversation flow as supplied by API clients (create / update).
         #
-        # @param description [String]
+        # @param description [String] Body param
         #
-        # @param dynamic_variables [Hash{Symbol=>Object}] Map of dynamic variables and their default values
+        # @param dynamic_variables [Hash{Symbol=>Object}] Body param: Map of dynamic variables and their default values
         #
-        # @param dynamic_variables_webhook_timeout_ms [Integer] Timeout in milliseconds for the dynamic variables webhook. Must be between 1 and
+        # @param dynamic_variables_webhook_timeout_ms [Integer] Body param: Timeout in milliseconds for the dynamic variables webhook. Must be b
         #
-        # @param dynamic_variables_webhook_url [String] If `dynamic_variables_webhook_url` is set, Telnyx sends a POST request to this U
+        # @param dynamic_variables_webhook_url [String] Body param: If `dynamic_variables_webhook_url` is set, Telnyx sends a POST reque
         #
-        # @param enabled_features [Array<Symbol, Telnyx::Models::AI::EnabledFeatures>]
+        # @param enabled_features [Array<Symbol, Telnyx::Models::AI::EnabledFeatures>] Body param
         #
-        # @param external_llm [Telnyx::Models::AI::ExternalLlmReq]
+        # @param external_llm [Telnyx::Models::AI::ExternalLlmReq] Body param
         #
-        # @param fallback_config [Telnyx::Models::AI::FallbackConfigReq]
+        # @param fallback_config [Telnyx::Models::AI::FallbackConfigReq] Body param
         #
-        # @param greeting [String] Text that the assistant will use to start the conversation. This may be template
+        # @param greeting [String] Body param: Text that the assistant will use to start the conversation. This may
         #
-        # @param insight_settings [Telnyx::Models::AI::InsightSettings]
+        # @param insight_settings [Telnyx::Models::AI::InsightSettings] Body param
         #
-        # @param integrations [Array<Telnyx::Models::AI::AssistantIntegration>] Connected integrations attached to the assistant. The catalog of available integ
+        # @param integrations [Array<Telnyx::Models::AI::AssistantIntegration>] Body param: Connected integrations attached to the assistant. The catalog of ava
         #
-        # @param interruption_settings [Telnyx::Models::AI::InferenceEmbeddingInterruptionSettings] Settings for interruptions and how the assistant decides the user has finished s
+        # @param interruption_settings [Telnyx::Models::AI::InferenceEmbeddingInterruptionSettings] Body param: Settings for interruptions and how the assistant decides the user ha
         #
-        # @param llm_api_key_ref [String] This is only needed when using third-party inference providers selected by `mode
+        # @param llm_api_key_ref [String] Body param: This is only needed when using third-party inference providers selec
         #
-        # @param mcp_servers [Array<Telnyx::Models::AI::AssistantMcpServer>] MCP servers attached to the assistant. Create MCP servers with `/ai/mcp_servers`
+        # @param mcp_servers [Array<Telnyx::Models::AI::AssistantMcpServer>] Body param: MCP servers attached to the assistant. Create MCP servers with `/ai/
         #
-        # @param messaging_settings [Telnyx::Models::AI::MessagingSettings]
+        # @param messaging_settings [Telnyx::Models::AI::MessagingSettings] Body param
         #
-        # @param model [String] ID of the model to use when `external_llm` is not set. You can use the [Get mode
+        # @param model [String] Body param: ID of the model to use when `external_llm` is not set. You can use t
         #
-        # @param observability_settings [Telnyx::Models::AI::ObservabilityReq]
+        # @param observability_settings [Telnyx::Models::AI::ObservabilityReq] Body param
         #
-        # @param post_conversation_settings [Telnyx::Models::AI::PostConversationSettingsReq] Configuration for post-conversation processing. When enabled, the assistant rece
+        # @param post_conversation_settings [Telnyx::Models::AI::PostConversationSettingsReq] Body param: Configuration for post-conversation processing. When enabled, the as
         #
-        # @param privacy_settings [Telnyx::Models::AI::PrivacySettings]
+        # @param privacy_settings [Telnyx::Models::AI::PrivacySettings] Body param
         #
-        # @param tags [Array<String>] Tags associated with the assistant. Tags can also be managed with the assistant
+        # @param tags [Array<String>] Body param: Tags associated with the assistant. Tags can also be managed with th
         #
-        # @param telephony_settings [Telnyx::Models::AI::TelephonySettings]
+        # @param telephony_settings [Telnyx::Models::AI::TelephonySettings] Body param
         #
-        # @param tool_ids [Array<String>] IDs of shared tools to attach to the assistant. New integrations should prefer `
+        # @param tool_ids [Array<String>] Body param: IDs of shared tools to attach to the assistant. New integrations sho
         #
-        # @param tools [Array<Telnyx::Models::AI::InferenceEmbeddingWebhookToolParams, Telnyx::Models::AI::AssistantTool::ClientSideTool, Telnyx::Models::AI::RetrievalTool, Telnyx::Models::AI::AssistantTool::Handoff, Telnyx::Models::AI::HangupTool, Telnyx::Models::AI::AssistantTool::Transfer, Telnyx::Models::AI::AssistantTool::Invite, Telnyx::Models::AI::AssistantTool::Refer, Telnyx::Models::AI::AssistantTool::SendDtmf, Telnyx::Models::AI::AssistantTool::SendMessage, Telnyx::Models::AI::AssistantTool::SkipTurn, Telnyx::Models::AI::AssistantTool::Pay, Telnyx::Models::AI::AssistantTool::UpdateDynamicVariables>] Deprecated for new integrations. Inline tool definitions available to the assist
+        # @param tools [Array<Telnyx::Models::AI::InferenceEmbeddingWebhookToolParams, Telnyx::Models::AI::AssistantTool::ClientSideTool, Telnyx::Models::AI::RetrievalTool, Telnyx::Models::AI::AssistantTool::Handoff, Telnyx::Models::AI::HangupTool, Telnyx::Models::AI::AssistantTool::Transfer, Telnyx::Models::AI::AssistantTool::Invite, Telnyx::Models::AI::AssistantTool::Refer, Telnyx::Models::AI::AssistantTool::SendDtmf, Telnyx::Models::AI::AssistantTool::SendMessage, Telnyx::Models::AI::AssistantTool::SkipTurn, Telnyx::Models::AI::AssistantTool::Pay, Telnyx::Models::AI::AssistantTool::UpdateDynamicVariables>] Body param: Deprecated for new integrations. Inline tool definitions available t
         #
-        # @param transcription [Telnyx::Models::AI::TranscriptionSettings]
+        # @param transcription [Telnyx::Models::AI::TranscriptionSettings] Body param
         #
-        # @param voice_settings [Telnyx::Models::AI::VoiceSettings]
+        # @param voice_settings [Telnyx::Models::AI::VoiceSettings] Body param
         #
-        # @param widget_settings [Telnyx::Models::AI::WidgetSettings] Configuration settings for the assistant's web widget.
+        # @param widget_settings [Telnyx::Models::AI::WidgetSettings] Body param: Configuration settings for the assistant's web widget.
+        #
+        # @param idempotency_key [String] Header param: Optional opaque, unquoted key for safely retrying the same logical
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -103,10 +106,12 @@ module Telnyx
         # @see Telnyx::Models::AI::AssistantCreateParams
         def create(params)
           parsed, options = Telnyx::AI::AssistantCreateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :post,
             path: "ai/assistants",
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Telnyx::AI::InferenceEmbedding,
             options: options
           )
@@ -146,7 +151,9 @@ module Telnyx
         # Some parameter documentations has been truncated, see
         # {Telnyx::Models::AI::AssistantUpdateParams} for more details.
         #
-        # Update an AI Assistant's attributes.
+        # Updates the specified AI assistant's attributes and returns the updated
+        # assistant. The request can also control how the change is promoted across
+        # assistant versions.
         #
         # @overload update(assistant_id, conversation_flow: nil, description: nil, dynamic_variables: nil, dynamic_variables_webhook_timeout_ms: nil, dynamic_variables_webhook_url: nil, enabled_features: nil, external_llm: nil, fallback_config: nil, greeting: nil, insight_settings: nil, instructions: nil, integrations: nil, interruption_settings: nil, llm_api_key_ref: nil, mcp_servers: nil, messaging_settings: nil, model: nil, name: nil, observability_settings: nil, post_conversation_settings: nil, privacy_settings: nil, promote_to_main: nil, tags: nil, telephony_settings: nil, tool_ids: nil, tools: nil, transcription: nil, version_name: nil, voice_settings: nil, widget_settings: nil, request_options: {})
         #
@@ -306,23 +313,30 @@ module Telnyx
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::AI::AssistantCloneParams} for more details.
+        #
         # Clone an existing assistant, excluding telephony and messaging settings.
         #
-        # @overload clone_(assistant_id, request_options: {})
+        # @overload clone_(assistant_id, idempotency_key: nil, request_options: {})
         #
         # @param assistant_id [String] Unique identifier of the assistant.
         #
+        # @param idempotency_key [String] Optional opaque, unquoted key for safely retrying the same logical request. Keys
+        #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [Telnyx::Models::AI::InferenceEmbedding]
         #
         # @see Telnyx::Models::AI::AssistantCloneParams
         def clone_(assistant_id, params = {})
+          parsed, options = Telnyx::AI::AssistantCloneParams.dump_request(params)
           @client.request(
             method: :post,
             path: ["ai/assistants/%1$s/clone", assistant_id],
+            headers: parsed.transform_keys(idempotency_key: "idempotency-key"),
             model: Telnyx::AI::InferenceEmbedding,
-            options: params[:request_options]
+            options: options
           )
         end
 
@@ -353,13 +367,15 @@ module Telnyx
         # imported will be overwritten with its latest version from the importing
         # provider.
         #
-        # @overload imports(api_key_ref:, provider:, import_ids: nil, request_options: {})
+        # @overload imports(api_key_ref:, provider:, import_ids: nil, idempotency_key: nil, request_options: {})
         #
-        # @param api_key_ref [String] Integration secret pointer that refers to the API key for the external provider.
+        # @param api_key_ref [String] Body param: Integration secret pointer that refers to the API key for the extern
         #
-        # @param provider [Symbol, Telnyx::Models::AI::AssistantImportsParams::Provider] The external provider to import assistants from.
+        # @param provider [Symbol, Telnyx::Models::AI::AssistantImportsParams::Provider] Body param: The external provider to import assistants from.
         #
-        # @param import_ids [Array<String>] Optional list of assistant IDs to import from the external provider. If not prov
+        # @param import_ids [Array<String>] Body param: Optional list of assistant IDs to import from the external provider.
+        #
+        # @param idempotency_key [String] Header param: Optional opaque, unquoted key for safely retrying the same logical
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -368,15 +384,20 @@ module Telnyx
         # @see Telnyx::Models::AI::AssistantImportsParams
         def imports(params)
           parsed, options = Telnyx::AI::AssistantImportsParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :post,
             path: "ai/assistants/import",
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Telnyx::AI::AssistantsList,
             options: options
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::AI::AssistantSendSMSParams} for more details.
+        #
         # Send an SMS message for an assistant. This endpoint:
         #
         # 1. Validates the assistant exists and has messaging profile configured
@@ -389,19 +410,21 @@ module Telnyx
         # 4. Updates conversation metadata if provided
         # 5. Returns the conversation ID
         #
-        # @overload send_sms(assistant_id, from:, to:, conversation_metadata: nil, should_create_conversation: nil, text: nil, request_options: {})
+        # @overload send_sms(assistant_id, from:, to:, conversation_metadata: nil, should_create_conversation: nil, text: nil, idempotency_key: nil, request_options: {})
         #
-        # @param assistant_id [String] Unique identifier of the assistant.
+        # @param assistant_id [String] Path param: Unique identifier of the assistant.
         #
-        # @param from [String]
+        # @param from [String] Body param
         #
-        # @param to [String]
+        # @param to [String] Body param
         #
-        # @param conversation_metadata [Hash{Symbol=>String, Integer, Boolean}]
+        # @param conversation_metadata [Hash{Symbol=>String, Integer, Boolean}] Body param
         #
-        # @param should_create_conversation [Boolean]
+        # @param should_create_conversation [Boolean] Body param
         #
-        # @param text [String]
+        # @param text [String] Body param
+        #
+        # @param idempotency_key [String] Header param: Optional opaque, unquoted key for safely retrying the same logical
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -410,10 +433,12 @@ module Telnyx
         # @see Telnyx::Models::AI::AssistantSendSMSParams
         def send_sms(assistant_id, params)
           parsed, options = Telnyx::AI::AssistantSendSMSParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :post,
             path: ["ai/assistants/%1$s/chat/sms", assistant_id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Telnyx::Models::AI::AssistantSendSMSResponse,
             options: options
           )

data/lib/telnyx/resources/ai/collections/sources.rb

@@ -10,7 +10,9 @@ module Telnyx
           # Some parameter documentations has been truncated, see
           # {Telnyx::Models::AI::Collections::SourceCreateParams} for more details.
           #
-          # Attaches a new source to a collection.
+          # Attaches a new content source to the specified collection and returns the
+          # created source. The source's content is ingested and embedded so it becomes
+          # searchable within the collection.
           #
           # @overload create(uuid, source_type:, bucket_id: nil, request_options: {})
           #

data/lib/telnyx/resources/ai/collections.rb

@@ -162,74 +162,6 @@ module Telnyx
           )
         end
 
-        # Some parameter documentations has been truncated, see
-        # {Telnyx::Models::AI::CollectionRetrieveDocumentsParams} for more details.
-        #
-        # 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`
-        #
-        # @overload retrieve_documents(slug, filter: nil, page_number: nil, page_size: nil, query: nil, retrieval_type: nil, sources: nil, top_k: nil, request_options: {})
-        #
-        # @param slug [String] The collection's slug (unique within your organization).
-        #
-        # @param filter [Hash{Symbol=>Object}] Field filters applied before ranking, using `filter[field][operator]=value`. Sup
-        #
-        # @param page_number [Integer] Page number to return (1-based). Defaults to 1.
-        #
-        # @param page_size [Integer] Number of results per page. Defaults to 20.
-        #
-        # @param query [String] Natural-language search query. When provided, the text is matched against the co
-        #
-        # @param retrieval_type [Symbol, Telnyx::Models::AI::CollectionRetrieveDocumentsParams::RetrievalType] Override the collection's configured retrieval strategy for this request. Echoed
-        #
-        # @param sources [String] Comma-separated list of source types to restrict the search to. When omitted, al
-        #
-        # @param top_k [Integer] Maximum number of ranked results to consider. When omitted, the collection's con
-        #
-        # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
-        #
-        # @return [Telnyx::Models::AI::CollectionRetrieveDocumentsResponse]
-        #
-        # @see Telnyx::Models::AI::CollectionRetrieveDocumentsParams
-        def retrieve_documents(slug, params = {})
-          parsed, options = Telnyx::AI::CollectionRetrieveDocumentsParams.dump_request(params)
-          query = Telnyx::Internal::Util.encode_query_params(parsed)
-          @client.request(
-            method: :get,
-            path: ["ai/collections/%1$s/documents", slug],
-            query: query.transform_keys(page_number: "page[number]", page_size: "page[size]"),
-            model: Telnyx::Models::AI::CollectionRetrieveDocumentsResponse,
-            options: options
-          )
-        end
-
         # @api private
         #
         # @param client [Telnyx::Client]

data/lib/telnyx/resources/ai/conversations/insight_groups/insights.rb

@@ -7,7 +7,7 @@ module Telnyx
         class InsightGroups
           # Manage historical AI assistant conversations
           class Insights
-            # Assign an insight to a group
+            # Assigns the specified insight template to the specified insight template group.
             #
             # @overload assign(insight_id, group_id:, request_options: {})
             #
@@ -34,7 +34,8 @@ module Telnyx
               )
             end
 
-            # Remove an insight from a group
+            # Removes the specified insight template from the specified group. The insight
+            # template itself is not deleted.
             #
             # @overload delete_unassign(insight_id, group_id:, request_options: {})
             #

data/lib/telnyx/resources/ai/conversations/insight_groups.rb

@@ -10,7 +10,8 @@ module Telnyx
           # @return [Telnyx::Resources::AI::Conversations::InsightGroups::Insights]
           attr_reader :insights
 
-          # Get insight group by ID
+          # Returns the details of a single insight template group, including the insight
+          # templates assigned to it.
           #
           # @overload retrieve(group_id, request_options: {})
           #
@@ -30,7 +31,7 @@ module Telnyx
             )
           end
 
-          # Update an insight template group
+          # Updates the specified insight template group and returns the updated group.
           #
           # @overload update(group_id, description: nil, name: nil, webhook: nil, request_options: {})
           #
@@ -58,7 +59,7 @@ module Telnyx
             )
           end
 
-          # Delete insight group by ID
+          # Permanently deletes the specified insight template group by its ID.
           #
           # @overload delete(group_id, request_options: {})
           #
@@ -78,13 +79,23 @@ module Telnyx
             )
           end
 
-          # Create a new insight group
+          # Some parameter documentations has been truncated, see
+          # {Telnyx::Models::AI::Conversations::InsightGroupInsightGroupsParams} for more
+          # details.
           #
-          # @overload insight_groups(name:, description: nil, webhook: nil, request_options: {})
+          # Creates a new insight template group for organizing related insight templates,
+          # and returns the created group.
+          #
+          # @overload insight_groups(name:, description: nil, webhook: nil, idempotency_key: nil, request_options: {})
+          #
+          # @param name [String] Body param
+          #
+          # @param description [String] Body param
+          #
+          # @param webhook [String] Body param
+          #
+          # @param idempotency_key [String] Header param: Optional opaque, unquoted key for safely retrying the same logical
           #
-          # @param name [String]
-          # @param description [String]
-          # @param webhook [String]
           # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
           #
           # @return [Telnyx::Models::AI::Conversations::InsightTemplateGroupDetail]
@@ -92,16 +103,20 @@ module Telnyx
           # @see Telnyx::Models::AI::Conversations::InsightGroupInsightGroupsParams
           def insight_groups(params)
             parsed, options = Telnyx::AI::Conversations::InsightGroupInsightGroupsParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :post,
               path: "ai/conversations/insight-groups",
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: Telnyx::AI::Conversations::InsightTemplateGroupDetail,
               options: options
             )
           end
 
-          # Get all insight groups
+          # Returns a paginated list of your insight template groups. Groups organize
+          # related insight templates that are applied together when analyzing
+          # conversations.
           #
           # @overload retrieve_insight_groups(page_number: nil, page_size: nil, request_options: {})
           #

data/lib/telnyx/resources/ai/conversations/insights.rb

@@ -6,17 +6,23 @@ module Telnyx
       class Conversations
         # Manage historical AI assistant conversations
         class Insights
-          # Create a new insight
+          # Some parameter documentations has been truncated, see
+          # {Telnyx::Models::AI::Conversations::InsightCreateParams} for more details.
           #
-          # @overload create(instructions:, name:, json_schema: nil, webhook: nil, request_options: {})
+          # Creates a new insight template defining an analysis to run over conversations,
+          # and returns the created template.
           #
-          # @param instructions [String]
+          # @overload create(instructions:, name:, json_schema: nil, webhook: nil, idempotency_key: nil, request_options: {})
           #
-          # @param name [String]
+          # @param instructions [String] Body param
           #
-          # @param json_schema [String, Hash{Symbol=>Object}] If specified, the output will follow the JSON schema.
+          # @param name [String] Body param
           #
-          # @param webhook [String]
+          # @param json_schema [String, Hash{Symbol=>Object}] Body param: If specified, the output will follow the JSON schema.
+          #
+          # @param webhook [String] Body param
+          #
+          # @param idempotency_key [String] Header param: Optional opaque, unquoted key for safely retrying the same logical
           #
           # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
           #
@@ -25,16 +31,19 @@ module Telnyx
           # @see Telnyx::Models::AI::Conversations::InsightCreateParams
           def create(params)
             parsed, options = Telnyx::AI::Conversations::InsightCreateParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key"}
             @client.request(
               method: :post,
               path: "ai/conversations/insights",
-              body: parsed,
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
               model: Telnyx::AI::Conversations::InsightTemplateDetail,
               options: options
             )
           end
 
-          # Get insight by ID
+          # Returns the details of a single insight template by its ID, including its
+          # configuration.
           #
           # @overload retrieve(insight_id, request_options: {})
           #
@@ -54,7 +63,7 @@ module Telnyx
             )
           end
 
-          # Update an insight template
+          # Updates the specified insight template and returns the updated template.
           #
           # @overload update(insight_id, instructions: nil, json_schema: nil, name: nil, webhook: nil, request_options: {})
           #
@@ -84,7 +93,8 @@ module Telnyx
             )
           end
 
-          # Get all insights
+          # Returns a paginated list of your insight templates. Insight templates define
+          # analyses that run over AI conversations to extract structured findings.
           #
           # @overload list(page_number: nil, page_size: nil, request_options: {})
           #
@@ -108,7 +118,7 @@ module Telnyx
             )
           end
 
-          # Delete insight by ID
+          # Permanently deletes the specified insight template by its ID.
           #
           # @overload delete(insight_id, request_options: {})
           #

data/lib/telnyx/resources/ai/conversations.rb

@@ -24,13 +24,16 @@ module Telnyx
         # Some parameter documentations has been truncated, see
         # {Telnyx::Models::AI::ConversationCreateParams} for more details.
         #
-        # Create a new AI Conversation.
+        # Creates a new AI conversation, the container for messages exchanged with an
+        # assistant, and returns the created conversation.
         #
-        # @overload create(metadata: nil, name: nil, request_options: {})
+        # @overload create(metadata: nil, name: nil, idempotency_key: nil, request_options: {})
         #
-        # @param metadata [Hash{Symbol=>String}] Metadata associated with the conversation. Set `ai_disabled` to `true` to create
+        # @param metadata [Hash{Symbol=>String}] Body param: Metadata associated with the conversation. Set `ai_disabled` to `tru
         #
-        # @param name [String]
+        # @param name [String] Body param
+        #
+        # @param idempotency_key [String] Header param: Optional opaque, unquoted key for safely retrying the same logical
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -39,10 +42,12 @@ module Telnyx
         # @see Telnyx::Models::AI::ConversationCreateParams
         def create(params = {})
           parsed, options = Telnyx::AI::ConversationCreateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :post,
             path: "ai/conversations",
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Telnyx::AI::Conversation,
             options: options
           )
@@ -174,28 +179,33 @@ module Telnyx
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::AI::ConversationAddMessageParams} for more details.
+        #
         # Add a new message to the conversation. Used to insert a new messages to a
         # conversation manually ( without using chat endpoint )
         #
-        # @overload add_message(conversation_id, role:, content: nil, metadata: nil, name: nil, sent_at: nil, tool_call_id: nil, tool_calls: nil, tool_choice: nil, request_options: {})
+        # @overload add_message(conversation_id, role:, content: nil, metadata: nil, name: nil, sent_at: nil, tool_call_id: nil, tool_calls: nil, tool_choice: nil, idempotency_key: nil, request_options: {})
+        #
+        # @param conversation_id [String] Path param: The ID of the conversation
         #
-        # @param conversation_id [String] The ID of the conversation
+        # @param role [String] Body param
         #
-        # @param role [String]
+        # @param content [String] Body param
         #
-        # @param content [String]
+        # @param metadata [Hash{Symbol=>String, Integer, Boolean, Array<String, Integer, Boolean>}] Body param
         #
-        # @param metadata [Hash{Symbol=>String, Integer, Boolean, Array<String, Integer, Boolean>}]
+        # @param name [String] Body param
         #
-        # @param name [String]
+        # @param sent_at [Time] Body param
         #
-        # @param sent_at [Time]
+        # @param tool_call_id [String] Body param
         #
-        # @param tool_call_id [String]
+        # @param tool_calls [Array<Hash{Symbol=>Object}>] Body param
         #
-        # @param tool_calls [Array<Hash{Symbol=>Object}>]
+        # @param tool_choice [String, Hash{Symbol=>Object}] Body param
         #
-        # @param tool_choice [String, Hash{Symbol=>Object}]
+        # @param idempotency_key [String] Header param: Optional opaque, unquoted key for safely retrying the same logical
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -204,10 +214,12 @@ module Telnyx
         # @see Telnyx::Models::AI::ConversationAddMessageParams
         def add_message(conversation_id, params)
           parsed, options = Telnyx::AI::ConversationAddMessageParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key"}
           @client.request(
             method: :post,
             path: ["ai/conversations/%1$s/message", conversation_id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: NilClass,
             options: options
           )

data/lib/telnyx/resources/ai/embeddings/buckets.rb

@@ -27,7 +27,8 @@ module Telnyx
             )
           end
 
-          # Get all embedding buckets for a user.
+          # Returns the list of storage buckets that have been embedded for your account,
+          # for use with similarity search.
           #
           # @overload list(request_options: {})
           #