telnyx 5.169.0 → 5.171.0

data/lib/telnyx/resources/calls/actions.rb

@@ -44,9 +44,33 @@ module Telnyx
         # Answer an incoming call. You must issue this command before executing subsequent
         # commands on an incoming call.
         #
+        # To answer with an AI assistant, include `assistant.id` and any per-call
+        # overrides in the `assistant` object. Telnyx attempts to warm up the assistant
+        # before answering the call, then starts the assistant automatically when the call
+        # is answered. Do not also send `ai_assistant_start` for this flow. The HTTP
+        # success response can arrive before the call is answered; use the `call.answered`
+        # webhook to track the answer. If warm-up fails, Telnyx falls back to starting the
+        # assistant after answering.
+        #
+        # When `assistant.id` is supplied, obtain the conversation ID from
+        # `data.payload.conversation_id` in the
+        # [call.conversation.created](/api-reference/callbacks/call-conversation-created)
+        # webhook and correlate it using `data.payload.call_control_id`. The `answer` HTTP
+        # response does not include `conversation_id`. The created event is emitted during
+        # assistant startup and does not indicate that the assistant is ready to speak.
+        #
+        # Set the assistant voice with `assistant.voice_settings.voice` and speech-to-text
+        # settings with `assistant.transcription`. You can reuse one stored assistant with
+        # different per-call settings. Warm-up prepares assistant configuration and
+        # dependencies; it does not wait for the greeting audio to be ready or guarantee
+        # zero silence after answer. A plain `answer` followed by `ai_assistant_start`
+        # performs assistant startup after the call has already been answered.
+        #
         # **Expected Webhooks:**
         #
         # - `call.answered`
+        # - `call.conversation.created` when the requested assistant conversation is
+        #   created
         # - `call.hold` and `call.unhold` if the call is held/unheld
         # - `call.deepfake_detection.result` if `deepfake_detection` was enabled
         # - `call.deepfake_detection.error` if `deepfake_detection` was enabled and an
@@ -61,7 +85,7 @@ module Telnyx
         #
         # @param call_control_id [String] Unique identifier and token for controlling the call
         #
-        # @param assistant [Telnyx::Models::CallAssistantRequest] AI Assistant configuration. All fields except `id` are optional — the assistant'
+        # @param assistant [Telnyx::Models::CallAssistantRequest] AI Assistant configuration and per-call overrides. All fields except `id` are op
         #
         # @param billing_group_id [String] Use this field to set the Billing Group ID for the call. Must be a valid and exi
         #
@@ -112,7 +136,7 @@ module Telnyx
         #
         # @param stream_url [String] The destination WebSocket address where the stream is going to be delivered.
         #
-        # @param transcription [Boolean] Enable transcription upon call answer. The default value is false.
+        # @param transcription [Boolean] Enable standalone call transcription upon call answer. The default value is fals
         #
         # @param transcription_config [Telnyx::Models::Calls::TranscriptionStartRequest]
         #
@@ -314,6 +338,8 @@ module Telnyx
         #
         # **Expected Webhooks:**
         #
+        # - [`call.conversation.created`](/api-reference/callbacks/call-conversation-created)
+        #   includes `conversation_id` during startup
         # - `call.ai_gather.ended`
         # - `call.conversation.ended`
         # - `call.ai_gather.partial_results` (if `send_partial_results` is set to `true`)
@@ -352,7 +378,7 @@ module Telnyx
         #
         # @param voice [String] The voice to be used by the voice assistant. Currently we support ElevenLabs, Te
         #
-        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::XaiVoiceSettings] The settings associated with the voice selected
+        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::XaiVoiceSettings, Telnyx::Models::Calls::SonioxVoiceSettings] The settings associated with the voice selected
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -485,7 +511,7 @@ module Telnyx
         #
         # @param valid_digits [String] A list of all digits accepted as valid.
         #
-        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings] The settings associated with the voice selected
+        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings, Telnyx::Models::Calls::SonioxVoiceSettings] The settings associated with the voice selected
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -661,7 +687,7 @@ module Telnyx
         # The UnionPay and Maestro numbers are accepted for processor testing, but Pay
         # currently does not emit a card type for them.
         #
