telnyx 5.158.0 → 5.160.0

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

@@ -21,6 +21,7 @@ module Telnyx
                   Telnyx::Calls::DeveloperMessage::OrHash
                 )
               ],
+            trigger_response: T::Boolean,
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::Calls::ActionAddAIAssistantMessagesResponse)
         end
@@ -35,6 +36,10 @@ module Telnyx
           command_id: nil,
           # The messages to add to the conversation.
           messages: nil,
+          # When `true`, the injected messages immediately trigger an assistant
+          # response/turn instead of waiting for the next natural turn or idle timeout. This
+          # may interrupt a user who is still speaking.
+          trigger_response: nil,
           request_options: {}
         )
         end
@@ -542,6 +547,10 @@ module Telnyx
           #   `s1`. `VoiceId` is a Fish Voice-Library reference ID.
           # - **xAI:** Use `xAI.<VoiceId>` (e.g., `xAI.eve`). Available voices: `eve`,
           #   `ara`, `rex`, `sal`, `leo`.
+          # - **Humain:** Use `Humain.<VoiceId>` (e.g., `Humain.sara-ar`). Available voices:
+          #   `sara-en`, `abdulaziz-en`, `sara-ar`, `abdulaziz-ar`, `nourah-ar`,
+          #   `abdullah-ar`. Native Arabic (Saudi dialect) and English voices only — no
+          #   `ModelId` segment.
           voice: nil,
           # The settings associated with the voice selected
           voice_settings: nil,
@@ -734,6 +743,10 @@ module Telnyx
           #   `s1`. `VoiceId` is a Fish Voice-Library reference ID.
           # - **xAI:** Use `xAI.<VoiceId>` (e.g., `xAI.eve`). Available voices: `eve`,
           #   `ara`, `rex`, `sal`, `leo`.
+          # - **Humain:** Use `Humain.<VoiceId>` (e.g., `Humain.sara-ar`). Available voices:
+          #   `sara-en`, `abdulaziz-en`, `sara-ar`, `abdulaziz-ar`, `nourah-ar`,
+          #   `abdullah-ar`. Native Arabic (Saudi dialect) and English voices only — no
+          #   `ModelId` segment.
           #
           # For service_level basic, you may define the gender of the speaker (male or
           # female).
@@ -890,6 +903,99 @@ module Telnyx
         )
         end
 
