telnyx 5.169.0 → 5.171.0

data/rbi/telnyx/resources/ai/assistants/deleted.rbi

@@ -0,0 +1,58 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Assistants
+        # Configure AI assistant specifications
+        class Deleted
+          # List the organization's soft-deleted assistants in the Recently Deleted list.
+          #
+          # Each entry includes `deleted_at` and `permanently_deleted_at`, the point after
+          # which the assistant is erased automatically and can no longer be restored.
+          sig do
+            params(
+              page_number: Integer,
+              page_size: Integer,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Internal::DefaultFlatPagination[
+                Telnyx::AI::Assistants::DeletedAssistant
+              ]
+            )
+          end
+          def list(
+            # Page number to retrieve (1-based).
+            page_number: nil,
+            # Number of items to return per page.
+            page_size: nil,
+            request_options: {}
+          )
+          end
+
+          # Retrieve a soft-deleted assistant from the Recently Deleted list by
+          # `assistant_id`, including its `deleted_at` and `permanently_deleted_at`
+          # timestamps. This is a read-only view; the assistant cannot be modified while it
+          # remains deleted.
+          sig do
+            params(
+              assistant_id: String,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(Telnyx::AI::Assistants::DeletedAssistant)
+          end
+          def get(
+            # Unique identifier of the assistant.
+            assistant_id,
+            request_options: {}
+          )
+          end
+
+          # @api private
+          sig { params(client: Telnyx::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/assistants/versions.rbi

@@ -33,7 +33,10 @@ module Telnyx
               version_id: String,
               assistant_id: String,
               a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent::OrHash],
+              avatar_settings:
+                T.nilable(Telnyx::AI::AvatarSettingsRequest::OrHash),
               conversation_flow: Telnyx::AI::ConversationFlowReq::OrHash,
+              delegation_settings: Telnyx::AI::DelegationSettings::OrHash,
               description: String,
               dynamic_variables: T::Hash[Symbol, T.anything],
               dynamic_variables_webhook_timeout_ms: Integer,
@@ -80,7 +83,9 @@ module Telnyx
                 ],
               transcription: Telnyx::AI::TranscriptionSettings::OrHash,
               version_name: String,
-              voice_settings: Telnyx::AI::VoiceSettings::OrHash,
+              voice_settings:
+                Telnyx::AI::InferenceEmbeddingVoiceSettings::OrHash,
+              websocket_settings: Telnyx::AI::WebsocketSettings::OrHash,
               widget_settings: Telnyx::AI::WidgetSettings::OrHash,
               request_options: Telnyx::RequestOptions::OrHash
             ).returns(Telnyx::AI::InferenceEmbedding)
@@ -101,12 +106,24 @@ module Telnyx
             # to leave the assistant's agents unchanged; send an empty array to remove them
             # all.
             a2a_agents: nil,
+            # Body param: **Beta:** Configuration for the Telnyx open-source avatar provider.
+            # The launch catalog supports six avatars and office, studio, or reception
+            # backgrounds.
+            avatar_settings: nil,
             # Body param: Conversation flow as supplied by API clients (create / update).
             #
             # A directed graph of `FlowNodeReq` connected by `FlowEdge`s. Validation enforces
             # unique node/edge IDs, that `start_node_id` references a real node, and that
             # every edge's endpoints reference real nodes.
             conversation_flow: nil,
+            # Body param: Splits the conversation between a frontend model that talks to the
+            # caller and a backend model that does the work. On the GPT-Live route the
+            # frontend model cannot call tools at all — when it needs something done it raises
+            # a delegation and waits. On the chat completion route the frontend keeps a single
+            # `delegate` tool that returns immediately, so the conversation carries on while
+            # the backend works. Either way the backend's answer is spoken as commentary or
+            # kept as silent context, depending on `speak_results`. Beta feature.
+            delegation_settings: nil,
             # Body param
             description: nil,
             # Body param: Map of dynamic variables and their default values