-        # @overload pay(call_control_id, amount: nil, client_state: nil, command_id: nil, connector_name: nil, currency: nil, description: nil, inter_digit_timeout_millis: nil, language: nil, max_attempts: nil, metadata: nil, parameters: nil, payment_method: nil, payment_token: nil, prompts: nil, service_level: nil, timeout_millis: nil, transaction_type: nil, valid_card_types: nil, voice: nil, request_options: {})
+        # @overload pay(call_control_id, amount: nil, client_state: nil, command_id: nil, connector_name: nil, currency: nil, description: nil, inter_digit_timeout_millis: nil, language: nil, max_attempts: nil, metadata: nil, min_postal_code_length: nil, parameters: nil, payment_method: nil, payment_token: nil, postal_code: nil, prompts: nil, service_level: nil, timeout_millis: nil, transaction_type: nil, valid_card_types: nil, voice: nil, request_options: {})
         #
         # @param call_control_id [String] Unique identifier and token for controlling the call
         #
@@ -685,12 +711,16 @@ module Telnyx
         #
         # @param metadata [Hash{Symbol=>Object}] Metadata forwarded to the Pay connector.
         #
+        # @param min_postal_code_length [Integer] Minimum number of digits the caller must enter when collecting a credit-card bil
+        #
         # @param parameters [Hash{Symbol=>Object}] Additional parameters forwarded to the Pay connector.
         #
         # @param payment_method [Symbol, Telnyx::Models::Calls::ActionPayParams::PaymentMethod] Payment method to collect.
         #
         # @param payment_token [String] Existing payment token. When supplied, payment-detail collection is skipped.
         #
+        # @param postal_code [String, Boolean] Controls billing postal code collection for credit-card payments when no `paymen
+        #
         # @param prompts [Telnyx::Models::Calls::ActionPayParams::Prompts] Custom text-to-speech prompts keyed by payment collection step.
         #
         # @param service_level [String] Speech synthesis service level used for payment prompts. Pay defaults to `premiu
@@ -778,7 +808,7 @@ module Telnyx
         #
         # @param call_control_id [String] Unique identifier and token for controlling the call
         #
-        # @param cause [Symbol, Telnyx::Models::Calls::ActionRejectParams::Cause] Cause for call rejection.
+        # @param cause [Symbol, Telnyx::Models::Calls::ActionRejectParams::Cause] Cause for call rejection. The cause sets the SIP response the caller receives: `
         #
         # @param client_state [String] Use this field to add state to every subsequent webhook. It must be a valid Base
         #
@@ -947,7 +977,7 @@ module Telnyx
         #
         # @param target_legs [Symbol, Telnyx::Models::Calls::ActionSpeakParams::TargetLegs] Specifies which legs of the call should receive the spoken audio.
         #
-        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings] The settings associated with the voice selected
+        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings, Telnyx::Models::Calls::SonioxVoiceSettings] The settings associated with the voice selected
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -972,6 +1002,8 @@ module Telnyx
         #
         # **Expected Webhooks:**
         #
+        # - [`call.conversation.created`](/api-reference/callbacks/call-conversation-created)
+        #   includes `conversation_id` during startup
         # - `call.conversation.ended`
         # - `call.conversation_insights.generated`
         #
@@ -979,7 +1011,7 @@ module Telnyx
         #
         # @param call_control_id [String] Unique identifier and token for controlling the call
         #
-        # @param assistant [Telnyx::Models::CallAssistantRequest] AI Assistant configuration. All fields except `id` are optional — the assistant'
+        # @param assistant [Telnyx::Models::CallAssistantRequest] AI Assistant configuration and per-call overrides. All fields except `id` are op
         #
         # @param client_state [String] Use this field to add state to every subsequent webhook. It must be a valid Base
         #
@@ -1068,7 +1100,7 @@ module Telnyx
         #
         # @param transcription_engine [Symbol, Telnyx::Models::Calls::ActionStartConversationRelayParams::TranscriptionEngine] Engine to use for speech recognition. Legacy values `A` - `Google`, `B` - `Telny
         #
-        # @param transcription_engine_config [Hash{Symbol=>Object}] Engine-specific transcription settings for Conversation Relay. This accepts the
+        # @param transcription_engine_config [Telnyx::Models::Calls::ConversationRelayTranscriptionEngineConfig] Engine-specific transcription settings for Conversation Relay. This accepts the
         #
         # @param tts_provider [String] Text-to-speech provider. If omitted, Telnyx derives it from `voice` or `provider
         #