+        # Collect payment details from the caller using DTMF and either charge or tokenize
+        # the payment method through a configured Pay connector. Pay pauses active call
+        # recordings while sensitive payment details are collected.
+        #
+        # When `payment_token` is supplied, the DTMF collection steps are skipped and the
+        # existing token is sent to the connector.
+        #
+        # **Expected Webhooks:**
+        #
+        # - `call.payment.progress`
+        # - `call.payment.completed`
+        #
+        # **Test mode card numbers:** `4111111111111111` (Visa), `5555555555554444`
+        # (Mastercard), `378282246310005` (American Express), `6011111111111117`
+        # (Discover), `3065930009020004` (Diners Club), `3566002020360505` (JCB),
+        # `6200000000000005` (UnionPay), and `6771798021000008` (Maestro). Test-mode
+        # connectors reject other card numbers before contacting the configured processor.
+        # The UnionPay and Maestro numbers are accepted for processor testing, but Pay
+        # currently does not emit a card type for them.
+        sig do
+          params(
+            call_control_id: String,
+            amount: Float,
+            client_state: String,
+            command_id: String,
+            connector_name: String,
+            currency: Telnyx::Calls::ActionPayParams::Currency::OrSymbol,
+            description: String,
+            inter_digit_timeout_millis: Integer,
+            language: String,
+            max_attempts: Integer,
+            metadata: T::Hash[Symbol, T.anything],
+            parameters: T::Hash[Symbol, T.anything],
+            payment_method:
+              Telnyx::Calls::ActionPayParams::PaymentMethod::OrSymbol,
+            payment_token: String,
+            prompts: Telnyx::Calls::ActionPayParams::Prompts::OrHash,
+            service_level: String,
+            timeout_millis: Integer,
+            transaction_type:
+              Telnyx::Calls::ActionPayParams::TransactionType::OrSymbol,
+            voice: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::Calls::ActionPayResponse)
+        end
+        def pay(
+          # Unique identifier and token for controlling the call
+          call_control_id,
+          # Amount to charge. Required when `transaction_type` is `charge`.
+          amount: nil,
+          # Base64-encoded state included in subsequent webhooks.
+          client_state: nil,
+          # Idempotency key for the command. Telnyx ignores a duplicate command with the
+          # same `command_id` for the same `call_control_id`.
+          command_id: nil,
+          # Name of the Pay connector used to process the transaction.
+          connector_name: nil,
+          # Currency used for the transaction. Pay currently supports USD only.
+          currency: nil,
+          # Optional description forwarded with the payment transaction.
+          description: nil,
+          # Time in milliseconds to wait between consecutive DTMF digits.
+          inter_digit_timeout_millis: nil,
+          # Language used for payment prompts.
+          language: nil,
+          # Maximum number of attempts for each payment collection step.
+          max_attempts: nil,
+          # Metadata forwarded to the Pay connector.
+          metadata: nil,
+          # Additional parameters forwarded to the Pay connector.
+          parameters: nil,
+          # Payment method to collect.
+          payment_method: nil,
+          # Existing payment token. When supplied, payment-detail collection is skipped.
+          payment_token: nil,
+          # Custom text-to-speech prompts keyed by payment collection step.
+          prompts: nil,
+          # Speech synthesis service level used for payment prompts. Pay defaults to
+          # `premium`.
+          service_level: nil,
+          # Time in milliseconds to wait for DTMF input for each collection step.
+          timeout_millis: nil,
+          # Transaction to perform. If omitted, Pay infers `tokenize` when `amount` is
+          # absent or zero and `charge` when `amount` is positive.
+          transaction_type: nil,
+          # Voice used for payment prompts. Accepts `male`, `female`, or a provider voice in
+          # `<Provider>.<Model>.<VoiceId>` format, for example `AWS.Polly.Joanna` or
+          # `Telnyx.KokoroTTS.af`.
+          voice: nil,
+          request_options: {}
+        )
+        end
+
         # Initiate a SIP Refer on a Call Control call. You can initiate a SIP Refer at any
         # point in the duration of a call.
         #
@@ -1154,6 +1260,10 @@ module Telnyx
           #   `s1`. `VoiceId` is a Fish Voice-Library reference ID.
           # - **xAI:** Use `xAI.<VoiceId>` (e.g., `xAI.eve`). Available voices: `eve`,
           #   `ara`, `rex`, `sal`, `leo`.
+          # - **Humain:** Use `Humain.<VoiceId>` (e.g., `Humain.sara-ar`). Available voices:
+          #   `sara-en`, `abdulaziz-en`, `sara-ar`, `abdulaziz-ar`, `nourah-ar`,
+          #   `abdullah-ar`. Native Arabic (Saudi dialect) and English voices only — no
+          #   `ModelId` segment.
           #
           # For service_level basic, you may define the gender of the speaker (male or
           # female).
@@ -1217,17 +1327,6 @@ module Telnyx
               T::Array[Telnyx::Calls::AIAssistantJoinParticipant::OrHash],
             send_message_history_updates: T::Boolean,
             transcription: Telnyx::Calls::TranscriptionConfig::OrHash,
-            voice: String,
-            voice_settings:
-              T.any(
-                Telnyx::Calls::ElevenLabsVoiceSettings::OrHash,
-                Telnyx::Calls::TelnyxVoiceSettings::OrHash,
-                Telnyx::Calls::AwsVoiceSettings::OrHash,
-                Telnyx::AzureVoiceSettings::OrHash,
-                Telnyx::RimeVoiceSettings::OrHash,
-                Telnyx::ResembleVoiceSettings::OrHash,
-                Telnyx::XaiVoiceSettings::OrHash
-              ),
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::Calls::ActionStartAIAssistantResponse)
         end
