sentdm 0.32.0 → 0.34.0

data/rbi/sentdm/models/message_retrieve_status_response.rbi

@@ -11,7 +11,12 @@ module Sentdm
           )
         end
 
-      # Message response for v3 API — same shape as v2 with snake_case JSON conventions
+      # Message response for v3 API — same shape as v2 with snake_case JSON conventions.
+      #
+      # The shape of a message that was sent immediately: it never has a scheduled_at
+      # key. A message that is or was held for a later instant is a
+      # ScheduledMessageResponse, and the endpoint decides which of the two to answer
+      # with. From always returns this type.
       sig do
         returns(T.nilable(Sentdm::Models::MessageRetrieveStatusResponse::Data))
       end
@@ -61,7 +66,12 @@ module Sentdm
         ).returns(T.attached_class)
       end
       def self.new(
-        # Message response for v3 API — same shape as v2 with snake_case JSON conventions
+        # Message response for v3 API — same shape as v2 with snake_case JSON conventions.
+        #
+        # The shape of a message that was sent immediately: it never has a scheduled_at
+        # key. A message that is or was held for a later instant is a
+        # ScheduledMessageResponse, and the endpoint decides which of the two to answer
+        # with. From always returns this type.
         data: nil,
         # Error information
         error: nil,
@@ -146,7 +156,14 @@ module Sentdm
         attr_accessor :events
 
         # Structured message body format for database storage. Preserves channel-specific
-        # components (header, body, footer, buttons).
+        # components (header, header media, body, footer, buttons, MMS subject and media).
+        #
+        # Persisted as the messageBody jsonb column on Messages. Every write path goes
+        # through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+        # shape is stable regardless of channel or status. Anything that rebuilds this
+        # object field by field — the four IMessageBodyStrategy implementations and
+        # MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+        # silently dropped on whichever path forgot it.
         sig do
           returns(
             T.nilable(
@@ -181,6 +198,20 @@ module Sentdm
         sig { returns(T.nilable(Float)) }
         attr_accessor :price
 
+        # A human-readable sentence for reason_code, for example "Insufficient balance".
+        # Omitted whenever reason_code is.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :reason
+
+        # Why the message is at its current status, as a stable platform code such as
+        # DELIVERY_007, BUSINESS_003 or DELIVERY_003. Present when the current status is
+        # FAILED, FILTERED or BLOCKED and the lifecycle was loaded; omitted otherwise.
+        # Switch on this rather than on reason: the code is stable, the wording may be
+        # improved. It is the platform's classification of the outcome, never a carrier or
+        # vendor code.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :reason_code
+
         sig { returns(T.nilable(String)) }
         attr_reader :region_code
 
@@ -202,7 +233,12 @@ module Sentdm
         sig { returns(T.nilable(String)) }
         attr_accessor :template_name
 
-        # Message response for v3 API — same shape as v2 with snake_case JSON conventions
+        # Message response for v3 API — same shape as v2 with snake_case JSON conventions.
+        #
+        # The shape of a message that was sent immediately: it never has a scheduled_at
+        # key. A message that is or was held for a later instant is a
+        # ScheduledMessageResponse, and the endpoint decides which of the two to answer
+        # with. From always returns this type.
         sig do
           params(
             id: String,
@@ -225,6 +261,8 @@ module Sentdm
             phone: String,
             phone_international: String,
             price: T.nilable(Float),
+            reason: T.nilable(String),
+            reason_code: T.nilable(String),
             region_code: String,
             status: String,
             template_category: T.nilable(String),
@@ -242,11 +280,28 @@ module Sentdm
           direction: nil,
           events: nil,
           # Structured message body format for database storage. Preserves channel-specific
-          # components (header, body, footer, buttons).
+          # components (header, header media, body, footer, buttons, MMS subject and media).
+          #
+          # Persisted as the messageBody jsonb column on Messages. Every write path goes
+          # through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+          # shape is stable regardless of channel or status. Anything that rebuilds this
+          # object field by field — the four IMessageBodyStrategy implementations and
+          # MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+          # silently dropped on whichever path forgot it.
           message_body: nil,
           phone: nil,
           phone_international: nil,
           price: nil,
+          # A human-readable sentence for reason_code, for example "Insufficient balance".
+          # Omitted whenever reason_code is.
+          reason: nil,
+          # Why the message is at its current status, as a stable platform code such as
+          # DELIVERY_007, BUSINESS_003 or DELIVERY_003. Present when the current status is
+          # FAILED, FILTERED or BLOCKED and the lifecycle was loaded; omitted otherwise.
+          # Switch on this rather than on reason: the code is stable, the wording may be
+          # improved. It is the platform's classification of the outcome, never a carrier or
+          # vendor code.
+          reason_code: nil,
           region_code: nil,
           status: nil,
           template_category: nil,
@@ -278,6 +333,8 @@ module Sentdm
               phone: String,
               phone_international: String,
               price: T.nilable(Float),
+              reason: T.nilable(String),
+              reason_code: T.nilable(String),
               region_code: String,
               status: String,
               template_category: T.nilable(String),
@@ -307,15 +364,39 @@ module Sentdm
           sig { returns(T.nilable(String)) }
           attr_accessor :description
 
+          # A human-readable sentence for reason_code. Omitted whenever reason_code is.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :reason
+
+          # Why the message reached this status, as a stable platform code such as
+          # DELIVERY_007. Present on FAILED, FILTERED and BLOCKED events; omitted on every
+          # status that needs no explanation. Same wire name and vocabulary as on the
+          # activities list and the webhook.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :reason_code
+
           # Represents a status change event in a message's lifecycle (v3)
           sig do
             params(
               status: String,
               timestamp: Time,
-              description: T.nilable(String)
+              description: T.nilable(String),
+              reason: T.nilable(String),
+              reason_code: T.nilable(String)
             ).returns(T.attached_class)
           end
-          def self.new(status:, timestamp:, description: nil)
+          def self.new(
+            status:,
+            timestamp:,
+            description: nil,
+            # A human-readable sentence for reason_code. Omitted whenever reason_code is.
+            reason: nil,
+            # Why the message reached this status, as a stable platform code such as
+            # DELIVERY_007. Present on FAILED, FILTERED and BLOCKED events; omitted on every
+            # status that needs no explanation. Same wire name and vocabulary as on the
+            # activities list and the webhook.
+            reason_code: nil
+          )
           end
 
           sig do
@@ -323,7 +404,9 @@ module Sentdm
               {
                 status: String,
                 timestamp: Time,
-                description: T.nilable(String)
+                description: T.nilable(String),
+                reason: T.nilable(String),
+                reason_code: T.nilable(String)
               }
             )
           end
@@ -363,8 +446,57 @@ module Sentdm
           sig { returns(T.nilable(String)) }
           attr_accessor :header
 
+          # The media asset that rode a message's header, recorded as sent.
+          sig do
+            returns(
+              T.nilable(
+                Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia
+              )
+            )
+          end
+          attr_reader :header_media
+
+          sig do
+            params(
+              header_media:
+                T.nilable(
+                  Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia::OrHash
+                )
+            ).void
+          end
+          attr_writer :header_media
+
+          # MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on
+          # every other channel.
+          #
+          # Persisted rather than derived because a resend and a curfew release rebuild the
+          # send from the stored row — MessageReplayCommandBuilder reads templateId and
+          # templateVariables and nothing else — so media that lives only on the original
+          # request would silently turn a replayed MMS into a text message.
+          sig do
+            returns(
+              T.nilable(
+                T::Array[
+                  Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media
+                ]
+              )
+            )
+          end
+          attr_accessor :media
+
+          # MMS subject line. Null on every other channel.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :subject
+
           # Structured message body format for database storage. Preserves channel-specific
-          # components (header, body, footer, buttons).
+          # components (header, header media, body, footer, buttons, MMS subject and media).
+          #
+          # Persisted as the messageBody jsonb column on Messages. Every write path goes
+          # through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+          # shape is stable regardless of channel or status. Anything that rebuilds this
+          # object field by field — the four IMessageBodyStrategy implementations and
+          # MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+          # silently dropped on whichever path forgot it.
           sig do
             params(
               buttons:
@@ -375,10 +507,38 @@ module Sentdm
                 ),
               content: String,
               footer: T.nilable(String),
-              header: T.nilable(String)
+              header: T.nilable(String),
+              header_media:
+                T.nilable(
+                  Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia::OrHash
+                ),
+              media:
+                T.nilable(
+                  T::Array[
+                    Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media::OrHash
+                  ]
+                ),
+              subject: T.nilable(String)
             ).returns(T.attached_class)
           end
-          def self.new(buttons: nil, content: nil, footer: nil, header: nil)
+          def self.new(
+            buttons: nil,
+            content: nil,
+            footer: nil,
+            header: nil,
+            # The media asset that rode a message's header, recorded as sent.
+            header_media: nil,
+            # MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on
+            # every other channel.
+            #
+            # Persisted rather than derived because a resend and a curfew release rebuild the
+            # send from the stored row — MessageReplayCommandBuilder reads templateId and
+            # templateVariables and nothing else — so media that lives only on the original
+            # request would silently turn a replayed MMS into a text message.
+            media: nil,
+            # MMS subject line. Null on every other channel.
+            subject: nil
+          )
           end
 
           sig do
@@ -392,7 +552,18 @@ module Sentdm
                   ),
                 content: String,
                 footer: T.nilable(String),
-                header: T.nilable(String)
+                header: T.nilable(String),
+                header_media:
+                  T.nilable(
+                    Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia
+                  ),
+                media:
+                  T.nilable(
+                    T::Array[
+                      Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media
+                    ]
+                  ),
+                subject: T.nilable(String)
               }
             )
           end