@@ -1076,7 +1108,7 @@ module Telnyx
         #
         # @param voice [String] The voice to be used by the voice assistant. Currently we support ElevenLabs, Te
         #
-        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings] The settings associated with the voice selected
+        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings, Telnyx::Models::Calls::SonioxVoiceSettings] The settings associated with the voice selected
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -1817,6 +1849,9 @@ module Telnyx
         #   `answering_machine_detection=premium` was requested
         # - `call.machine.premium.greeting.ended` if `answering_machine_detection=premium`
         #   was requested and a beep was detected
+        # - `call.machine.premium.call_screening.detected` if
+        #   `answering_machine_detection=premium_ios_call_screening_detection` was
+        #   requested and an Apple Call Screening tone was detected
         #
         # @overload transfer(call_control_id, to:, answering_machine_detection: nil, answering_machine_detection_config: nil, audio_url: nil, client_state: nil, command_id: nil, custom_headers: nil, diversion: nil, early_media: nil, from: nil, from_display_name: nil, media_encryption: nil, media_name: nil, mute_dtmf: nil, park_after_unbridge: nil, preferred_codecs: nil, privacy: nil, record: nil, record_channels: nil, record_custom_file_name: nil, record_format: nil, record_max_length: nil, record_timeout_secs: nil, record_track: nil, record_trim: nil, route_to_mobile: nil, send_digits_on_answer: nil, sip_auth_password: nil, sip_auth_username: nil, sip_headers: nil, sip_region: nil, sip_transport_protocol: nil, sound_modifications: nil, target_leg_client_state: nil, time_limit_secs: nil, timeout_secs: nil, webhook_retries_policies: nil, webhook_url: nil, webhook_url_method: nil, webhook_urls: nil, webhook_urls_method: nil, request_options: {})
         #

data/lib/telnyx/resources/calls.rb

@@ -14,10 +14,18 @@ module Telnyx
       # include a `call_leg_id` which can be used to correlate the command with
       # subsequent webhooks.
       #
+      # To place the call with an AI assistant from the start, include `assistant.id`
+      # and any per-call overrides in the `assistant` object; Telnyx attempts to warm up
+      # the assistant before placing the call and starts it automatically when the
+      # called party answers.
+      #
       # **Expected Webhooks:**
       #
       # - `call.initiated`
       # - `call.answered` or `call.hangup`
+      # - `call.conversation.created` when the requested assistant conversation is
+      #   created, or `call.conversation.start_failed` when it could not be started
+      #   after the called party answered
       # - `call.hold` and `call.unhold` if the call is held/unheld
       # - `call.machine.detection.ended` if `answering_machine_detection` was requested
       # - `call.machine.greeting.ended` if `answering_machine_detection` was requested
@@ -26,6 +34,9 @@ module Telnyx
       #   `answering_machine_detection=premium` was requested
       # - `call.machine.premium.greeting.ended` if `answering_machine_detection=premium`
       #   was requested and a beep was detected
+      # - `call.machine.premium.call_screening.detected` if
+      #   `answering_machine_detection=premium_ios_call_screening_detection` was
+      #   requested and an Apple Call Screening tone was detected
       # - `call.deepfake_detection.result` if `deepfake_detection` was enabled
       # - `call.deepfake_detection.error` if `deepfake_detection` was enabled and an
       #   error occurred
@@ -47,7 +58,7 @@ module Telnyx
       #
       # @param answering_machine_detection_config [Telnyx::Models::CallDialParams::AnsweringMachineDetectionConfig] Optional configuration parameters to modify 'answering_machine_detection' perfor
       #
-      # @param assistant [Telnyx::Models::CallAssistantRequest] AI Assistant configuration. All fields except `id` are optional — the assistant'
+      # @param assistant [Telnyx::Models::CallAssistantRequest] AI Assistant configuration and per-call overrides. All fields except `id` are op
       #
       # @param audio_url [String] The URL of a file to be played back to the callee when the call is answered. The
       #

data/lib/telnyx/resources/conferences/actions.rb

@@ -522,7 +522,7 @@ module Telnyx
         #
         # @param region [Symbol, Telnyx::Models::Conferences::ConferenceRegion] Region where the conference data is located. Defaults to the region defined in u
         #
