telnyx 5.171.0 → 5.174.0

data/rbi/telnyx/resources/email/dedicated_ips.rbi

@@ -0,0 +1,187 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class Email
+      # Purchase and manage dedicated sending IP addresses for your Telnyx email
+      # traffic.
+      class DedicatedIPs
+        # Purchase and manage dedicated sending IP addresses for your Telnyx email
+        # traffic.
+        sig { returns(Telnyx::Resources::Email::DedicatedIPs::Actions) }
+        attr_reader :actions
+
+        # Purchase a dedicated sending IP. Requires a verified, enterprise, or legacy
+        # account, and an `Idempotency-Key` header: a request without the header returns
+        # `400` (code `10015`) and allocates nothing. Telnyx allocates the next available
+        # IP from stock. The optional `region` and `ip_version` fields each restrict which
+        # stock IP is allocated; they never change the allocated IP's metadata. An omitted
+        # field applies no restriction for that field, and omitting the body applies
+        # neither restriction. An unsupported selector value returns `422`; a supported
+        # value that matches no available IP returns `429` and records the request on the
+        # waitlist. Billing: $14/month/IP, charged as a monthly recurring charge (MRC)
+        # from purchase. The IP is returned in `provisioning` status with a Telnyx-managed
+        # PTR hostname and carries no mail until you call `start_warmup` and add it to a
+        # pool that routes mail.
+        sig do
+          params(
+            idempotency_key: String,
+            ip_version:
+              Telnyx::Email::DedicatedIPCreateParams::IPVersion::OrSymbol,
+            region: Telnyx::Email::DedicatedIPCreateParams::Region::OrSymbol,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Email::DedicatedIPShowResponse)
+        end
+        def create(
+          # Header param: Required. Opaque, unquoted key for safely retrying the same
+          # purchase. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+          # Generate a unique UUID v4 for each purchase and reuse it only when retrying that
+          # purchase with the same request. A missing header, or an invalid one —including
+          # duplicate, empty, malformed, or overlong values—returns 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:,
+          # Body param: Allocate an IP of this address family. Supported value: `ipv4`. Any
+          # other value, including `ipv6` or `null`, returns `422`.
+          ip_version: nil,
+          # Body param: Allocate an IP in this region. Supported value: `ewr-nj1`. Any other
+          # value, including an empty string or `null`, returns `422`.
+          region: nil,
+          request_options: {}
+        )
+        end
+
+        # Retrieve a single dedicated IP by its identifier, including warm-up state,
+        # billing state, and the DNS/PTR provisioning checklist.
+        sig do
+          params(
+            id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Email::DedicatedIPShowResponse)
+        end
+        def retrieve(
+          # The dedicated IP identifier (UUID).
+          id,
+          request_options: {}
+        )
+        end
+
+        # Move the IP to another pool, or pause/resume its warm-up ramp. One change
+        # applies per request. `pool_id` takes precedence over warm-up changes. Otherwise,
+        # use `warmup_paused` or `warmup.paused`; a Boolean `warmup_paused` takes
+        # precedence. Moving the last IP out of a pool requires `force: true` and
+        # `drain: true`. The PTR hostname is managed by Telnyx: a request that includes
+        # `ptr_hostname` returns `422` unless `pool_id` or a warm-up field is present, in
+        # which case `ptr_hostname` is ignored.
+        sig do
+          params(
+            id: String,
+            drain: T::Boolean,
+            force: T::Boolean,
+            pool_id: String,
+            warmup: Telnyx::Email::DedicatedIPUpdateParams::Warmup::OrHash,
+            warmup_paused: T::Boolean,
+            weight: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Email::DedicatedIPShowResponse)
+        end
+        def update(
+          # The dedicated IP identifier (UUID).
+          id,
+          # Set together with `force: true` to move the last IP out of its current pool.
+          # Acknowledges that mail routed to the emptied pool is held. Used only with
+          # `pool_id`.
+          drain: nil,
+          # Set together with `drain: true` to move the last IP out of its current pool.
+          # Used only with `pool_id`.
+          force: nil,
+          # Move the IP to this pool, replacing its current membership. Use the IP's current
+          # pool to change only its weight. To take an IP out of a pool, use
+          # `DELETE /email/ip_pools/{id}/ips/{ip_id}`.
+          pool_id: nil,
+          # Alias for `warmup_paused`.
+          warmup: nil,
+          # Pause (`true`) or resume (`false`) the warm-up ramp; equivalent to the
+          # `pause_warmup` and `resume_warmup` actions. A Boolean value takes precedence
+          # over `warmup.paused`. When a pause field is present and `pool_id` is absent,
+          # supplying neither pause field as a Boolean invokes resume.
+          warmup_paused: nil,
+          # Routing weight in the target pool. Used only with `pool_id`.
+          weight: nil,
+          request_options: {}
+        )
+        end
+
+        # List the dedicated sending IPs owned by the account, newest first. Narrow the
+        # list with `filter[status]`, `filter[pool_id]`, and `filter[region]`; supplied
+        # filters combine, so an IP must match every one. An empty value, or a nested or
+        # array value such as `filter[status][]=active`, applies no filter, and other
+        # `filter[...]` keys are ignored. A value that no IP can match (an unknown status,
+        # a `pool_id` that is not a UUID, or a value containing a NUL byte) returns an
+        # empty list, not an error.
+        sig do
+          params(
+            filter_pool_id: String,
+            filter_region: String,
+            filter_status:
+              Telnyx::Email::DedicatedIPListParams::FilterStatus::OrSymbol,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::Email::DedicatedIPListResponse)
+        end
+        def list(
+          # Return only IPs in this pool (exact match on `pool_id`). A value that is not a
+          # UUID returns an empty list. An empty value applies no filter.
+          filter_pool_id: nil,
+          # Return only IPs in this region (exact, case-sensitive match on `region`). An
+          # empty value applies no filter.
+          filter_region: nil,
+          # Return only IPs in this lifecycle status (exact match). Any other value returns
+          # an empty list. An empty value applies no filter.
+          filter_status: nil,
+          request_options: {}
+        )
+        end
+
+        # Release the dedicated IP to Telnyx. The IP stops carrying mail immediately,
+        # leaves its pool, and moves to `released`. Telnyx sets `quarantine_until` to 30
+        # days after release. Release requests that the MRC stop asynchronously. Check
+        # `billing`: `stopping` means the stop is pending, `stopped` means it completed,
+        # and `stop_failed` means the charge remains. If the charge was never created or
+        # its creation has not completed, `billing` keeps showing the creation status
+        # (`not_started`, `pending`, `in_progress`, or `failed`). Any status except
+        # `released` can be released. Releasing the last IP in a pool requires
+        # `force=true` and `drain=true`.
+        sig do
+          params(
+            id: String,
+            body_drain: T::Boolean,
+            body_force: T::Boolean,
+            body_reason: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Email::DedicatedIPShowResponse)
+        end
+        def delete(
+          # Path param: The dedicated IP identifier (UUID).
+          id,
+          # Body param: Set together with `force: true` to release the last IP in a pool.
+          # Acknowledges that mail routed to the emptied pool is held until the pool has a
+          # sendable IP again.
+          body_drain: nil,
+          # Body param: Set together with `drain: true` to release the last IP in a pool.
+          # Either flag alone has no effect.
+          body_force: nil,
+          # Body param: Free-text reason recorded with the release.
+          body_reason: 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/email/ip_pools/ips.rbi

@@ -0,0 +1,69 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class Email
+      class IPPools
+        # Group dedicated IPs into pools for sending.
+        class IPs
+          # Add a dedicated IP to the pool with an optional routing weight. An IP can belong
+          # to one pool; to move an IP that is already in a pool, use
+          # `PATCH /email/dedicated_ips/{id}` with `pool_id`.
+          sig do
+            params(
+              id: String,
+              dedicated_ip_id: String,
+              weight: Integer,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(Telnyx::Models::Email::IPPools::IPCreateResponse)
+          end
+          def create(
+            # The IP pool identifier (UUID).
+            id,
+            # The dedicated IP to add. It must belong to the account, must not be released,
+            # and must not already be in a pool.
+            dedicated_ip_id:,
+            # Relative routing weight for this IP in the pool. Positive integer; defaults
+            # to 100.
+            weight: nil,
+            request_options: {}
+          )
+          end
+
+          # Remove the dedicated IP from the pool. The IP is kept but carries no mail until
+          # added to a pool again. Removing the last IP requires `force=true` and
+          # `drain=true`.
+          sig do
+            params(
+              ip_id: String,
+              id: String,
+              drain: T::Boolean,
+              force: T::Boolean,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).void
+          end
+          def delete(
+            # Path param: The dedicated IP identifier (UUID).
+            ip_id,
+            # Path param: The IP pool identifier (UUID).
+            id:,
+            # Query param: Set together with `force=true` to remove the last IP in the pool.
+            # Acknowledges that mail routed to the emptied pool is held until the pool has a
+            # sendable IP again.
+            drain: nil,
+            # Query param: Set together with `drain=true` to remove the last IP in the pool.
+            # Either flag alone has no effect.
+            force: 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

data/rbi/telnyx/resources/email/ip_pools.rbi

@@ -0,0 +1,123 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class Email
+      # Group dedicated IPs into pools for sending.
+      class IPPools
+        # Group dedicated IPs into pools for sending.
+        sig { returns(Telnyx::Resources::Email::IPPools::IPs) }
+        attr_reader :ips
+
+        # Create an account-scoped pool of dedicated IPs. Set `is_default` or `domain_id`
+        # for the pool to carry mail; a pool with neither carries none.
+        sig do
+          params(
+            name: String,
+            domain_id: String,
+            is_default: T::Boolean,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Email::IPPoolShowResponse)
+        end
+        def create(
+          # Pool name: 1-64 characters of lowercase letters, digits, `.`, `_`, and `-`,
+          # starting and ending with a letter or digit. Must be unique within the account
+          # and must not start with `dip_`.
+          name:,
+          # Scope the pool to one of the account's email domains; the pool then carries that
+          # domain's mail. Scope at most one pool to each domain.
+          domain_id: nil,
+          # Make this the account's default pool, which carries mail for sending domains
+          # without a domain-scoped pool. An account can have one default pool. Defaults to
+          # `false`.
+          is_default: nil,
+          request_options: {}
+        )
+        end
+
+        # Retrieve a single IP pool by its identifier, including its dedicated-IP members
+        # with billing state.
+        sig do
+          params(
+            id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Email::IPPoolShowResponse)
+        end
+        def retrieve(
+          # The IP pool identifier (UUID).
+          id,
+          request_options: {}
+        )
+        end
+
+        # Rename the pool, set or clear the default flag, or change its domain scope.
+        # Routing follows the new settings for subsequent mail.
+        sig do
+          params(
+            id: String,
+            domain_id: T.nilable(String),
+            is_default: T::Boolean,
+            name: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Email::IPPoolShowResponse)
+        end
+        def update(
+          # The IP pool identifier (UUID).
+          id,
+          # Scope the pool to one of the account's email domains, or `null` to remove the
+          # scope.
+          domain_id: nil,
+          # Set or clear the account default flag. An account can have one default pool.
+          is_default: nil,
+          # Pool name: 1-64 characters of lowercase letters, digits, `.`, `_`, and `-`,
+          # starting and ending with a letter or digit. Must be unique within the account
+          # and must not start with `dip_`.
+          name: nil,
+          request_options: {}
+        )
+        end
+
+        # List the account's dedicated-IP pools. Member IPs are not included (`ips` is
+        # empty); retrieve a pool to see its members.
+        sig do
+          params(request_options: Telnyx::RequestOptions::OrHash).returns(
+            Telnyx::Models::Email::IPPoolListResponse
+          )
+        end
+        def list(request_options: {})
+        end
+
+        # Delete the pool. Member IPs are kept but leave the pool, so they carry no mail
+        # until added to another pool. Deleting a pool changes routing for subsequently
+        # resolved messages. It does not reroute messages already assigned to the deleted
+        # pool. Deleting a pool that still has IPs requires `force=true` and `drain=true`.
+        sig do
+          params(
+            id: String,
+            drain: T::Boolean,
+            force: T::Boolean,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).void
+        end
+        def delete(
+          # The IP pool identifier (UUID).
+          id,
+          # Set together with `force=true` to delete a pool that still has IPs. Acknowledges
+          # deletion while the pool still has members; this flag does not reroute already
+          # queued messages.
+          drain: nil,
+          # Set together with `drain=true` to delete a pool that still has IPs. Either flag
+          # alone has no effect.
+          force: 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/email.rbi

@@ -0,0 +1,21 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class Email
+      # Purchase and manage dedicated sending IP addresses for your Telnyx email
+      # traffic.
+      sig { returns(Telnyx::Resources::Email::DedicatedIPs) }
+      attr_reader :dedicated_ips
+
+      # Group dedicated IPs into pools for sending.
+      sig { returns(Telnyx::Resources::Email::IPPools) }
+      attr_reader :ip_pools
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/email_templates.rbi

@@ -14,12 +14,7 @@ module Telnyx
           subject: T.nilable(String),
           text_body: T.nilable(String),
           variable_schema:
-            T.nilable(
-              T::Hash[
-                Symbol,
-                Telnyx::EmailTemplateCreateParams::VariableSchema::OrHash
-              ]
-            ),
+            T.nilable(T::Hash[Symbol, Telnyx::VariableSchemaEntry::OrHash]),
           variables: T.nilable(T::Array[String]),
           variables_mode:
             Telnyx::EmailTemplateCreateParams::VariablesMode::OrSymbol,
@@ -111,12 +106,7 @@ module Telnyx
           subject: T.nilable(String),
           text_body: T.nilable(String),
           variable_schema:
-            T.nilable(
-              T::Hash[
-                Symbol,
-                Telnyx::UpdateEmailTemplateRequest::VariableSchema::OrHash
-              ]
-            ),
+            T.nilable(T::Hash[Symbol, Telnyx::VariableSchemaEntry::OrHash]),
           variables: T.nilable(T::Array[String]),
           variables_mode:
             Telnyx::UpdateEmailTemplateRequest::VariablesMode::OrSymbol,
@@ -252,12 +242,7 @@ module Telnyx
           subject: T.nilable(String),
           text_body: T.nilable(String),
           variable_schema:
-            T.nilable(
-              T::Hash[
-                Symbol,
-                Telnyx::UpdateEmailTemplateRequest::VariableSchema::OrHash
-              ]
-            ),
+            T.nilable(T::Hash[Symbol, Telnyx::VariableSchemaEntry::OrHash]),
           variables: T.nilable(T::Array[String]),
           variables_mode:
             Telnyx::UpdateEmailTemplateRequest::VariablesMode::OrSymbol,

data/rbi/telnyx/resources/enterprises/verify_email.rbi

@@ -4,7 +4,7 @@ module Telnyx
   module Resources
     class Enterprises
       # Verify ownership of a DIR's authorizer email. A short code is emailed and
-      # confirmed; the email must be verified before references can be submitted.
+      # confirmed.
       class VerifyEmail
         # Email a 6-digit code to the enterprise account's contact email to confirm
         # ownership of that address.

data/rbi/telnyx/resources/enterprises.rbi

@@ -14,7 +14,7 @@ module Telnyx
       attr_reader :dir
 
       # Verify ownership of a DIR's authorizer email. A short code is emailed and
-      # confirmed; the email must be verified before references can be submitted.
+      # confirmed.
       sig { returns(Telnyx::Resources::Enterprises::VerifyEmail) }
       attr_reader :verify_email
 

data/rbi/telnyx/resources/fqdn_connections.rbi

@@ -16,6 +16,7 @@ module Telnyx
           active: T::Boolean,
           anchorsite_override: Telnyx::AnchorsiteOverride::OrSymbol,
           android_push_credential_id: T.nilable(String),
+          bridge_generate_comfort_noise_on_cn: T::Boolean,
           call_cost_in_webhooks: T::Boolean,
           default_on_hold_comfort_noise_enabled: T::Boolean,
           dtmf_type: Telnyx::DtmfType::OrSymbol,
@@ -51,6 +52,14 @@ module Telnyx
         anchorsite_override: nil,
         # The uuid of the push credential for Android
         android_push_credential_id: nil,
+        # Stores the connection preference for generating silent RTP toward the opposite
+        # call leg when comfort-noise packets (CN, payload type 13) are received during
+        # hold. Optional; defaults to false when omitted on creation. Only JSON true and
+        # false are accepted; null and non-boolean values are rejected. This preference is
+        # independent of default_on_hold_comfort_noise_enabled and does not modify that
+        # setting. This API provisions the preference; call-processing behavior is
+        # implemented separately.
+        bridge_generate_comfort_noise_on_cn: nil,
         # Specifies if call cost webhooks should be sent for this connection.
         call_cost_in_webhooks: nil,
         # When enabled, Telnyx will generate comfort noise when you place the call on
@@ -63,8 +72,8 @@ module Telnyx
         # Encode the SIP contact header sent by Telnyx to avoid issues for NAT or ALG
         # scenarios.
         encode_contact_header_enabled: nil,
-        # Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
-        # TLS.
+        # Enable use of SRTP for encryption. Can only be set when the SIP signaling
+        # transport protocol is TLS.
         encrypted_media: nil,
         inbound: nil,
         # The uuid of the push credential for Ios
@@ -134,6 +143,7 @@ module Telnyx
           active: T::Boolean,
           anchorsite_override: Telnyx::AnchorsiteOverride::OrSymbol,
           android_push_credential_id: T.nilable(String),
+          bridge_generate_comfort_noise_on_cn: T::Boolean,
           call_cost_in_webhooks: T::Boolean,
           connection_name: String,
           conversation_persistence: T::Boolean,
@@ -170,6 +180,14 @@ module Telnyx
         anchorsite_override: nil,
         # The uuid of the push credential for Android
         android_push_credential_id: nil,
+        # Stores the connection preference for generating silent RTP toward the opposite
+        # call leg when comfort-noise packets (CN, payload type 13) are received during
+        # hold. Optional; omitting this field preserves the saved value. Only JSON true
+        # and false are accepted; null and non-boolean values are rejected. This
+        # preference is independent of default_on_hold_comfort_noise_enabled and does not
+        # modify that setting. This API provisions the preference; call-processing
+        # behavior is implemented separately.
+        bridge_generate_comfort_noise_on_cn: nil,
         # Specifies if call cost webhooks should be sent for this connection.
         call_cost_in_webhooks: nil,
         # A user-assigned name to help manage the connection.
@@ -188,8 +206,8 @@ module Telnyx
         # Encode the SIP contact header sent by Telnyx to avoid issues for NAT or ALG
         # scenarios.
         encode_contact_header_enabled: nil,
-        # Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
-        # TLS.
+        # Enable use of SRTP for encryption. Can only be set when the SIP signaling
+        # transport protocol is TLS.
         encrypted_media: nil,
         inbound: nil,
         # The uuid of the push credential for Ios

data/rbi/telnyx/resources/ip_connections.rbi

@@ -11,6 +11,7 @@ module Telnyx
           active: T::Boolean,
           anchorsite_override: Telnyx::AnchorsiteOverride::OrSymbol,
           android_push_credential_id: T.nilable(String),
+          bridge_generate_comfort_noise_on_cn: T::Boolean,
           call_cost_in_webhooks: T::Boolean,
           connection_name: String,
           default_on_hold_comfort_noise_enabled: T::Boolean,
@@ -46,6 +47,14 @@ module Telnyx
         anchorsite_override: nil,
         # The uuid of the push credential for Android
         android_push_credential_id: nil,
+        # Stores the connection preference for generating silent RTP toward the opposite
+        # call leg when comfort-noise packets (CN, payload type 13) are received during
+        # hold. Optional; defaults to false when omitted on creation. Only JSON true and
+        # false are accepted; null and non-boolean values are rejected. This preference is
+        # independent of default_on_hold_comfort_noise_enabled and does not modify that
+        # setting. This API provisions the preference; call-processing behavior is
+        # implemented separately.
+        bridge_generate_comfort_noise_on_cn: nil,
         # Specifies if call cost webhooks should be sent for this connection.
         call_cost_in_webhooks: nil,
         connection_name: nil,
@@ -59,8 +68,8 @@ module Telnyx
         # Encode the SIP contact header sent by Telnyx to avoid issues for NAT or ALG
         # scenarios.
         encode_contact_header_enabled: nil,
-        # Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
-        # TLS.
+        # Enable use of SRTP for encryption. Can only be set when the SIP signaling
+        # transport protocol is TLS.
         encrypted_media: nil,
         inbound: nil,
         # The uuid of the push credential for Ios
@@ -127,6 +136,7 @@ module Telnyx
           active: T::Boolean,
           anchorsite_override: Telnyx::AnchorsiteOverride::OrSymbol,
           android_push_credential_id: T.nilable(String),
+          bridge_generate_comfort_noise_on_cn: T::Boolean,
           call_cost_in_webhooks: T::Boolean,
           connection_name: String,
           conversation_persistence: T::Boolean,
@@ -165,6 +175,14 @@ module Telnyx
         anchorsite_override: nil,
         # The uuid of the push credential for Android
         android_push_credential_id: nil,
+        # Stores the connection preference for generating silent RTP toward the opposite
+        # call leg when comfort-noise packets (CN, payload type 13) are received during
+        # hold. Optional; omitting this field preserves the saved value. Only JSON true
+        # and false are accepted; null and non-boolean values are rejected. This
+        # preference is independent of default_on_hold_comfort_noise_enabled and does not
+        # modify that setting. This API provisions the preference; call-processing
+        # behavior is implemented separately.
+        bridge_generate_comfort_noise_on_cn: nil,
         # Specifies if call cost webhooks should be sent for this connection.
         call_cost_in_webhooks: nil,
         connection_name: nil,
@@ -182,8 +200,8 @@ module Telnyx
         # Encode the SIP contact header sent by Telnyx to avoid issues for NAT or ALG
         # scenarios.
         encode_contact_header_enabled: nil,
-        # Enable use of SRTP for encryption. Cannot be set if the transport_portocol is
-        # TLS.
+        # Enable use of SRTP for encryption. Can only be set when the SIP signaling
+        # transport protocol is TLS.
         encrypted_media: nil,
         inbound: nil,
         # The uuid of the push credential for Ios

data/rbi/telnyx/resources/meeting_sessions/actions.rbi

@@ -23,12 +23,15 @@ module Telnyx
         end
 
         # Sends audio / text-to-speech into a meeting session. With a Telnyx AI Assistant
-        # (or avatar) attached, the bot is a webpage-output bot: the speak audio routes
-        # through the assistant's output page rather than the bot mic and plays once the
-        # assistant is connected -- it is not refused. If that page cannot be reached,
-        # delivery fails with the 502 below, which may arrive without an error envelope,
-        # so branch on the status code before parsing a body. The assistant is designed to
-        # own the conversation, so prefer letting it speak or use `send_chat`.
+        # attached, the bot is a webpage-output bot: the speak audio routes through the
+        # assistant's output page rather than the bot mic and plays once the assistant is
+        # connected -- it is not refused. If that page cannot be reached, delivery fails
+        # with the 502 below, which may arrive without an error envelope, so branch on the
+        # status code before parsing a body. The assistant is designed to own the
+        # conversation, so prefer letting it speak or use `send_chat`. With a digital
+        # avatar (`assistant.avatar: true`), speak is refused with 409 `invalid_state`
+        # (message prefix `avatar_requires_assistant_speech:`): the avatar renders only
+        # the assistant's own speech.
         sig do
           params(
             id: String,
@@ -53,7 +56,10 @@ module Telnyx
         )
         end
 
-        # Stops any active text-to-speech playback in a meeting session.
+        # Stops any active text-to-speech playback in a meeting session. Sessions with a
+        # digital avatar (`assistant.avatar: true`) return 409 `invalid_state` (message
+        # prefix `avatar_requires_assistant_speech:`): the avatar renders only the
+        # assistant's own speech.
         sig do
           params(
             id: String,