@@ -216,6 +233,12 @@ module Telnyx
             version_name: nil,
             # Body param
             voice_settings: nil,
+            # Body param: Streams conversation and telephony events to a WebSocket server you
+            # host, and accepts messages injected back into the conversation. Telnyx opens the
+            # connection as a client, once per conversation. Delivery is best effort
+            # throughout: while the connection is down events are dropped rather than queued,
+            # and no socket failure is ever allowed to affect the call. Beta feature.
+            websocket_settings: nil,
             # Body param: Configuration settings for the assistant's web widget.
             widget_settings: nil,
             request_options: {}

data/rbi/telnyx/resources/ai/assistants.rbi

@@ -33,6 +33,10 @@ module Telnyx
         sig { returns(Telnyx::Resources::AI::Assistants::Instructions) }
         attr_reader :instructions
 
+        # Configure AI assistant specifications
+        sig { returns(Telnyx::Resources::AI::Assistants::Deleted) }
+        attr_reader :deleted
+
         # Creates a new AI assistant from the provided configuration, including its model,
         # instructions, and attached tools, and returns the created assistant.
         sig do
@@ -40,7 +44,10 @@ module Telnyx
             instructions: String,
             name: String,
             a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent::OrHash],
+            avatar_settings:
+              T.nilable(Telnyx::AI::AvatarSettingsRequest::OrHash),
             conversation_flow: Telnyx::AI::ConversationFlowReq::OrHash,
+            delegation_settings: Telnyx::AI::DelegationSettings::OrHash,
             description: String,
             dynamic_variables: T::Hash[Symbol, T.anything],
             dynamic_variables_webhook_timeout_ms: Integer,
@@ -84,7 +91,8 @@ module Telnyx
                 )
               ],
             transcription: Telnyx::AI::TranscriptionSettings::OrHash,
-            voice_settings: Telnyx::AI::VoiceSettings::OrHash,
+            voice_settings: Telnyx::AI::InferenceEmbeddingVoiceSettings::OrHash,
+            websocket_settings: Telnyx::AI::WebsocketSettings::OrHash,
             widget_settings: Telnyx::AI::WidgetSettings::OrHash,
             idempotency_key: String,
             request_options: Telnyx::RequestOptions::OrHash
@@ -105,12 +113,24 @@ module Telnyx
           # card fetches combined. An agent whose card cannot be fetched costs the assistant
           # that capability for the conversation; it does not fail the call.
           a2a_agents: nil,
+          # Body param: **Beta:** Configuration for the Telnyx open-source avatar provider.
+          # The launch catalog supports six avatars and office, studio, or reception
+          # backgrounds.
+          avatar_settings: nil,
           # Body param: Conversation flow as supplied by API clients (create / update).
           #
           # A directed graph of `FlowNodeReq` connected by `FlowEdge`s. Validation enforces
           # unique node/edge IDs, that `start_node_id` references a real node, and that
           # every edge's endpoints reference real nodes.
           conversation_flow: nil,
+          # Body param: Splits the conversation between a frontend model that talks to the
+          # caller and a backend model that does the work. On the GPT-Live route the
+          # frontend model cannot call tools at all — when it needs something done it raises
+          # a delegation and waits. On the chat completion route the frontend keeps a single
+          # `delegate` tool that returns immediately, so the conversation carries on while
+          # the backend works. Either way the backend's answer is spoken as commentary or
+          # kept as silent context, depending on `speak_results`. Beta feature.
+          delegation_settings: nil,
           # Body param
           description: nil,
           # Body param: Map of dynamic variables and their default values
@@ -202,6 +222,12 @@ module Telnyx
           transcription: nil,
           # Body param
           voice_settings: nil,