-        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings] The settings associated with the voice selected
+        # @param voice_settings [Telnyx::Models::Calls::ElevenLabsVoiceSettings, Telnyx::Models::Calls::TelnyxVoiceSettings, Telnyx::Models::Calls::AwsVoiceSettings, Telnyx::Models::MinimaxVoiceSettings, Telnyx::Models::AzureVoiceSettings, Telnyx::Models::ResembleVoiceSettings, Telnyx::Models::InworldVoiceSettings, Telnyx::Models::XaiVoiceSettings, Telnyx::Models::Calls::SonioxVoiceSettings] The settings associated with the voice selected
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/telnyx/resources/dir/phone_numbers.rb

@@ -12,7 +12,7 @@ module Telnyx
         # List the phone numbers registered under a DIR. The enterprise is resolved
         # server-side from the DIR id.
         #
-        # @overload list(dir_id, page_number: nil, page_size: nil, status: nil, request_options: {})
+        # @overload list(dir_id, page_number: nil, page_size: nil, request_options: {})
         #
         # @param dir_id [String] The DIR id. Lowercase UUID.
         #
@@ -20,8 +20,6 @@ module Telnyx
         #
         # @param page_size [Integer] Items per page. Maximum 250; values above are clamped to 250.
         #
-        # @param status [Symbol, Telnyx::Models::Dir::DirPhoneNumberStatus] Filter by phone-number status.
-        #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::Dir::DirPhoneNumber>]
@@ -44,11 +42,11 @@ module Telnyx
         # {Telnyx::Models::Dir::PhoneNumberAddParams} for more details.
         #
         # Register phone numbers under a DIR. The enterprise is resolved server-side from
-        # the DIR id. Same body, failure modes, and batch semantics whichever path form
-        # you use.
+        # the DIR id.
         #
-        # **Pricing:** This is a billable action. See https://telnyx.com/pricing/numbers
-        # for current pricing.
+        # **Pricing:** Adding phone numbers is free. Branded Calling fees are charged per
+        # DIR and per branded call. See https://telnyx.com/pricing/branded-calling for
+        # current pricing.
         #
         # @overload add(dir_id, documents:, phone_numbers:, request_options: {})
         #
@@ -74,6 +72,9 @@ module Telnyx
           )
         end
 
+        # Some parameter documentations has been truncated, see
+        # {Telnyx::Models::Dir::PhoneNumberRemoveParams} for more details.
+        #
         # Deregister phone numbers from a DIR. The enterprise is resolved server-side from
         # the DIR id. Returns a partial-success envelope.
         #
@@ -81,7 +82,7 @@ module Telnyx
         #
         # @param dir_id [String] The DIR id. Lowercase UUID.
         #
-        # @param phone_numbers [Array<String>]
+        # @param phone_numbers [Array<String>] The phone numbers to remove from this brand, in E.164 format, up to 100 per requ
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/telnyx/resources/dir/references.rb

@@ -84,19 +84,19 @@ module Telnyx
         #
         # @param ref_type [Symbol, Telnyx::Models::Dir::ReferenceUpdateParams::RefType] Path param: Reference type to address.
         #
-        # @param email [String] Body param: Reference contact email address.
+        # @param email [String] Body param: The reference's email address. We email them scheduling and dial-in
         #
-        # @param full_name [String] Body param: Full name of the reference contact.
+        # @param full_name [String] Body param: The full name of the person we should contact as your reference.
         #
-        # @param job_title [String, nil] Body param: Job title of the reference contact.
+        # @param job_title [String, nil] Body param: The reference contact's job title, for example CFO or Owner.
         #
-        # @param organization [String, nil] Body param: Organization the reference contact belongs to.
+        # @param organization [String, nil] Body param: The name of the organization the reference contact works for.
         #
-        # @param phone_e164 [String] Body param: Reference phone number in E.164 format.
+        # @param phone_e164 [String] Body param: The reference's phone number in E.164 format, for example +141555501
         #
         # @param relationship_to_registrant [String, nil] Body param: How the reference contact is related to the registering business.
         #
-        # @param timezone [String] Body param: IANA timezone id for the reference.
+        # @param timezone [String] Body param: The reference's IANA time zone, for example America/New_York. We onl
         #
         # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
         #

data/lib/telnyx/resources/dir.rb

