sentdm 0.31.0 → 0.33.0

data/rbi/sentdm/models/message_event_payload.rbi

@@ -25,6 +25,12 @@ module Sentdm
       sig { returns(T.nilable(String)) }
       attr_accessor :agent_id
 
+      # The rendered message body, as plain text. Sent as null when we aren't asserting
+      # a body for this event. The field is always present, so read it and check for
+      # null rather than checking whether the key exists. Truncated to 3072 characters.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :body
+
       # The channel the message went out on, for example sms or whatsapp. A message that
       # falls back to another channel reports the channel actually used.
       sig { returns(T.nilable(String)) }
@@ -48,6 +54,17 @@ module Sentdm
       sig { params(outbound_number: String).void }
       attr_writer :outbound_number
 
+      # message.scheduled only: why the message is held, either because you scheduled it
+      # or because the recipient is inside a protected quiet-hours window. Omitted on
+      # every other event.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :schedule_reason
+
+      # message.scheduled only: when the held message will be released for delivery, in
+      # UTC (yyyy-MM-ddTHH:mm:ssZ). Omitted on every other event.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :scheduled_at
+
       # The template the message was sent from, when it was sent from one.
       sig { returns(T.nilable(String)) }
       attr_accessor :template_id
@@ -72,9 +89,12 @@ module Sentdm
           message_status: String,
           account_id: String,
           agent_id: T.nilable(String),
+          body: T.nilable(String),
           channel: String,
           message_id: String,
           outbound_number: String,
+          schedule_reason: T.nilable(String),
+          scheduled_at: T.nilable(String),
           template_id: T.nilable(String),
           template_name: T.nilable(String),
           updated_at: String
@@ -89,6 +109,10 @@ module Sentdm
         account_id: nil,
         # The agent attributed to the send, when the send was attributed to one.
         agent_id: nil,
+        # The rendered message body, as plain text. Sent as null when we aren't asserting
+        # a body for this event. The field is always present, so read it and check for
+        # null rather than checking whether the key exists. Truncated to 3072 characters.
+        body: nil,
         # The channel the message went out on, for example sms or whatsapp. A message that
         # falls back to another channel reports the channel actually used.
         channel: nil,
@@ -97,6 +121,13 @@ module Sentdm
         message_id: nil,
         # The recipient's number in E.164 format.
         outbound_number: nil,
+        # message.scheduled only: why the message is held, either because you scheduled it
+        # or because the recipient is inside a protected quiet-hours window. Omitted on
+        # every other event.
+        schedule_reason: nil,
+        # message.scheduled only: when the held message will be released for delivery, in
+        # UTC (yyyy-MM-ddTHH:mm:ssZ). Omitted on every other event.
+        scheduled_at: nil,
         # The template the message was sent from, when it was sent from one.
         template_id: nil,
         # Name of the template the message was sent from. Omitted when the message wasn't
@@ -113,9 +144,12 @@ module Sentdm
             message_status: String,
             account_id: String,
             agent_id: T.nilable(String),
+            body: T.nilable(String),
             channel: String,
             message_id: String,
             outbound_number: String,
+            schedule_reason: T.nilable(String),
+            scheduled_at: T.nilable(String),
             template_id: T.nilable(String),
             template_name: T.nilable(String),
             updated_at: String

data/rbi/sentdm/models/message_retrieve_activities_response.rbi

@@ -203,8 +203,15 @@ module Sentdm
           sig { returns(T.nilable(String)) }
           attr_accessor :price
 
-          # Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SENT, DELIVERED, READ,
-          # FAILED. Inbound (from contact): RECEIVED (terminal).
+          # SCHEDULED activities only: when the held message will be released for delivery,
+          # in UTC. Same wire name as on the send response, the message and the webhook.
+          # Omitted on every other activity. A message that quiet hours moved at release has
+          # two SCHEDULED entries, each carrying the instant as it stood at that moment.
+          sig { returns(T.nilable(Time)) }
+          attr_accessor :scheduled_at
+
+          # Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SCHEDULED, SENT,
+          # DELIVERED, READ, FAILED. Inbound (from contact): RECEIVED (terminal).
           sig { returns(T.nilable(String)) }
           attr_reader :status
 
@@ -218,13 +225,18 @@ module Sentdm
           sig { params(timestamp: Time).void }
           attr_writer :timestamp
 
-          # A single message activity event for v3 API
+          # A single message activity event for v3 API.
+          #
+          # The activity list mixes statuses, so unlike a message it is one shape rather
+          # than two: a SCHEDULED entry carries scheduled_at, and every other entry has no
+          # such key.
           sig do
             params(
               active_contact_price: T.nilable(String),
               description: String,
               from: T.nilable(String),
               price: T.nilable(String),
+              scheduled_at: T.nilable(Time),
               status: String,
               timestamp: Time
             ).returns(T.attached_class)
@@ -242,8 +254,13 @@ module Sentdm
             # Channel cost for this activity (e.g., SMS/WhatsApp provider cost), formatted to
             # 4 decimal places.
             price: nil,
-            # Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SENT, DELIVERED, READ,
-            # FAILED. Inbound (from contact): RECEIVED (terminal).
+            # SCHEDULED activities only: when the held message will be released for delivery,
+            # in UTC. Same wire name as on the send response, the message and the webhook.
+            # Omitted on every other activity. A message that quiet hours moved at release has
+            # two SCHEDULED entries, each carrying the instant as it stood at that moment.
+            scheduled_at: nil,
+            # Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SCHEDULED, SENT,
+            # DELIVERED, READ, FAILED. Inbound (from contact): RECEIVED (terminal).
             status: nil,
             # When this activity occurred
             timestamp: nil
@@ -257,6 +274,7 @@ module Sentdm
                 description: String,
                 from: T.nilable(String),
                 price: T.nilable(String),
+                scheduled_at: T.nilable(Time),
                 status: String,
                 timestamp: Time
               }

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(
@@ -202,7 +219,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,
@@ -242,7 +264,14 @@ 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,
@@ -363,8 +392,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 +453,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 +498,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 +567,94 @@ 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 Constants.MmsMediaTypes when known. Advisory — the carrier reads the
+            # fetched object's Content-Type, not this.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :media_type
+
+            sig { returns(T.nilable(String)) }
+            attr_reader :url
+
+            sig { params(url: String).void }
+            attr_writer :url
+
+            # One attachment on a message: a customer-supplied public URL handed to the
+            # carrier as-is.
+            #
+            #              A URL and nothing else. sent.dm never takes custody of MMS media — the customer hosts it and we
+            #              pass the link through at send time — so there is no storage key, size or expiry to record. If we ever
+            #              do host attachments, that belongs with the change that introduces the hosting, not here.
+            sig do
+              params(media_type: T.nilable(String), url: String).returns(
+                T.attached_class
+              )
+            end
+            def self.new(
+              # One of Constants.MmsMediaTypes when known. Advisory — the carrier reads the
+              # fetched object's Content-Type, not this.
+              media_type: nil,
+              url: nil
+            )
+            end
+
+            sig do
+              override.returns({ media_type: T.nilable(String), url: 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