+          # Body param: Streams conversation and telephony events to a WebSocket server you
+          # host, and accepts messages injected back into the conversation. Telnyx opens the
+          # connection as a client, once per conversation. Delivery is best effort
+          # throughout: while the connection is down events are dropped rather than queued,
+          # and no socket failure is ever allowed to affect the call. Beta feature.
+          websocket_settings: nil,
           # Body param: Configuration settings for the assistant's web widget.
           widget_settings: nil,
           # Header param: Optional opaque, unquoted key for safely retrying the same logical
@@ -250,7 +276,10 @@ module Telnyx
           params(
             assistant_id: String,
             a2a_agents: T::Array[Telnyx::AI::AssistantA2AAgent::OrHash],
+            avatar_settings:
+              T.nilable(Telnyx::AI::AvatarSettingsRequest::OrHash),
             conversation_flow: Telnyx::AI::ConversationFlowReq::OrHash,
+            delegation_settings: Telnyx::AI::DelegationSettings::OrHash,
             description: String,
             dynamic_variables: T::Hash[Symbol, T.anything],
             dynamic_variables_webhook_timeout_ms: Integer,
@@ -298,7 +327,8 @@ module Telnyx
               ],
             transcription: Telnyx::AI::TranscriptionSettings::OrHash,
             version_name: String,
-            voice_settings: Telnyx::AI::VoiceSettings::OrHash,
+            voice_settings: Telnyx::AI::InferenceEmbeddingVoiceSettings::OrHash,
+            websocket_settings: Telnyx::AI::WebsocketSettings::OrHash,
             widget_settings: Telnyx::AI::WidgetSettings::OrHash,
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::AI::InferenceEmbedding)
@@ -316,12 +346,23 @@ module Telnyx
           # capability for the conversation; it does not fail the call. Omit this field to
           # leave the assistant's agents unchanged; send an empty array to remove them all.
           a2a_agents: nil,
+          # **Beta:** Configuration for the Telnyx open-source avatar provider. The launch
+          # catalog supports six avatars and office, studio, or reception backgrounds.
+          avatar_settings: nil,
           # Conversation flow as supplied by API clients (create / update).
           #
           # A directed graph of `FlowNodeReq` connected by `FlowEdge`s. Validation enforces
           # unique node/edge IDs, that `start_node_id` references a real node, and that
           # every edge's endpoints reference real nodes.
           conversation_flow: nil,
+          # Splits the conversation between a frontend model that talks to the caller and a
+          # backend model that does the work. On the GPT-Live route the frontend model
+          # cannot call tools at all — when it needs something done it raises a delegation
+          # and waits. On the chat completion route the frontend keeps a single `delegate`
+          # tool that returns immediately, so the conversation carries on while the backend
+          # works. Either way the backend's answer is spoken as commentary or kept as silent
+          # context, depending on `speak_results`. Beta feature.
+          delegation_settings: nil,
           description: nil,
           # Map of dynamic variables and their default values
           dynamic_variables: nil,
@@ -421,6 +462,12 @@ module Telnyx
           # Human-readable name for the assistant version.
           version_name: nil,
           voice_settings: nil,
+          # Streams conversation and telephony events to a WebSocket server you host, and
+          # accepts messages injected back into the conversation. Telnyx opens the
+          # connection as a client, once per conversation. Delivery is best effort
+          # throughout: while the connection is down events are dropped rather than queued,
+          # and no socket failure is ever allowed to affect the call. Beta feature.
+          websocket_settings: nil,
           # Configuration settings for the assistant's web widget.
           widget_settings: nil,
           request_options: {}
@@ -437,15 +484,33 @@ module Telnyx
         end
 
         # Delete an AI Assistant by `assistant_id`.