@@ -56,14 +56,17 @@ module Telnyx
       # Edit a DIR. DIRs in `draft`, `rejected`, `unsuccessful`, or `suspended` can be
       # edited freely: PATCH is a pure edit, `status` is never changed, and you re-vet
       # by calling `POST /v2/dir/{dir_id}/submit` explicitly. A `verified` DIR can also
-      # be edited in place: a PATCH that changes any value returns the DIR to `draft`
-      # and branded delivery stops until you re-submit and the DIR is approved again,
-      # while a PATCH that changes nothing (an empty body or values identical to the
-      # current ones) leaves the DIR `verified`, so idempotent retries are safe. DIRs in
-      # any other status (`submitted`, `in_review`, `expired`, `infringement_claimed`,
+      # be edited in place: a PATCH that changes any value returns the DIR to `draft`;
+      # the currently approved identity keeps displaying, and the edited content goes
+      # live only after you re-submit and the DIR is approved again. A PATCH that
+      # changes nothing (an empty body or values identical to the current ones) leaves
+      # the DIR `verified`, so idempotent retries are safe. Changing only
+      # `bpo_authorizations` or `webhook_url` is the exception: the DIR stays
+      # `verified`. Each BPO authorization is reviewed on its own instead. DIRs in any
+      # other status (`submitted`, `in_review`, `expired`, `infringement_claimed`,
       # `permanently_rejected`) cannot be edited.
       #
-      # @overload update(dir_id, authorizer_email: nil, authorizer_name: nil, call_reasons: nil, certify_brand_is_accurate: nil, certify_ip_ownership: nil, certify_no_shaft_content: nil, display_name: nil, documents: nil, logo_url: nil, reselling: nil, request_options: {})
+      # @overload update(dir_id, authorizer_email: nil, authorizer_name: nil, bpo_authorizations: nil, call_reasons: nil, certify_brand_is_accurate: nil, certify_ip_ownership: nil, certify_no_shaft_content: nil, display_name: nil, documents: nil, logo_url: nil, reselling: nil, webhook_url: nil, request_options: {})
       #
       # @param dir_id [String] The DIR id. Lowercase UUID.
       #
@@ -71,6 +74,8 @@ module Telnyx
       #
       # @param authorizer_name [String] Name of the person at your enterprise authorizing this DIR. Must be a real indiv
       #
+      # @param bpo_authorizations [Array<Telnyx::Models::BpoAuthorizationInput>] Optional. Replace this DIR's authorized BPO (Business Process Outsourcer) accoun
+      #
       # @param call_reasons [Array<String>] 1–10 reasons your business calls customers. Validate phrasing against `POST /cal
       #
       # @param certify_brand_is_accurate [Boolean] Certification that the DIR information is accurate. Must be `true` for the DIR t
@@ -87,6 +92,8 @@ module Telnyx
       #
       # @param reselling [Boolean] Set to true if your organization places calls on behalf of other enterprises (BP
       #
+      # @param webhook_url [String, nil] Optional `https://` URL that receives webhook notifications when this DIR's comp
+      #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Telnyx::Models::DirWrapped]
@@ -162,9 +169,13 @@ module Telnyx
         )
       end
 
-      # Delete a DIR. Failure modes: `400` if a child phone number is in a non-deletable
-      # status, `409` if the DIR has an unresolved infringement claim, `404` if the DIR
-      # is not yours.
+      # Request deletion of a DIR. This does not remove the DIR on this call: it records
+      # the request, moves the DIR to `delete_requested`, and Telnyx completes the
+      # removal (de-registration and cleanup) shortly after. A verified DIR keeps
+      # serving its branded identity, and keeps billing, until the removal is executed.
+      # Failure modes: `400` if a child phone number is still attached or the DIR is
+      # `in_review` (wait for the review to finish), `409` if the DIR has an unresolved
+      # infringement claim, `404` if the DIR is not yours.
       #
       # @overload delete(dir_id, request_options: {})
       #
@@ -172,18 +183,59 @@ module Telnyx
       #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [nil]