@@ -450,6 +621,143 @@ module Sentdm
             def to_hash
             end
           end
+
+          class HeaderMedia < Sentdm::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia,
+                  Sentdm::Internal::AnyHash
+                )
+              end
+
+            # "image", "video" or "document" — taken from the header's media variable.
+            sig { returns(T.nilable(String)) }
+            attr_reader :type
+
+            sig { params(type: String).void }
+            attr_writer :type
+
+            # The https URL the caller supplied for this send. Never the template's stored
+            # props.sample, which is Meta's expiring header_handle rather than what was
+            # delivered.
+            sig { returns(T.nilable(String)) }
+            attr_reader :url
+
+            sig { params(url: String).void }
+            attr_writer :url
+
+            # The media asset that rode a message's header, recorded as sent.
+            sig { params(type: String, url: String).returns(T.attached_class) }
+            def self.new(
+              # "image", "video" or "document" — taken from the header's media variable.
+              type: nil,
+              # The https URL the caller supplied for this send. Never the template's stored
+              # props.sample, which is Meta's expiring header_handle rather than what was
+              # delivered.
+              url: nil
+            )
+            end
+
+            sig { override.returns({ type: String, url: String }) }
+            def to_hash
+            end
+          end
+
+          class Media < Sentdm::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media,
+                  Sentdm::Internal::AnyHash
+                )
+              end
+
+            # One of MmsMediaTypes when the content type is known. Advisory — a reader should
+            # trust the fetched object's own Content-Type.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :media_type
+
+            # Content type as the provider declared it. Null when it declared none.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :mime_type
+
+            # Size as the provider declared it. Never measured here — nothing downloads the
+            # file.
+            sig { returns(T.nilable(Integer)) }
+            attr_accessor :size_bytes
+
+            # Inbound only: the SHA-256 the provider declared alongside the attachment, when
+            # it declared one. Relayed to the customer so they can verify what they fetch
+            # matches what the carrier said it sent. It is the only integrity signal available
+            # on an attachment nobody here has read.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :source_hash_sha256
+
+            # Where the file lives. Outbound: the URL the customer gave us and the carrier
+            # fetched. Inbound: the URL the carrier hosts it at, relayed unchanged.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :url
+
+            # One attachment on a message, in either direction — and in both, a URL somebody
+            # else hosts.
+            #
+            # Outbound: the customer supplied a public URL and we handed it to the carrier.
+            # Inbound: the carrier hosts the file and we record where. sent.dm never holds the
+            # bytes, so there is no key, no expiry bookkeeping and nothing minted per read —
+            # what is stored is what is served.
+            #
+            # An inbound link expires on the carrier's own schedule and is unauthenticated.
+            # That is the customer's to manage, and it is documented where they will see it
+            # rather than only here — a recipient who needs an attachment to outlive that
+            # window copies it on receipt.
+            #
+            # Storing a presigned URL is the specific mistake this shape still avoids:
+            # M260826130000 and M260826140000 exist because RCS assets were stored as signed
+            # URLs and went stale. Nothing here is signed.
+            sig do
+              params(
+                media_type: T.nilable(String),
+                mime_type: T.nilable(String),
+                size_bytes: T.nilable(Integer),
+                source_hash_sha256: T.nilable(String),
+                url: T.nilable(String)
+              ).returns(T.attached_class)
+            end
+            def self.new(
+              # One of MmsMediaTypes when the content type is known. Advisory — a reader should
+              # trust the fetched object's own Content-Type.
+              media_type: nil,
+              # Content type as the provider declared it. Null when it declared none.
+              mime_type: nil,
+              # Size as the provider declared it. Never measured here — nothing downloads the
+              # file.
+              size_bytes: nil,
+              # Inbound only: the SHA-256 the provider declared alongside the attachment, when
+              # it declared one. Relayed to the customer so they can verify what they fetch
+              # matches what the carrier said it sent. It is the only integrity signal available
+              # on an attachment nobody here has read.
+              source_hash_sha256: nil,
+              # Where the file lives. Outbound: the URL the customer gave us and the carrier
+              # fetched. Inbound: the URL the carrier hosts it at, relayed unchanged.
+              url: nil
+            )
+            end
+
+            sig do
+              override.returns(
+                {
+                  media_type: T.nilable(String),
+                  mime_type: T.nilable(String),
+                  size_bytes: T.nilable(Integer),
+                  source_hash_sha256: T.nilable(String),
+                  url: T.nilable(String)
+                }
+              )
+            end
+            def to_hash
+            end
+          end
         end
       end
     end