+        #
+        # By default this performs a soft delete: the assistant moves to the Recently
+        # Deleted list and stays restorable for 30 days, after which it is permanently
+        # deleted automatically. The assistant's versions and TeXML application are
+        # preserved during the retention window.
+        #
+        # Pass `hard_delete=true` to skip the retention window and permanently delete the
+        # assistant immediately. A hard delete erases the assistant and all of its
+        # versions, and deletes its TeXML application unless phone numbers are still
+        # assigned to it. It does not delete conversations, recordings, shared tools the
+        # assistant referenced, or knowledge-base embeddings.
+        #
+        # Deletion fails with `400` if other assistants reference this one through a
+        # handoff tool or a conversation-flow edge — remove those references first.
         sig do
           params(
             assistant_id: String,
+            hard_delete: T::Boolean,
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::AI::AssistantDeleteResponse)
         end
         def delete(
           # Unique identifier of the assistant.
           assistant_id,
+          # Permanently delete the assistant immediately instead of soft-deleting it to the
+          # Recently Deleted list, where it stays restorable for 30 days.
+          hard_delete: nil,
           request_options: {}
         )
         end
@@ -560,6 +625,24 @@ module Telnyx
         )
         end
 
+        # Restore a soft-deleted assistant from the Recently Deleted list.
+        #
+        # The assistant becomes fully active again with its versions and TeXML application
+        # as they were at deletion time. Restoring does not re-enable numbers or
+        # connections that were released separately after the deletion.
+        sig do
+          params(
+            assistant_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::AI::InferenceEmbedding)
+        end
+        def restore(
+          # Unique identifier of the assistant.
+          assistant_id,
+          request_options: {}
+        )
+        end
+
         # Send an SMS message for an assistant. This endpoint:
         #
         # 1. Validates the assistant exists and has messaging profile configured
@@ -613,6 +696,65 @@ module Telnyx
         )
         end
 
+        # Start a WhatsApp conversation with a customer from the business side. This
+        # endpoint:
+        #
+        # 1. Validates that `from` is a WhatsApp number on your account whose messaging
+        #    profile has this assistant configured
+        # 2. Creates a new `whatsapp_chat` conversation with the provided metadata
+        # 3. Asks the assistant to pick one of its approved WhatsApp templates and fill
+        #    its variables from `content`
+        # 4. Sends the template from `from` to `to`
+        # 5. Returns the conversation ID and the message ID
+        #
+        # When the customer replies, the reply is routed to the same conversation and the
+        # assistant answers within the 24-hour customer service window. The assistant
+        # needs a `whatsapp_template` tool with at least one approved template, data
+        # retention enabled and PII redaction disabled.
+        sig do
+          params(
+            assistant_id: String,
+            content: String,
+            from: String,
+            to: String,
+            conversation_metadata:
+              T::Hash[
+                Symbol,
+                Telnyx::AI::AssistantWhatsappParams::ConversationMetadata::Variants
+              ],
+            idempotency_key: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::AI::AssistantWhatsappResponse)
+        end
+        def whatsapp(
+          # Path param: Unique identifier of the assistant. Must be the assistant configured
+          # on the messaging profile of the `from` number.
+          assistant_id,
+          # Body param: Instruction for the assistant, including the values for the template
+          # variables, e.g. `Send the login verification code 482913 to the customer.`
+          content:,
+          # Body param: WhatsApp number on your account to send from, in E.164 format. Its
+          # messaging profile must have this assistant configured.
+          from:,
+          # Body param: Customer to message, as an E.164 phone number or a WhatsApp
+          # business-scoped user ID (BSUID).
+          to:,
+          # Body param: Metadata stored on the conversation. Keys starting with `telnyx_`
+          # and the `assistant_id` key are reserved.
+          conversation_metadata: nil,
+          # Header param: Optional opaque, unquoted key for safely retrying the same logical
+          # request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+          # Generate a unique UUID v4 for each operation and reuse it only when retrying
+          # that operation with the same request. Invalid headers—including duplicate,
+          # empty, malformed, or overlong values—return 400 with error code 10015. A request
+          # already in progress with the same key returns 409; reusing the key with a
+          # different request returns 422. Only successful responses are replayed, for up to
+          # 24 hours. Do not include sensitive data in the key.
+          idempotency_key: nil,
+          request_options: {}
+        )
+        end
+
         # @api private
         sig { params(client: Telnyx::Client).returns(T.attached_class) }
         def self.new(client:)