+      # @return [Telnyx::Models::DirDeleteResponse]
       #
       # @see Telnyx::Models::DirDeleteParams
       def delete(dir_id, params = {})
         @client.request(
           method: :delete,
           path: ["dir/%1$s", dir_id],
-          model: NilClass,
+          model: Telnyx::Models::DirDeleteResponse,
           options: params[:request_options]
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Telnyx::Models::DirBpoLoaParams} for more details.
+      #
+      # The Letter of Authorization in which a Brand Owner authorizes an approved BPO
+      # (Business Process Outsourcer) to place branded calls that display this DIR on
+      # the owner's behalf. Both parties are read from the caller's account: the Brand
+      # Owner is the enterprise that owns the DIR, and the BPO is `bpo_enterprise_id`.
+      # No business identity is accepted in the body.
+      #
+      # When `signature` is omitted the PDF is returned unsigned so the Brand Owner can
+      # sign it externally and the BPO can upload it via the Documents API. When
+      # `signature` is present the PDF embeds the supplied image, printed name, and
+      # signed-at date.
+      #
+      # Returns `application/pdf`.
+      #
+      # @overload bpo_loa(dir_id, bpo_enterprise_id:, signature: nil, request_options: {})
+      #
+      # @param dir_id [String] The DIR id.
+      #
+      # @param bpo_enterprise_id [String] The approved BPO enterprise the Brand Owner is authorizing. Must be a BPO accoun
+      #
+      # @param signature [Telnyx::Models::SignaturePayload] Optional. When provided the rendered PDF embeds the signature image, printed nam
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [StringIO]
+      #
+      # @see Telnyx::Models::DirBpoLoaParams
+      def bpo_loa(dir_id, params)
+        parsed, options = Telnyx::DirBpoLoaParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["dir/%1$s/bpo_loa", dir_id],
+          headers: {"accept" => "application/pdf"},
+          body: parsed,
+          model: StringIO,
+          options: options
+        )
+      end
+
       # Reference list of `document_type` values accepted by
       # `DirCreateRequest.documents[].document_type` and the infringement-contest
       # endpoint. Each entry has a stable `short_name` (used in API calls) and a
@@ -261,9 +313,9 @@ module Telnyx
       #
       # @param phone_numbers [Array<String>] Telephone numbers to authorize on the DIR, in `+E164` format (`+` followed by 10
       #
-      # @param agent [Telnyx::Models::Enterprises::Reputation::AgentInput] Third-party reseller / partner managing the enterprise's phone numbers. Omit whe
+      # @param agent [Telnyx::Models::Enterprises::Reputation::AgentInput] Third-party reseller / partner managing the enterprise's phone numbers on its be
       #
-      # @param signature [Telnyx::Models::DirNewLoaParams::Signature] Optional. When provided the rendered PDF embeds the signature image, printed nam
+      # @param signature [Telnyx::Models::SignaturePayload] Optional. When provided the rendered PDF embeds the signature image, printed nam
       #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #
@@ -282,6 +334,47 @@ module Telnyx
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Telnyx::Models::DirRetrieveBpoAuthorizationsParams} for more details.
+      #
+      # List the BPO (Business Process Outsourcer) accounts a Brand Owner has authorized
+      # on this DIR, together with the review state of each authorization.
+      #
+      # Authorizations are supplied as the `bpo_authorizations` array when creating or
+      # updating a DIR, and each one is reviewed on its own. Only an `approved`
+      # authorization adds that BPO to this DIR's authorized callers in the branded
+      # calling registry; `pending` and `rejected` authorizations do not. Each entry
+      # includes the `loa_document_id` you submitted: because `bpo_authorizations`
+      # replaces the whole list on every DIR update, send each entry you want to keep
+      # back with its `loa_document_id` unchanged, and it keeps its review state. A
+      # rejected entry carries a `rejection_reason`. Returns an empty list when the DIR
+      # has authorized no BPOs.
+      #
+      # @overload retrieve_bpo_authorizations(dir_id, page_number: nil, page_size: nil, request_options: {})
+      #
+      # @param dir_id [String] The DIR id. Lowercase UUID.
+      #
+      # @param page_number [Integer] 1-based page number. Out-of-range values return an empty page with correct meta.
+      #
+      # @param page_size [Integer] Items per page. Maximum 250; values above are clamped to 250.
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Telnyx::Models::DirRetrieveBpoAuthorizationsResponse]
+      #
+      # @see Telnyx::Models::DirRetrieveBpoAuthorizationsParams
+      def retrieve_bpo_authorizations(dir_id, params = {})
+        parsed, options = Telnyx::DirRetrieveBpoAuthorizationsParams.dump_request(params)
+        query = Telnyx::Internal::Util.encode_query_params(parsed)
+        @client.request(
+          method: :get,
+          path: ["dir/%1$s/bpo_authorizations", dir_id],
+          query: query.transform_keys(page_number: "page[number]", page_size: "page[size]"),
+          model: Telnyx::Models::DirRetrieveBpoAuthorizationsResponse,
+          options: options
+        )
+      end
+
       # Submit a DIR for vetting. Sends the DIR back through the vetting cycle from any
       # non-terminal status. When re-submitting from `suspended` or `expired`, the DIR's
       # previous Branded Calling registration is torn down transactionally and its phone
