sentdm 0.38.1 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16dc14ecd9c936e5dd3491d360224828550cd817ca6948685030bba5e446f4bf
-  data.tar.gz: '091a8f5517a1b38d376bea98bd8790c981a6803741943cf573c3fdbb0dd5b1c3'
+  metadata.gz: b0fe2b102d0383035abaeca878cfc21c6ca248654c43cd778b525ebc7c3f2ad5
+  data.tar.gz: f581f11fa8a55d391fcc1ee01958b359fec4562bc58702060db9c598d4d6f1a4
 SHA512:
-  metadata.gz: 4aa11719a1c01c114e7a34d1f0b1d925428fb74134d1ebb587dd4c9b6f401c7373b64bfc8aaf42cd2e1f3d6580063e3443fce61bfd01a427885b605df1f41191
-  data.tar.gz: bc846fa52387c5b28c16c7e17e7efb5a9e6c65fc3816baa6be2df535a98ab9ca6aeba04078e2821c5e51671b37021eb45dec501cfccb9cdd7ca0ebba2f4a3a32
+  metadata.gz: f337dcafa200de5fb45bc924339b2a0b07179a2bf531fee5535ac38ffcea924e35612892a4a9a9c96fc31ebbd2e398a630aa7ef41c67d67179b83c58fa456fc3
+  data.tar.gz: '0878a20b5965654dfcd33ef5a39d34e1631d9d7591b073bf2c75a3ac0a69c49f4868eb169f8fe5d75bce928111c9a0ee4af1f3e14fd2ec0dcc2d6bd7c728c4d5'

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [0.40.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.39.0...v0.40.0) (2026-10-28)
+
+
+### Features
+
+* **api:** add voice agents, the voice catalogue and agent_id ([abd31b9](https://github.com/sentdm/sent-dm-ruby/commit/abd31b96b520c10bd3ac67bb1c2b243c3a75b5fd))
+* **api:** sync generated SDKs from the committed spec ([30477ca](https://github.com/sentdm/sent-dm-ruby/commit/30477cacd760dccdf6ce8c5112267d75197746a6))
+* **api:** sync OpenAPI spec from production ([fa5b9f1](https://github.com/sentdm/sent-dm-ruby/commit/fa5b9f12f44e770a7aa6f2382585755fd9935acf))
+
+## [0.39.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.38.1...v0.39.0) (2026-10-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* **api:** move calls and voice tokens under the voice resource
+
+### Features
+
+* **api:** move calls and voice tokens under the voice resource ([a49f63f](https://github.com/sentdm/sent-dm-ruby/commit/a49f63f03c8ab24f342811916cf886f0bf8e85fa))
+* **api:** sync generated SDKs from the committed spec ([8201d6f](https://github.com/sentdm/sent-dm-ruby/commit/8201d6f1770931232a0ca73d1887a7e08df58ba0))
+
 ## [0.38.1](https://github.com/sentdm/sent-dm-ruby/compare/v0.38.0...v0.38.1) (2026-10-20)
 
 

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "sentdm", "~> 0.38.1"
+gem "sentdm", "~> 0.40.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/sentdm/client.rb

@@ -120,25 +120,8 @@ module Sentdm
     # @return [Sentdm::Resources::Conversations]
     attr_reader :conversations
 
-    # Phone calls from the numbers you hold, driven by your own callback URL.
-    #
-    # `POST /v3/channels/voice` enables a number for calls, with the callback URL Sent
-    # asks what to do with each call on it, and `POST /v3/channels/voice/tokens` mints
-    # a short-lived token that lets a user of your app place and receive calls as that
-    # number. When a call arrives or a caller presses a key, a signed question is
-    # POSTed to the callback URL and the answer decides the call;
-    # `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need
-    # before a real call reaches it, and
-    # `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret.
-    # The call events themselves (`call.completed` and the rest) arrive through your
-    # webhooks.
-    #
-    # Every call is a record under `/v3/calls`: read it, list its recordings once one
-    # is ready, hang it up, start or stop recording, and add, mute or remove
-    # conference participants while it is live. A leg to a phone number runs for at
-    # most what your balance affords at the destination's rate.
-    # @return [Sentdm::Resources::Calls]
-    attr_reader :calls
+    # @return [Sentdm::Resources::Voice]
+    attr_reader :voice
 
     # @return [Sentdm::Resources::Channels]
     attr_reader :channels
@@ -221,7 +204,7 @@ module Sentdm
       @messages = Sentdm::Resources::Messages.new(client: self)
       @contacts = Sentdm::Resources::Contacts.new(client: self)
       @conversations = Sentdm::Resources::Conversations.new(client: self)
-      @calls = Sentdm::Resources::Calls.new(client: self)
+      @voice = Sentdm::Resources::Voice.new(client: self)
       @channels = Sentdm::Resources::Channels.new(client: self)
       @me = Sentdm::Resources::Me.new(client: self)
     end

data/lib/sentdm/internal/voice_agents_page.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Internal
+    # @generic Elem
+    #
+    # @example
+    #   if voice_agents_page.has_next?
+    #     voice_agents_page = voice_agents_page.next_page
+    #   end
+    #
+    # @example
+    #   voice_agents_page.auto_paging_each do |agent|
+    #     puts(agent)
+    #   end
+    class VoiceAgentsPage
+      include Sentdm::Internal::Type::BasePage
+
+      # @return [Data]
+      attr_accessor :data
+
+      # @return [Boolean]
+      def next_page?
+        data&.pagination&.has_more
+      end
+
+      # @raise [Sentdm::HTTP::Error]
+      # @return [self]
+      def next_page
+        unless next_page?
+          message = "No more pages available. Please check #next_page? before calling ##{__method__}"
+          raise RuntimeError.new(message)
+        end
+
+        req = Sentdm::Internal::Util.deep_merge(
+          @req,
+          {query: {page: @req.fetch(:query).fetch(:page, 1).to_i.succ}}
+        )
+        @client.request(req)
+      end
+
+      # @param blk [Proc]
+      #
+      # @yieldparam [generic<Elem>]
+      def auto_paging_each(&blk)
+        unless block_given?
+          raise ArgumentError.new("A block must be given to ##{__method__}")
+        end
+
+        page = self
+        loop do
+          page.data&.agents&.each(&blk)
+
+          break unless page.next_page?
+          page = page.next_page
+        end
+      end
+
+      # @api private
+      #
+      # @param client [Sentdm::Internal::Transport::BaseClient]
+      # @param req [Hash{Symbol=>Object}]
+      # @param headers [Hash{String=>String}]
+      # @param page_data [Hash{Symbol=>Object}]
+      def initialize(client:, req:, headers:, page_data:)
+        super
+
+        case page_data
+        in {data: Hash | nil => data}
+          if (agents = data[:agents]).is_a?(Array)
+            data = {**data, agents: agents.map { Sentdm::Internal::Type::Converter.coerce(@model, _1) }}
+          end
+          @data = Sentdm::Internal::Type::Converter.coerce(Sentdm::Internal::VoiceAgentsPage::Data, data)
+        else
+        end
+      end
+
+      # @api private
+      #
+      # @return [String]
+      def inspect
+        model = Sentdm::Internal::Type::Converter.inspect(@model, depth: 1)
+
+        "#<#{self.class}[#{model}]:0x#{object_id.to_s(16)}>"
+      end
+
+      class Data < Sentdm::Internal::Type::BaseModel
+        # @!attribute agents
+        #
+        #   @return [Array<Object>, nil]
+        optional :agents, Sentdm::Internal::Type::ArrayOf[Sentdm::Internal::Type::Unknown]
+
+        # @!attribute pagination
+        #
+        #   @return [Data::Pagination, nil]
+        optional :pagination, -> { Data::Pagination }
+
+        # @!method initialize(agents: nil, pagination: nil)
+        #   @param agents [Array<Object>]
+        #   @param pagination [Data::Pagination]
+
+        # @see Data#pagination
+        class Pagination < Sentdm::Internal::Type::BaseModel
+          # @!attribute has_more
+          #
+          #   @return [Boolean, nil]
+          optional :has_more, Sentdm::Internal::Type::Boolean
+
+          # @!method initialize(has_more: nil)
+          #   @param has_more [Boolean]
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/models/call_event.rb

@@ -19,15 +19,17 @@ module Sentdm
       optional :field, String
 
       # @!attribute payload
-      #   Body of a call.initiated, call.answered, call.completed, call.failed or
-      #   call.recording_ready event. Which of them occurred is the envelope's event.
+      #   Body of a call.initiated, call.answered, call.agent_connected, call.completed,
+      #   call.failed or call.recording_ready event. Which of them occurred is the
+      #   envelope's event.
       #
       #   Shaped like the message, inbound, template and channel payloads: account_id
       #   names the account the event is about, channel names the channel, and updated_at
       #   is when the change happened on the call, in the same yyyy-MM-ddTHH:mm:ssZ form.
-      #   duration_seconds and price are added on call.completed, reason on call.failed
-      #   and recording_id on call.recording_ready; each is omitted rather than sent as
-      #   null when it does not apply.
+      #   Every event says how the call is handled in mode, and an agent call names its
+      #   agent in agent_id. duration_seconds and price are added on call.completed,
+      #   reason on call.failed and recording_id on call.recording_ready; each is omitted
+      #   rather than sent as null when it does not apply.
       #
       #   Casing is snake_case because these ride the same webhook stream customers
       #   already parse message_id from; the question/answer contract is a separate
@@ -62,7 +64,7 @@ module Sentdm
       #
       #   @param field [String] The event family, for example message, templates or contact. Route on
       #
-      #   @param payload [Sentdm::Models::CallEventPayload, nil] Body of a call.initiated, call.answered, call.completed, call.failed
+      #   @param payload [Sentdm::Models::CallEventPayload, nil] Body of a call.initiated, call.answered, call.agent_connected, call.completed,
       #
       #   @param request_id [String, nil] The event-specific body.
       #

data/lib/sentdm/models/call_event_payload.rb

@@ -16,6 +16,12 @@ module Sentdm
       #   @return [String, nil]
       optional :account_id, String
 
+      # @!attribute agent_id
+      #   The voice agent that answers the call, agent\_…. Only on an agent call.
+      #
+      #   @return [String, nil]
+      optional :agent_id, String, nil?: true
+
       # @!attribute channel
       #   Always voice.
       #
@@ -28,6 +34,13 @@ module Sentdm
       #   @return [Integer, nil]
       optional :duration_seconds, Integer, nil?: true
 
+      # @!attribute mode
+      #   inapp, a call routed by the number's callback URL, or agent, a call one of the
+      #   account's voice agents answers. The same value GET /v3/voice/calls returns.
+      #
+      #   @return [String, nil]
+      optional :mode, String
+
       # @!attribute number
       #   The customer number that owns the call, in E.164 format.
       #
@@ -49,8 +62,9 @@ module Sentdm
       optional :reason, String, nil?: true
 
       # @!attribute recording_id
-      #   The recording that became available, the same id GET /v3/calls/{id}/recordings
-      #   lists it under. Only on call.recording_ready, which is sent once per recording.
+      #   The recording that became available, the same id GET
+      #   /v3/voice/calls/{id}/recordings lists it under. Only on call.recording_ready,
+      #   which is sent once per recording.
       #
       #   @return [String, nil]
       optional :recording_id, String, nil?: true
@@ -61,19 +75,21 @@ module Sentdm
       #   @return [String, nil]
       optional :updated_at, String
 
-      # @!method initialize(call_id:, account_id: nil, channel: nil, duration_seconds: nil, number: nil, price: nil, reason: nil, recording_id: nil, updated_at: nil)
+      # @!method initialize(call_id:, account_id: nil, agent_id: nil, channel: nil, duration_seconds: nil, mode: nil, number: nil, price: nil, reason: nil, recording_id: nil, updated_at: nil)
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::CallEventPayload} for more details.
       #
-      #   Body of a call.initiated, call.answered, call.completed, call.failed or
-      #   call.recording_ready event. Which of them occurred is the envelope's event.
+      #   Body of a call.initiated, call.answered, call.agent_connected, call.completed,
+      #   call.failed or call.recording_ready event. Which of them occurred is the
+      #   envelope's event.
       #
       #   Shaped like the message, inbound, template and channel payloads: account_id
       #   names the account the event is about, channel names the channel, and updated_at
       #   is when the change happened on the call, in the same yyyy-MM-ddTHH:mm:ssZ form.
-      #   duration_seconds and price are added on call.completed, reason on call.failed
-      #   and recording_id on call.recording_ready; each is omitted rather than sent as
-      #   null when it does not apply.
+      #   Every event says how the call is handled in mode, and an agent call names its
+      #   agent in agent_id. duration_seconds and price are added on call.completed,
+      #   reason on call.failed and recording_id on call.recording_ready; each is omitted
+      #   rather than sent as null when it does not apply.
       #
       #   Casing is snake_case because these ride the same webhook stream customers
       #   already parse message_id from; the question/answer contract is a separate
@@ -84,17 +100,21 @@ module Sentdm
       #
       #   @param account_id [String] The account the call belongs to: the key's own customer, or the sender profile i
       #
+      #   @param agent_id [String, nil] The voice agent that answers the call, agent\_…. Only on an agent call.
+      #
       #   @param channel [String] Always voice.
       #
       #   @param duration_seconds [Integer, nil] How long the call lasted. Only on call.completed.
       #
+      #   @param mode [String] inapp, a call routed by the number's callback URL, or agent, a call one of the a
+      #
       #   @param number [String] The customer number that owns the call, in E.164 format.
       #
       #   @param price [Float, nil] What the call was charged. Only on call.completed, and omitted there until billi
       #
       #   @param reason [String, nil] The machine-readable reason the call did not complete. Only on call.failed, and
       #
-      #   @param recording_id [String, nil] The recording that became available, the same id GET /v3/calls/{id}/recordings l
+      #   @param recording_id [String, nil] The recording that became available, the same id GET /v3/voice/calls/{id}/record
       #
       #   @param updated_at [String] When the change happened on the call, as opposed to when the event was emitted.
     end

data/lib/sentdm/models/channels/voice_create_params.rb

@@ -8,16 +8,15 @@ module Sentdm
         extend Sentdm::Internal::Type::RequestParameters::Converter
         include Sentdm::Internal::Type::RequestParameters
 
-        # @!attribute callback_url
-        #   Where Sent asks what to do with each call on this number: an absolute HTTP or
-        #   HTTPS URL on a public host. A signed question is POSTed here when a call arrives
-        #   or a caller presses a key, and the answer decides the call. Every question is
-        #   signed with the callback_secret the response returns, the same way your webhooks
-        #   are signed. Turning the number on again with a different URL replaces it and
-        #   keeps the secret.
+        # @!attribute agent_id
+        #   One of your voice agents (GET /v3/voice/agents), such as
+        #   agent_9f2ab000-0000-4000-8000-000000000001, to answer calls to this number. It
+        #   wins over callback_url for calls to the number, and both may be sent; calls your
+        #   app places from the number still follow your app. Send it instead of
+        #   callback_url for a number only an agent answers.
         #
-        #   @return [String]
-        required :callback_url, String
+        #   @return [String, nil]
+        optional :agent_id, String, nil?: true
 
         # @!attribute area_code
         #   The US area code a new number should be in, as 212. Only for a request that
@@ -28,6 +27,17 @@ module Sentdm
         #   @return [String, nil]
         optional :area_code, String, nil?: true
 
+        # @!attribute callback_url
+        #   Where Sent asks what to do with each call on this number: an absolute HTTP or
+        #   HTTPS URL on a public host. A signed question is POSTed here when a call arrives
+        #   or a caller presses a key, and the answer decides the call. Every question is
+        #   signed with the callback_secret the response returns, the same way your webhooks
+        #   are signed. Turning the number on again with a different URL replaces it and
+        #   keeps the secret. Required unless agent_id is sent.
+        #
+        #   @return [String, nil]
+        optional :callback_url, String, nil?: true
+
         # @!attribute default_for_app_calls
         #   Make this the line app-originated calls are placed from when a voice token names
         #   no number. Omit it and your first voice number takes that role; a later one
@@ -61,14 +71,16 @@ module Sentdm
         #   @return [String, nil]
         optional :x_profile_id, String
 
-        # @!method initialize(callback_url:, area_code: nil, default_for_app_calls: nil, number: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        # @!method initialize(agent_id: nil, area_code: nil, callback_url: nil, default_for_app_calls: nil, number: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
         #   Some parameter documentations has been truncated, see
         #   {Sentdm::Models::Channels::VoiceCreateParams} for more details.
         #
-        #   @param callback_url [String] Where Sent asks what to do with each call on this number: an absolute HTTP or HT
+        #   @param agent_id [String, nil] One of your voice agents (GET /v3/voice/agents), such as
         #
         #   @param area_code [String, nil] The US area code a new number should be in, as 212. Only for a request that leav
         #
+        #   @param callback_url [String, nil] Where Sent asks what to do with each call on this number: an absolute HTTP or HT
+        #
         #   @param default_for_app_calls [Boolean, nil] Make this the line app-originated calls are placed from when a voice token names
         #
         #   @param number [String, nil] One of your phone numbers, in E.164 format. Leave the field out entirely to be g

data/lib/sentdm/models/channels/voice_number.rb

@@ -4,6 +4,15 @@ module Sentdm
   module Models
     module Channels
       class VoiceNumber < Sentdm::Internal::Type::BaseModel
+        # @!attribute agent_id
+        #   The voice agent calls to this number go to, such as
+        #   agent_9f2ab000-0000-4000-8000-000000000001. It wins over callback_url for calls
+        #   to the number; calls your app places from the number still follow your app. Null
+        #   when no agent answers the number.
+        #
+        #   @return [String, nil]
+        optional :agent_id, String, nil?: true
+
         # @!attribute callback_url
         #   Where Sent asks what to do with each call on this number: a signed question is
         #   POSTed here when a call arrives or a caller presses a key, and the answer
@@ -32,6 +41,15 @@ module Sentdm
         #   @return [String, nil]
         optional :number, String
 
+        # @!attribute routes_to
+        #   Who answers calls to this number: agent, the voice agent in agent_id;
+        #   agent_pending, that agent once the number has finished moving to it, with calls
+        #   possibly unanswered until then; callback, your callback_url; or none, in which
+        #   case calls to it are declined.
+        #
+        #   @return [String, nil]
+        optional :routes_to, String
+
         # @!attribute status
         #   ACTIVE while the number carries calls, INACTIVE once it was turned off. Nothing
         #   provisions: a number the customer holds can carry calls the moment voice is
@@ -45,12 +63,14 @@ module Sentdm
         #   @return [Time, nil]
         optional :updated_at, Time
 
-        # @!method initialize(callback_url: nil, created_at: nil, default_for_app_calls: nil, number: nil, status: nil, updated_at: nil)
+        # @!method initialize(agent_id: nil, callback_url: nil, created_at: nil, default_for_app_calls: nil, number: nil, routes_to: nil, status: nil, updated_at: nil)
         #   Some parameter documentations has been truncated, see
         #   {Sentdm::Models::Channels::VoiceNumber} for more details.
         #
         #   One number the profile carries phone calls on.
         #
+        #   @param agent_id [String, nil] The voice agent calls to this number go to, such as agent_9f2ab000-0000-4000-800
+        #
         #   @param callback_url [String, nil] Where Sent asks what to do with each call on this number: a signed question is P
         #
         #   @param created_at [Time]
@@ -59,6 +79,8 @@ module Sentdm
         #
         #   @param number [String] The number, in E.164.
         #
+        #   @param routes_to [String] Who answers calls to this number: agent, the voice agent in agent_id;
+        #
         #   @param status [String] ACTIVE while the number carries calls, INACTIVE once it was turned off. Nothing
         #
         #   @param updated_at [Time]

data/lib/sentdm/models/channels/voice_update_params.rb

@@ -13,6 +13,15 @@ module Sentdm
         #   @return [String]
         required :number, String
 
+        # @!attribute agent_id
+        #   One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to
+        #   answer calls to the number, or null to unbind it so the callback URL answers
+        #   them again. The agent wins over callback_url for calls to the number; calls your
+        #   app places from it still follow your app.
+        #
+        #   @return [String, nil]
+        optional :agent_id, String, nil?: true
+
         # @!attribute callback_url
         #   A new callback URL for the number, active or not: an absolute HTTP or HTTPS URL
         #   on a public host, where Sent asks what to do with each call. The signing secret
@@ -54,12 +63,14 @@ module Sentdm
         #   @return [String, nil]
         optional :x_profile_id, String
 
-        # @!method initialize(number:, callback_url: nil, default_for_app_calls: nil, sandbox: nil, status: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        # @!method initialize(number:, agent_id: nil, callback_url: nil, default_for_app_calls: nil, sandbox: nil, status: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
         #   Some parameter documentations has been truncated, see
         #   {Sentdm::Models::Channels::VoiceUpdateParams} for more details.
         #
         #   @param number [String]
         #
+        #   @param agent_id [String, nil] One of your voice agents, such as agent_9f2ab000-0000-4000-8000-000000000001, to
+        #
         #   @param callback_url [String, nil] A new callback URL for the number, active or not: an absolute HTTP or HTTPS URL
         #
         #   @param default_for_app_calls [Boolean, nil] true makes this the line app-originated calls are placed from when a voice token

data/lib/sentdm/models/message_send_params.rb

@@ -30,6 +30,11 @@ module Sentdm
       #   itself is unchanged: the same rules are scored and ranked the same way, with
       #   routes pinned to numbers you did not list removed from the running.
       #
+      #   Each channel's list is independent: an sms list does not restrict MMS. To choose
+      #   the numbers a message may go out from as MMS, name them under mms. MMS sends
+      #   from your SMS numbers, so an mms list may name any of your active SMS numbers
+      #   whose market carries MMS — the ones listed under mms in your channels.
+      #
       #   Every number must be an active sender on your account. The request itself is
       #   still accepted (202) if one is not — like every other send-time rule, that is
       #   decided per message, so each affected message is recorded BLOCKED with error
@@ -52,7 +57,9 @@ module Sentdm
       #
       #   Their presence is also what makes a message eligible for MMS on an auto-detect
       #   send: a message with nothing attached is delivered as SMS, because an MMS with
-      #   no media is a more expensive text message.
+      #   no media is a more expensive text message. For the same reason a send that names
+      #   mms in channel with nothing attached, here or on the template, is refused with
+      #   a 400.
       #
       #   The recipient's carrier fetches each URL after the send is accepted, so it must
       #   stay publicly reachable — a link that expires, or one behind auth, arrives as a

data/lib/sentdm/models/template.rb

@@ -42,17 +42,18 @@ module Sentdm
 
       # @!attribute channels
       #   The channels this template's definition can render on, in canonical order: sms,
-      #   whatsapp, rcs.
+      #   whatsapp, rcs, mms.
       #
       #   Derived from the definition's body, mirroring each channel's send-time fallback
       #   chain, so a channel is listed only when a real body would be produced for it:
       #   SMS reads sms ?? multiChannel, WhatsApp reads whatsapp ?? multiChannel, and RCS
-      #   reads rcs ?? multiChannel ?? sms. A multiChannel body therefore reports all
-      #   three, and the extra SMS fallback on RCS is why an sms/whatsapp pair reports RCS
-      #   too.
+      #   and MMS read rcs ?? multiChannel ?? sms and mms ?? multiChannel ?? sms. A
+      #   multiChannel body therefore reports all four, and the extra SMS fallback is why
+      #   an sms/whatsapp pair reports RCS and MMS too.
       #
       #   This says what the content can render on, not what may be sent: sending also
-      #   needs the template approved for that channel.
+      #   needs the template approved for that channel, and MMS needs an attachment, from
+      #   media_urls or the template's mms body.
       #
       #   @return [Array<String>, nil]
       optional :channels, Sentdm::Internal::Type::ArrayOf[String], nil?: true

data/lib/sentdm/models/template_body.rb

@@ -7,10 +7,10 @@ module Sentdm
       #   MMS-specific content — subject, text and attachments.
       #
       #   Like Rcs, an override that cannot stand on its own: a template still needs a
-      #   MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
-      #   Rcs, it has no fallback at send time — MMS with no media is a more expensive
-      #   SMS, so a template without this slot is deliberately not MMS-capable and never
-      #   produces an MMS route candidate.
+      #   MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Without
+      #   this slot MMS renders the shared or SMS body, so it is only needed for
+      #   MMS-specific copy, a subject or attachments. When present it replaces that body
+      #   on MMS rather than adding to it.
       #
       #   @return [Sentdm::Models::TemplateBody::Mms, nil]
       optional :mms, -> { Sentdm::TemplateBody::Mms }, nil?: true
@@ -94,10 +94,10 @@ module Sentdm
         #   MMS-specific content — subject, text and attachments.
         #
         #   Like Rcs, an override that cannot stand on its own: a template still needs a
-        #   MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
-        #   Rcs, it has no fallback at send time — MMS with no media is a more expensive
-        #   SMS, so a template without this slot is deliberately not MMS-capable and never
-        #   produces an MMS route candidate.
+        #   MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Without
+        #   this slot MMS renders the shared or SMS body, so it is only needed for
+        #   MMS-specific copy, a subject or attachments. When present it replaces that body
+        #   on MMS rather than adding to it.
         #
         #   @param media [Array<Sentdm::Models::TemplateBody::Mms::Media>, nil] Attachments carried by every send on this template, in order. A per-send media_u
         #