data/rbi/sentdm/models/message_send_params.rbi

@@ -17,6 +17,23 @@ module Sentdm
       sig { returns(T.nilable(T::Array[String])) }
       attr_accessor :channel
 
+      # Attachments for this send, as publicly fetchable https URLs. Used by the MMS
+      # channel and ignored by every other one.
+      #
+      # Supplying these replaces the media on the template's mms body rather than adding
+      # to it, so a template can hold a default creative while a caller still sends
+      # something recipient-specific.
+      #
+      # 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.
+      #
+      # 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
+      # failed message.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_accessor :media_urls
+
       # Sandbox flag - when true, the operation is simulated without side effects Useful
       # for testing integrations without actual execution
       sig { returns(T.nilable(T::Boolean)) }
@@ -25,6 +42,25 @@ module Sentdm
       sig { params(sandbox: T::Boolean).void }
       attr_writer :sandbox
 
+      # Optional future send time as an ISO-8601 timestamp with an explicit UTC offset,
+      # e.g. 2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A value without an
+      # offset is rejected (400) rather than read in the server's zone. The offset only
+      # fixes the instant: it is stored and echoed in UTC as scheduled_at. Omit to send
+      # now. Must be at least one minute ahead and at most 30 days ahead. Accepted
+      # messages report SCHEDULED and are released for delivery at this time. Quiet
+      # hours, balance and template approval are evaluated at release, not at
+      # acceptance: a message whose time falls inside a recipient's protected
+      # quiet-hours window is moved to the next allowed time and a second
+      # message.scheduled webhook reports the new scheduled_at.
+      sig { returns(T.nilable(Time)) }
+      attr_accessor :scheduled_at
+
+      # Subject line for this send, overriding the template's. MMS only; ignored on
+      # every other channel. Most handsets render it above the body, some ignore it
+      # entirely.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :subject
+
       # SDK-style template reference: resolve by ID or by name, with optional
       # parameters.
       sig { returns(T.nilable(Sentdm::MessageSendParams::Template)) }