data/rbi/telnyx/resources/ai/conversations.rbi

@@ -97,6 +97,7 @@ module Telnyx
             last_message_at: String,
             limit: Integer,
             metadata_assistant_id: String,
+            metadata_assistant_version_id: String,
             metadata_call_control_id: String,
             metadata_telnyx_agent_target: String,
             metadata_telnyx_conversation_channel: String,
@@ -118,6 +119,12 @@ module Telnyx
           limit: nil,
           # Filter by assistant ID (e.g., `metadata->assistant_id=eq.assistant-123`)
           metadata_assistant_id: nil,
+          # Filter by assistant version ID (e.g.,
+          # `metadata->assistant_version_id=eq.20250812T114318034399`). The version that
+          # handled the conversation is stored in metadata when the conversation starts;
+          # conversations created before this field was tracked, or that never resolved a
+          # version, have no `assistant_version_id` and do not match this filter.
+          metadata_assistant_version_id: nil,
           # Filter by call control ID (e.g., `metadata->call_control_id=eq.v3:123`)
           metadata_call_control_id: nil,
           # Filter by the phone number, SIP URI, or other identifier for the agent (e.g.,

data/rbi/telnyx/resources/ai/memory/namespaces/profiles/memories.rbi

@@ -0,0 +1,94 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Memory
+        class Namespaces
+          class Profiles
+            # What a namespace and a profile hold.
+            class Memories
+              # One memory by its id, as `recall` and the listing return it, together with what
+              # it came from. A fact names its `source_id`: read it with
+              # `GET .../sources/{source_id}` to see what was stored. A memory derived from
+              # other memories names them in `derived_from` instead; read each of those to reach
+              # its source.
+              sig do
+                params(
+                  memory_id: String,
+                  namespace: String,
+                  profile_id: String,
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Models::AI::Memory::Namespaces::Profiles::MemoryRetrieveResponse
+                )
+              end
+              def retrieve(
+                # A memory's id, as `recall` and the listing return it.
+                memory_id,
+                # The namespace. `default` exists for every organization.
+                namespace:,
+                # The profile: your identifier for the user, caller or agent this memory is about.
+                profile_id:,
+                request_options: {}
+              )
+              end
+
+              # Everything stored under one profile, unranked -- ask `recall` for the memories
+              # that answer a question. A profile that holds nothing is an empty page rather
+              # than a 404: profiles exist by being written to. Each memory names the
+              # `source_id` it was extracted from, or null for a memory derived from other
+              # memories -- which can read almost the same as the fact it restates. A
+              # `source_id` narrows the listing to the memories extracted from that source, and
+              # a `session_id` to those extracted from the session, which is the same thing
+              # named another way; pass one or the other. Neither is everything the source led
+              # to: a memory derived from several sources belongs to no single one and appears
+              # only in the unfiltered listing. A memory written while the listing is paged
+              # shifts the pages after it, so an entry can be repeated or missed at a page
+              # boundary.
+              sig do
+                params(
+                  profile_id: String,
+                  namespace: String,
+                  page_number: Integer,
+                  page_size: Integer,
+                  session_id: T.nilable(String),
+                  source_id: T.nilable(String),
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Internal::DefaultFlatPagination[
+                    Telnyx::Models::AI::Memory::Namespaces::Profiles::MemoryListResponse
+                  ]
+                )
+              end
+              def list(
+                # Path param
+                profile_id,
+                # Path param
+                namespace:,
+                # Query param: The page to return, counting from 1. Bounded in depth:
+                # (page[number] - 1) \* page[size] may be at most 10000.
+                page_number: nil,
+                # Query param: How many results a page holds.
+                page_size: nil,
+                # Query param: An ingested session, by the `session_id` it was ingested with.
+                # Narrows the request to the source that session was stored as.
+                session_id: nil,
+                # Query param: Narrows the listing to the memories extracted from one source, a
+                # remembered fact as well as a session. Pass this or `session_id`, not both.
+                source_id: nil,
+                request_options: {}
+              )
+              end
+
+              # @api private
+              sig { params(client: Telnyx::Client).returns(T.attached_class) }
+              def self.new(client:)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/memory/namespaces/profiles/sources.rbi