@@ -1263,39 +1362,6 @@ module Telnyx
           # using a model with native audio support (e.g. `fixie-ai/ultravox-v0_4`) will
           # ignore this field.
           transcription: nil,
-          # The voice to be used by the voice assistant. Currently we support ElevenLabs,
-          # Telnyx and AWS voices.
-          #
-          # **Supported Providers:**
-          #
-          # - **AWS:** Use `AWS.Polly.<VoiceId>` (e.g., `AWS.Polly.Joanna`). For neural
-          #   voices, which provide more realistic, human-like speech, append `-Neural` to
-          #   the `VoiceId` (e.g., `AWS.Polly.Joanna-Neural`). Check the
-          #   [available voices](https://docs.aws.amazon.com/polly/latest/dg/available-voices.html)
-          #   for compatibility.
-          # - **Azure:** Use `Azure.<VoiceId>. (e.g. Azure.en-CA-ClaraNeural,
-          #   Azure.en-CA-LiamNeural, Azure.en-US-BrianMultilingualNeural,
-          #   Azure.en-US-Ava:DragonHDLatestNeural. For a complete list of voices, go to
-          #   [Azure Voice Gallery](https://speech.microsoft.com/portal/voicegallery).)
-          # - **ElevenLabs:** Use `ElevenLabs.<ModelId>.<VoiceId>` (e.g.,
-          #   `ElevenLabs.BaseModel.John`). The `ModelId` part is optional. To use
-          #   ElevenLabs, you must provide your ElevenLabs API key as an integration secret
-          #   under `"voice_settings": {"api_key_ref": "<secret_id>"}`. See
-          #   [integration secrets documentation](https://developers.telnyx.com/api/secrets-manager/integration-secrets/create-integration-secret)
-          #   for details. Check
-          #   [available voices](https://elevenlabs.io/docs/api-reference/get-voices).
-          # - **Telnyx:** Use `Telnyx.<model_id>.<voice_id>`
-          # - **Inworld:** Use `Inworld.<ModelId>.<VoiceId>` (e.g., `Inworld.Mini.Loretta`,
-          #   `Inworld.Max.Oliver`, `Inworld.TTS2.Loretta`). Supported models: `Mini`,
-          #   `Max`, `TTS2`.
-          # - **Fish Audio:** Use `FishAudio.<ModelId>.<VoiceId>` (e.g.,
-          #   `FishAudio.s2.1-pro.<reference_id>`). Supported models: `s2.1-pro`, `s2-pro`,
-          #   `s1`. `VoiceId` is a Fish Voice-Library reference ID.
-          # - **xAI:** Use `xAI.<VoiceId>` (e.g., `xAI.eve`). Available voices: `eve`,
-          #   `ara`, `rex`, `sal`, `leo`.
-          voice: nil,
-          # The settings associated with the voice selected
-          voice_settings: nil,
           request_options: {}
         )
         end
@@ -1457,6 +1523,10 @@ module Telnyx
           #   `s1`. `VoiceId` is a Fish Voice-Library reference ID.
           # - **xAI:** Use `xAI.<VoiceId>` (e.g., `xAI.eve`). Available voices: `eve`,
           #   `ara`, `rex`, `sal`, `leo`.
+          # - **Humain:** Use `Humain.<VoiceId>` (e.g., `Humain.sara-ar`). Available voices:
+          #   `sara-en`, `abdulaziz-en`, `sara-ar`, `abdulaziz-ar`, `nourah-ar`,
+          #   `abdullah-ar`. Native Arabic (Saudi dialect) and English voices only — no
+          #   `ModelId` segment.
           voice: nil,
           # The settings associated with the voice selected
           voice_settings: nil,
@@ -1509,7 +1579,8 @@ module Telnyx
         )
         end
 