@@ -290,7 +383,7 @@ module Telnyx
       #
       # 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.
+      # `400` if the DIR has an unresolved infringement claim.
       #
       # @overload submit(dir_id, request_options: {})
       #
@@ -328,7 +421,7 @@ module Telnyx
       #
       # @param certify_ip_ownership [Boolean, Telnyx::Models::DirUpdateInfringementParams::CertifyIPOwnership] Must be `true`.
       #
-      # @param certify_no_infringement [Boolean, Telnyx::Models::DirUpdateInfringementParams::CertifyNoInfringement] Must be `true`.
+      # @param certify_no_infringement [Boolean, Telnyx::Models::DirUpdateInfringementParams::CertifyNoInfringement] Check to certify that the brand no longer infringes anyone else's trademark or i
       #
       # @param certify_no_shaft_content [Boolean, Telnyx::Models::DirUpdateInfringementParams::CertifyNoShaftContent] Must be `true`.
       #
@@ -336,7 +429,7 @@ module Telnyx
       #
       # @param call_reasons [Array<String>, nil]
       #
-      # @param display_name [String, nil]
+      # @param display_name [String, nil] The business name shown to call recipients, 1 to 35 characters, no emoji, not bl
       #
       # @param documents [Array<Telnyx::Models::Document>, nil] Append-only supporting documents to attach while resolving the claim (e.g. autho
       #

data/lib/telnyx/resources/email_blocks/imports.rb

@@ -16,9 +16,23 @@ module Telnyx
         # - 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`).
+        #
+        # Native Telnyx exports are detected by the stable first-12-column header
+        # signature (`id` … `group_id`) and are restored with their original `from`,
+        # `domain_id`, `group_id`, `source`, `status`, `expires_at`, plus
+        # `bounce_category`, `dsn_code`, and `meta` when present (`scope` is re-derived
+        # from `domain_id`/`from`; the exported `scope` cell must be a valid enum value).
+        # Lifecycle changes reconcile through the same create path as the API: a row
+        # already in the requested state restores its mutable backup fields without a new
+        # audit event, and a real transition (e.g. tombstone → active) appends the
+        # matching lifecycle event. `block_ttl_days` is not applied to native rows — their
+        # exported `expires_at` is preserved verbatim.
+        #
+        # Competitor and generic imports (SendGrid / Mailgun / SES / generic) remain
+        # account-scoped (`from`, `domain_id`, `group_id`, `scope` are not read) and
+        # `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`).
         #
         # @overload create(file:, block_ttl_days: nil, request_options: {})
         #

data/lib/telnyx/resources/email_blocks.rb

@@ -194,9 +194,11 @@ module Telnyx
       # stream `ORDER BY created_at ASC, id ASC` with no pagination.
       #
       # CSV columns:
-      # `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id`.
-      # The CSV carries the `group_id` column so group-scoped suppressions' group link
-      # survives the export (empty for account-scope rows).
+      # `id,to,from,reason,source,scope,status,domain_id, created_at,updated_at,expires_at,group_id,bounce_category,dsn_code, meta`
+      # (15 columns). The first 12 columns are the stable native signature;
+      # `bounce_category`, `dsn_code`, and `meta` are optional backup fields (empty when
+      # unset). The CSV carries the `group_id` column so group-scoped suppressions'
+      # group link survives the export (empty for account-scope rows).
       #
       # @overload retrieve_export(filter_created_after: nil, filter_created_before: nil, filter_domain_id: nil, filter_reason: nil, page_number: nil, page_size: nil, sort: nil, request_options: {})
       #

data/lib/telnyx/resources/email_domains.rb

@@ -221,6 +221,34 @@ module Telnyx
         )
       end
 