@@ -0,0 +1,117 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Memory
+        class Namespaces
+          class Profiles
+            # What a profile stored, and what its memories came from.
+            class Sources
+              # One source and its content, as it was stored: an ingested session's payload or a
+              # remembered fact. A source whose ingest is still queued answers 404 until it has
+              # been stored.
+              sig do
+                params(
+                  source_id: String,
+                  namespace: String,
+                  profile_id: String,
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Models::AI::Memory::Namespaces::Profiles::SourceRetrieveResponse
+                )
+              end
+              def retrieve(
+                # Identifies one source within its profile: an ingested session, or one remembered
+                # fact. Returned by `ingest` and `remember` when the write is accepted.
+                # Re-ingesting a session keeps its source id.
+                source_id,
+                # The namespace. `default` exists for every organization.
+                namespace:,
+                # The profile: your identifier for the user, caller or agent this memory is about.
+                profile_id:,
+                request_options: {}
+              )
+              end
+
+              # Everything a profile has stored and extracts memories from: each ingested
+              # session, and each remembered fact, which has no session. Content is not listed;
+              # read one source for it. A source whose ingest is still queued is not here yet.
+              # Re-ingesting a session moves it to the front, so a listing paged while sessions
+              # are written can repeat or miss one at a page boundary. A `session_id` narrows
+              # the listing to the source that session was stored as: one source or none, and
+              # none -- an empty page, not a 404 -- for a session never ingested, still queued,
+              # or another profile's.
+              sig do
+                params(
+                  profile_id: String,
+                  namespace: String,
+                  page_number: Integer,
+                  page_size: Integer,
+                  session_id: T.nilable(String),
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Internal::DefaultFlatPagination[
+                    Telnyx::AI::Collections::Source
+                  ]
+                )
+              end
+              def list(
+                # Path param
+                profile_id,
+                # Path param
+                namespace:,
+                # Query param: The page to return, counting from 1. Bounded in depth:
+                # (page[number] - 1) \* page[size] may be at most 10000.
+                page_number: nil,
+                # Query param: How many results a page holds.
+                page_size: nil,
+                # Query param: An ingested session, by the `session_id` it was ingested with.
+                # Narrows the request to the source that session was stored as.
+                session_id: nil,
+                request_options: {}
+              )
+              end
+
+              # Deletes one source -- an ingested session or a remembered fact -- together with
+              # the memories derived from it. A memory derived from this source and others is
+              # deleted too, and derived again from what remains in the background. It answers
+              # only once the source is gone. A source that is not there -- never stored,
+              # another profile's, or already deleted -- answers 404, so on a `502` or a `504`
+              # repeat the identical request and read a 404 as done. An ingest of the same
+              # session that is still queued is not cancelled, and stores the session again when
+              # it runs. Nothing here can be undone.
+              sig do
+                params(
+                  source_id: String,
+                  namespace: String,
+                  profile_id: String,
+                  request_options: Telnyx::RequestOptions::OrHash
+                ).returns(
+                  Telnyx::Models::AI::Memory::Namespaces::Profiles::SourceDeleteResponse
+                )
+              end
+              def delete(
+                # Identifies one source within its profile: an ingested session, or one remembered
+                # fact. Returned by `ingest` and `remember` when the write is accepted.
+                # Re-ingesting a session keeps its source id.
+                source_id,
+                # The namespace. `default` exists for every organization.
+                namespace:,
+                # The profile: your identifier for the user, caller or agent this memory is about.
+                profile_id:,
+                request_options: {}
+              )
+              end
+
+              # @api private
+              sig { params(client: Telnyx::Client).returns(T.attached_class) }
+              def self.new(client:)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end