-        # Noise Suppression Start (BETA)
+        # Start noise suppression on an active call to reduce background noise. This
+        # feature is currently in beta.
         sig do
           params(
             call_control_id: String,
@@ -1861,6 +1932,8 @@ module Telnyx
                 Telnyx::Calls::TranscriptionEngineSpeechmaticsConfig::OrHash,
                 Telnyx::Calls::TranscriptionEngineSonioxConfig::OrHash,
                 Telnyx::Calls::TranscriptionEngineParakeetConfig::OrHash,
+                Telnyx::Calls::TranscriptionStartRequest::TranscriptionEngineConfig::Humain::OrHash,
+                Telnyx::Calls::TranscriptionStartRequest::TranscriptionEngineConfig::Reson8::OrHash,
                 Telnyx::Calls::TranscriptionEngineAConfig::OrHash,
                 Telnyx::Calls::TranscriptionEngineBConfig::OrHash,
                 Telnyx::Calls::DeepgramNova2Config::OrHash,
@@ -1992,7 +2065,8 @@ module Telnyx
         )
         end
 
-        # Noise Suppression Stop (BETA)
+        # Stop noise suppression previously started on an active call. This feature is
+        # currently in beta.
         sig do
           params(
             call_control_id: String,
@@ -2226,6 +2300,7 @@ module Telnyx
               Telnyx::Calls::ActionTransferParams::RecordTrack::OrSymbol,
             record_trim:
               Telnyx::Calls::ActionTransferParams::RecordTrim::OrSymbol,
+            route_to_mobile: T::Boolean,
             send_digits_on_answer: String,
             sip_auth_password: String,
             sip_auth_username: String,
@@ -2355,6 +2430,13 @@ module Telnyx
           # When set to `trim-silence`, silence will be removed from the beginning and end
           # of the recording.
           record_trim: nil,
+          # When set to true, routes the call directly to the mobile device associated with
+          # the destination Telnyx Mobile number, bypassing Inbound Calls Interception
+          # configured in the Telnyx Portal under Mobile Numbers → select the number → Voice
+          # → Call Interception. Use this when transferring an intercepted call to the
+          # mobile device to prevent the call from being intercepted again. Defaults to
+          # false.
+          route_to_mobile: nil,
           # DTMF digits to send automatically after the transfer destination answers. Useful
           # for reaching an extension behind an IVR (e.g. `"200"` to dial extension 200 once
           # the called party picks up). Allowed characters: `0-9`, `A-D`, `w` (0.5s pause),

data/rbi/telnyx/resources/calls.rbi

@@ -71,6 +71,7 @@ module Telnyx
           record_track: Telnyx::CallDialParams::RecordTrack::OrSymbol,
           record_trim: Telnyx::CallDialParams::RecordTrim::OrSymbol,
           retry_on_timeout: T::Boolean,
+          route_to_mobile: T::Boolean,
           send_digits_on_answer: String,
           send_silence_when_idle: T::Boolean,
           sip_auth_password: String,
@@ -264,6 +265,13 @@ module Telnyx
         # entire dial attempt and the `call.hangup` webhook reports a `hangup_cause` of
         # `no_answer` instead of `timeout`.
         retry_on_timeout: nil,
+        # When set to true, routes the call directly to the mobile device associated with
+        # the destination Telnyx Mobile number, bypassing Inbound Calls Interception
+        # configured in the Telnyx Portal under Mobile Numbers → select the number → Voice
+        # → Call Interception. Use this when transferring an intercepted call to the
+        # mobile device to prevent the call from being intercepted again. Defaults to
+        # false.
+        route_to_mobile: nil,
         # DTMF digits to send automatically after the called party answers. Useful for
         # reaching an extension behind an IVR (e.g. `"200"` to dial extension 200 once the
         # called party picks up). Allowed characters: `0-9`, `A-D`, `w` (0.5s pause), `W`

data/rbi/telnyx/resources/comments.rbi

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

data/rbi/telnyx/resources/conferences/actions.rbi

@@ -590,6 +590,10 @@ module Telnyx
           #   `s1`. `VoiceId` is a Fish Voice-Library reference ID.
           # - **xAI:** Use `xAI.<VoiceId>` (e.g., `xAI.eve`). Available voices: `eve`,
           #   `ara`, `rex`, `sal`, `leo`.
+          # - **Humain:** Use `Humain.<VoiceId>` (e.g., `Humain.sara-ar`). Available voices:
+          #   `sara-en`, `abdulaziz-en`, `sara-ar`, `abdulaziz-ar`, `nourah-ar`,
+          #   `abdullah-ar`. Native Arabic (Saudi dialect) and English voices only — no
+          #   `ModelId` segment.
           #
           # For service_level basic, you may define the gender of the speaker (male or
           # female).

data/rbi/telnyx/resources/credential_connections.rbi

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

data/rbi/telnyx/resources/custom_storage_credentials.rbi

@@ -13,6 +13,7 @@ module Telnyx
             T.any(
               Telnyx::GcsConfigurationData::OrHash,
               Telnyx::S3ConfigurationData::OrHash,
+              Telnyx::CustomStorageConfiguration::Configuration::S3Generic::OrHash,
               Telnyx::AzureConfigurationData::OrHash
             ),
           request_options: Telnyx::RequestOptions::OrHash
@@ -52,6 +53,7 @@ module Telnyx
             T.any(
               Telnyx::GcsConfigurationData::OrHash,
               Telnyx::S3ConfigurationData::OrHash,
+              Telnyx::CustomStorageConfiguration::Configuration::S3Generic::OrHash,
               Telnyx::AzureConfigurationData::OrHash
             ),
           request_options: Telnyx::RequestOptions::OrHash

data/rbi/telnyx/resources/dir/references.rbi

@@ -13,9 +13,29 @@ module Telnyx
         # endpoint). Until it is, this returns `409` and no references are stored.
         #
         # The request body carries exactly two business references plus one financial
-        # reference. On success the references are stored and the response echoes them in
-        # the same shape as the GET. Submitting again converges on the already-stored
-        # references rather than erroring.
+        # reference. The first submission stores them and returns `201`. Resubmitting
+        # returns `200`: identical values are simply confirmed and nothing is written,
+        # while changed values replace those references.
+        #
+        # Replacing a reference is allowed only while the DIR itself is still editable,
+        # the same window in which a single reference may be updated; once the DIR has
+        # been submitted for vetting this returns `400`. A replaced reference's pending
+        # verification call is cancelled and its dial-in code stops working, and the
+        # replacement contact is emailed fresh scheduling details. References whose
+        # details did not change keep their existing call, code, and the notice already
+        # sent to them.
+        #
+        # The response always echoes the stored references in the same shape as the GET.
+        #
+        # Who qualifies: the two business references confirm the company's reputation and
+        # operations. Each should be a senior contact at an organization the business
+        # works with, such as a vendor, partner, or client: a C-suite executive (CEO, CFO,
+        # CTO, COO), an owner or founder as reflected in the company's corporate records,
+        # or a senior manager, director, or executive. The financial reference confirms
+        # the company pays its bills and should be a licensed certified public accountant
+        # (CPA) the company uses, a contact at a bank or financial institution that has a
+        # relationship with the company, or a reasonable alternative banking or financial
+        # reference.
         sig do
           params(
             dir_id: String,
@@ -27,7 +47,13 @@ module Telnyx
         def create(
           # The DIR id. Lowercase UUID.
           dir_id,
-          # Exactly two business references.
+          # Exactly two business references. Array order determines each one's slot: the
+          # first entry becomes slot 1 and the second becomes slot 2. Those slots are what
+          # you pass when updating a single reference later. Each should be a senior contact
+          # who can speak to your company's reputation and operations: a C-suite executive
+          # (CEO, CFO, CTO, COO), an owner or founder as reflected in your corporate
+          # records, or a senior manager, director, or executive at an organization you work
+          # with, such as a vendor, partner, or client.
           business_references:,
           # One reference supplied at submit. The reference type is implied by the field
           # that carries it (business_references vs financial_reference).
@@ -60,8 +86,11 @@ module Telnyx
           ).returns(Telnyx::Models::Dir::ReferenceUpdateResponse)
         end
         def update(
-          # Path param: Reference slot. Business references use slots 0 and 1; the financial
-          # reference uses slot 0.
+          # Path param: Reference slot, counting from 1. Business references are slots 1 and
+          # 2, matching the order they were sent in the `business_references` array; the
+          # financial reference is slot 1. Every reference returned by the submit and list
+          # endpoints carries its own `ref_type` and `slot`, so you do not need to derive
+          # them.
           slot,
           # Path param: The DIR id. Lowercase UUID.
           dir_id:,
@@ -87,10 +116,12 @@ module Telnyx
 
         # List the business and financial references submitted for a DIR.
         #
-        # Returns the two business references (slots 0 and 1) followed by the single
-        # financial reference. Each entry carries only the customer-supplied details
-        # (name, title, organization, relationship, phone, email, timezone). Returns an
-        # empty list when no references were submitted.
+        # Returns the two business references (slots 1 and 2) followed by the single
+        # financial reference. Each entry carries its `ref_type` and `slot`, which
+        # together address the reference when updating it, alongside the details supplied
+        # when it was submitted (name, title, organization, relationship, phone, email,
+        # timezone). No internal identifiers are exposed. Returns an empty list when no
+        # references were submitted.
         sig do
           params(
             dir_id: String,

data/rbi/telnyx/resources/dir.rbi

@@ -250,8 +250,9 @@ module Telnyx
       # numbers flip back to `submitted`. When re-submitting from `verified`, the
       # existing registration stays live throughout the new vetting cycle.
       #
-      # Returns `400` from `submitted`/`in_review`/`permanently_rejected`. Returns `409`
-      # if the DIR has an unresolved infringement claim.
+      # Returns `400` from `submitted`/`in_review`/`permanently_rejected`. Returns `400`
+      # if the DIR's business and financial references have not been submitted. Returns
+      # `409` if the DIR has an unresolved infringement claim.
       sig do
         params(
           dir_id: String,

data/rbi/telnyx/resources/email_blocks/import.rbi

@@ -0,0 +1,61 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class EmailBlocks
+      # Async CSV import of competitor suppression lists.
+      class Import
+        # Accepts `multipart/form-data` with a `file` field (the CSV) and an optional
+        # `block_ttl_days` (integer >0, default 30). Validates:
+        #
+        # - content ≤ 25 MiB, else `413`
+        # - row count ≤ 250 000, else `413`
+        # - header-only / all-blank / undetectable provider → `400` Returns `202` with the
+        #   import record (status `pending`); an Oban worker (`EmailBlockImportWorker`,
+        #   max_attempts 3) transitions `pending → processing → completed | failed`.
+        #   `block_ttl_days` applies only to imported `manual_block` rows; other reasons
+        #   get `expires_at: nil`. Provider is auto-detected from the CSV header
+        #   (`sendgrid` / `mailgun` / `ses` / `generic`).
+        sig do
+          params(
+            file: Telnyx::Internal::FileInput,
+            block_ttl_days: Integer,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailBlocks::EmailBlockImportResponse)
+        end
+        def create(
+          # The CSV file (Plug.Upload). Missing/non-upload → 400.
+          file:,
+          # TTL for imported `manual_block` rows; other reasons get `expires_at: null`.
+          # Invalid/missing → falls back to 30.
+          block_ttl_days: nil,
+          request_options: {}
+        )
+        end
+
+        # Account-scoped fetch (cross-account → 404; malformed UUID → 404). Nullable
+        # fields are omitted until terminal: `provider`/`completed_at` when nil;
+        # `processed_rows`/`created_count`/`existing_count`/ `skipped_count`/`error_count`
+        # only when `status == completed`; `errors` only when non-empty; `failure_reason`
+        # only on terminal failure.
+        sig do
+          params(
+            id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::EmailBlocks::EmailBlockImportResponse)
+        end
+        def retrieve(
+          # Resource UUID. Malformed UUIDs are treated as not-found (not 400).
+          id,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end