@@ -63,7 +99,10 @@ module Sentdm
       sig do
         params(
           channel: T.nilable(T::Array[String]),
+          media_urls: T.nilable(T::Array[String]),
           sandbox: T::Boolean,
+          scheduled_at: T.nilable(Time),
+          subject: T.nilable(String),
           template: T.nilable(Sentdm::MessageSendParams::Template::OrHash),
           text: T.nilable(String),
           to: T::Array[String],
@@ -77,9 +116,39 @@ module Sentdm
         # separate message per recipient. "sent" = auto-detect. Defaults to ["sent"]
         # (auto-detect) if omitted.
         channel: nil,
+        # Attachments for this send, as publicly fetchable https URLs. Used by the MMS
+        # channel and ignored by every other one.
+        #
+        # Supplying these replaces the media on the template's mms body rather than adding
+        # to it, so a template can hold a default creative while a caller still sends
+        # something recipient-specific.
+        #
+        # 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.
+        #
+        # 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
+        # failed message.
+        media_urls: nil,
         # Sandbox flag - when true, the operation is simulated without side effects Useful
         # for testing integrations without actual execution
         sandbox: nil,
+        # Optional future send time as an ISO-8601 timestamp with an explicit UTC offset,
+        # e.g. 2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A value without an
+        # offset is rejected (400) rather than read in the server's zone. The offset only
+        # fixes the instant: it is stored and echoed in UTC as scheduled_at. Omit to send
+        # now. Must be at least one minute ahead and at most 30 days ahead. Accepted
+        # messages report SCHEDULED and are released for delivery at this time. Quiet
+        # hours, balance and template approval are evaluated at release, not at
+        # acceptance: a message whose time falls inside a recipient's protected
+        # quiet-hours window is moved to the next allowed time and a second
+        # message.scheduled webhook reports the new scheduled_at.
+        scheduled_at: nil,
+        # Subject line for this send, overriding the template's. MMS only; ignored on
+        # every other channel. Most handsets render it above the body, some ignore it
+        # entirely.
+        subject: nil,
         # SDK-style template reference: resolve by ID or by name, with optional
         # parameters.
         template: nil,
@@ -97,7 +166,10 @@ module Sentdm
         override.returns(
           {
             channel: T.nilable(T::Array[String]),
+            media_urls: T.nilable(T::Array[String]),
             sandbox: T::Boolean,
+            scheduled_at: T.nilable(Time),
+            subject: T.nilable(String),
             template: T.nilable(Sentdm::MessageSendParams::Template),
             text: T.nilable(String),
             to: T::Array[String],
@@ -127,7 +199,20 @@ module Sentdm
         sig { returns(T.nilable(String)) }
         attr_accessor :name
 
-        # Template variable parameters for personalization
+        # Template variable parameters for personalization, keyed by variable name.
+        #
+        # Every variable the template declares is required; GET /v3/templates/{id} lists
+        # them. Supplying a key the template does not declare is ignored.
+        #
+        # Media headers. A template whose header is an image (designed in WhatsApp Manager
+        # and imported into Sent) declares a reserved header_image key. Its value is a
+        # publicly reachable https URL that Meta fetches at send time — Sent does not host
+        # the asset, and the sample approved with the template is not reused. The key is
+        # derived from the header's media type, so header_video and header_document follow
+        # the same shape when those formats ship.
+        #
+        # "parameters": { "header_image": "https://cdn.example.com/banner.jpg", "name":
+        # "John Doe" }
         sig { returns(T.nilable(T::Hash[Symbol, String])) }
         attr_accessor :parameters
 
@@ -145,7 +230,20 @@ module Sentdm
           id: nil,
           # Template name (mutually exclusive with id)
           name: nil,
-          # Template variable parameters for personalization
+          # Template variable parameters for personalization, keyed by variable name.
+          #
+          # Every variable the template declares is required; GET /v3/templates/{id} lists
+          # them. Supplying a key the template does not declare is ignored.
+          #
+          # Media headers. A template whose header is an image (designed in WhatsApp Manager
+          # and imported into Sent) declares a reserved header_image key. Its value is a
+          # publicly reachable https URL that Meta fetches at send time — Sent does not host
+          # the asset, and the sample approved with the template is not reused. The key is
+          # derived from the header's media type, so header_video and header_document follow
+          # the same shape when those formats ship.
+          #
+          # "parameters": { "header_image": "https://cdn.example.com/banner.jpg", "name":
+          # "John Doe" }
           parameters: nil
         )
         end

data/rbi/sentdm/models/message_send_response.rbi

@@ -17,7 +17,9 @@ module Sentdm
       # its result; this is what a caller sees, and the mapping between them is a
       # decision the endpoint makes.
       #
-      # The wire is unchanged by the move: same names, same values.
+      # The shape of an immediate send: it never has a scheduled_at key. A send that
+      # carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+      # which of the two to answer with. From always returns this type.
       sig { returns(T.nilable(Sentdm::Models::MessageSendResponse::Data)) }
       attr_reader :data
 
@@ -68,7 +70,9 @@ module Sentdm
         # its result; this is what a caller sees, and the mapping between them is a
         # decision the endpoint makes.
         #
-        # The wire is unchanged by the move: same names, same values.
+        # The shape of an immediate send: it never has a scheduled_at key. A send that
+        # carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+        # which of the two to answer with. From always returns this type.
         data: nil,
         # Error information
         error: nil,
@@ -120,7 +124,9 @@ module Sentdm
         end
         attr_writer :recipients
 
-        # Overall status — QUEUED once the batch is accepted for delivery.
+        # QUEUED: the batch is accepted. A request that carried scheduled_at is QUEUED
+        # here too; each message moves to SCHEDULED once it is held, as GET
+        # /v3/messages/{id} and the message.scheduled webhook report.
         sig { returns(T.nilable(String)) }
         attr_reader :status
 
@@ -148,7 +154,9 @@ module Sentdm
         # its result; this is what a caller sees, and the mapping between them is a
         # decision the endpoint makes.
         #
-        # The wire is unchanged by the move: same names, same values.
+        # The shape of an immediate send: it never has a scheduled_at key. A send that
+        # carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+        # which of the two to answer with. From always returns this type.
         sig do
           params(
             recipients:
@@ -162,7 +170,9 @@ module Sentdm
         end
         def self.new(
           recipients: nil,
-          # Overall status — QUEUED once the batch is accepted for delivery.
+          # QUEUED: the batch is accepted. A request that carried scheduled_at is QUEUED
+          # here too; each message moves to SCHEDULED once it is held, as GET
+          # /v3/messages/{id} and the message.scheduled webhook report.
           status: nil,
           template_id: nil,
           template_name: nil