+      # Generates a new DKIM key for the domain, activates it, and retires the previous
+      # key. The response includes the updated DKIM DNS records the customer must
+      # publish. Selectors are fixed, so rotation replaces the TXT value at the existing
+      # `<selector>._domainkey.<domain>` host rather than adding a second record —
+      # `old_selector_retained` is false and the new TXT value must be published
+      # promptly, since signing switches to the new key immediately and the old TXT
+      # value will no longer match. The previous key is retired to a `retiring` state
+      # (retained, not revoked) so it can be revoked after the DNS propagation grace
+      # period.
+      #
+      # @overload rotate_dkim(domain_id, request_options: {})
+      #
+      # @param domain_id [String] Email domain UUID
+      #
+      # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Telnyx::Models::EmailDomainRotateDkimResponse]
+      #
+      # @see Telnyx::Models::EmailDomainRotateDkimParams
+      def rotate_dkim(domain_id, params = {})
+        @client.request(
+          method: :post,
+          path: ["email_domains/%1$s/rotate_dkim", domain_id],
+          model: Telnyx::Models::EmailDomainRotateDkimResponse,
+          options: params[:request_options]
+        )
+      end
+
       # Checks the published DNS records against the records required for the email
       # domain and returns the latest verification results.
       #

data/lib/telnyx/resources/email_events.rb

@@ -8,25 +8,38 @@ module Telnyx
       # {Telnyx::Models::EmailEventListParams} for more details.
       #
       # Lists account-level email events sorted oldest first by
-      # `occurred_at asc, id asc`.
-      #
-      # @overload list(email_id: nil, event_type: nil, from: nil, page_cursor: nil, page_size: nil, to: nil, request_options: {})
+      # `occurred_at asc, id asc`. Each row contains a legacy email.-prefixed event_type
+      # and an additive canonical_event_type. Gateway rejection renders email.failed
+      # with canonical email.gw_reject; ambiguous injection timeout renders
+      # email.injection_timeout in both; MTA expiration renders email.bounced with
+      # canonical email.expired. Message-scoped queued, sending, sandbox, cancelled, and
+      # daily_limit_exceeded rows fan out per durable recipient with stable derived IDs
+      # matching webhook delivery. Scheduled is the cardinality exception: account
+      # polling retains one message-scoped scheduled row with its stored event ID, while
+      # scheduled webhook publication fans out per recipient with derived IDs; reconcile
+      # scheduled events by message ID, event type, and occurrence time rather than
+      # event UUID. Recipient-scoped stored rows retain their stored UUIDs across
+      # polling and webhook delivery. Legacy names are derived from stored rows; an
+      # AdminBounce row stored as failed renders email.failed in polling while its
+      # webhook retains email.bounced, both with canonical email.failed.
+      #
+      # @overload list(email_id: nil, event_type: nil, from: nil, page_size: nil, page_cursor: nil, to: nil, request_options: {})
       #
       # @param email_id [String] Filter events for a specific email message UUID. Invalid UUID values are silentl
       #
-      # @param event_type [String, Array<String>] Comma-separated list of event types to include. Also accepts repeated query para
+      # @param event_type [String, Array<String>] Comma-separated list of event types to include. Also accepts repeated
       #
       # @param from [Time] Inclusive ISO 8601 start timestamp. Defaults to 30 days ago when omitted.
       #
-      # @param page_cursor [String] Opaque URL-safe Base64 cursor returned by a previous list response.
-      #
       # @param page_size [Integer] Number of results to return. Defaults to 25; maximum is 100. Invalid values are
       #
+      # @param page_cursor [String] Opaque URL-safe Base64 cursor returned by a previous event list response. The le
+      #
       # @param to [Time] Inclusive ISO 8601 end timestamp. When `from` is provided without `to`, defaults
       #
       # @param request_options [Telnyx::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Telnyx::Internal::EmailCursorPagination<Telnyx::Models::EmailEventListResponse>]
+      # @return [Telnyx::Models::EmailEventListResponse]
       #
       # @see Telnyx::Models::EmailEventListParams
       def list(params = {})
@@ -35,8 +48,7 @@ module Telnyx
         @client.request(
           method: :get,
           path: "email_events",
-          query: query,
-          page: Telnyx::Internal::EmailCursorPagination,
+          query: query.transform_keys(page_cursor: "page[cursor]"),
           model: Telnyx::Models::EmailEventListResponse,
           options: options
         )