sentdm 0.32.0 → 0.33.0

data/lib/sentdm/models/message_retrieve_activities_response.rb

@@ -98,9 +98,18 @@ module Sentdm
           #   @return [String, nil]
           optional :price, String, nil?: true
 
+          # @!attribute scheduled_at
+          #   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.
+          #
+          #   @return [Time, nil]
+          optional :scheduled_at, Time, nil?: true
+
           # @!attribute status
-          #   Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SENT, DELIVERED, READ,
-          #   FAILED. Inbound (from contact): RECEIVED (terminal).
+          #   Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SCHEDULED, SENT,
+          #   DELIVERED, READ, FAILED. Inbound (from contact): RECEIVED (terminal).
           #
           #   @return [String, nil]
           optional :status, String
@@ -111,12 +120,16 @@ module Sentdm
           #   @return [Time, nil]
           optional :timestamp, Time
 
-          # @!method initialize(active_contact_price: nil, description: nil, from: nil, price: nil, status: nil, timestamp: nil)
+          # @!method initialize(active_contact_price: nil, description: nil, from: nil, price: nil, scheduled_at: nil, status: nil, timestamp: nil)
           #   Some parameter documentations has been truncated, see
           #   {Sentdm::Models::MessageRetrieveActivitiesResponse::Data::Activity} for more
           #   details.
           #
-          #   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.
           #
           #   @param active_contact_price [String, nil] Active contact markup applied on top of the channel cost, formatted to 4 decimal
           #
@@ -126,7 +139,9 @@ module Sentdm
           #
           #   @param price [String, nil] Channel cost for this activity (e.g., SMS/WhatsApp provider cost), formatted to
           #
-          #   @param status [String] Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SENT, DELIVERED, READ, FAI
+          #   @param scheduled_at [Time, nil] SCHEDULED activities only: when the held message will be released for delivery,
+          #
+          #   @param status [String] Activity status. Outbound: QUEUED, PROCESSED, ROUTED, SCHEDULED, SENT, DELIVERED
           #
           #   @param timestamp [Time] When this activity occurred
         end

data/lib/sentdm/models/message_retrieve_status_response.rb

@@ -5,7 +5,12 @@ module Sentdm
     # @see Sentdm::Resources::Messages#retrieve_status
     class MessageRetrieveStatusResponse < Sentdm::Internal::Type::BaseModel
       # @!attribute data
-      #   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.
       #
       #   @return [Sentdm::Models::MessageRetrieveStatusResponse::Data, nil]
       optional :data, -> { Sentdm::Models::MessageRetrieveStatusResponse::Data }, nil?: true
@@ -29,9 +34,12 @@ module Sentdm
       optional :success, Sentdm::Internal::Type::Boolean
 
       # @!method initialize(data: nil, error: nil, meta: nil, success: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Sentdm::Models::MessageRetrieveStatusResponse} for more details.
+      #
       #   Standard API response envelope for all v3 endpoints
       #
-      #   @param data [Sentdm::Models::MessageRetrieveStatusResponse::Data, nil] Message response for v3 API — same shape as v2 with snake_case JSON conventions
+      #   @param data [Sentdm::Models::MessageRetrieveStatusResponse::Data, nil] Message response for v3 API — same shape as v2 with snake_case JSON conventions.
       #
       #   @param error [Sentdm::Models::ErrorDetail, nil] Error information
       #
@@ -85,7 +93,14 @@ module Sentdm
 
         # @!attribute message_body
         #   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.
         #
         #   @return [Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody, nil]
         optional :message_body,
@@ -136,7 +151,12 @@ module Sentdm
         #   Some parameter documentations has been truncated, see
         #   {Sentdm::Models::MessageRetrieveStatusResponse::Data} for more details.
         #
-        #   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.
         #
         #   @param id [String]
         #
@@ -220,14 +240,63 @@ module Sentdm
           #   @return [String, nil]
           optional :header, String, nil?: true
 
-          # @!method initialize(buttons: nil, content: nil, footer: nil, header: nil)
+          # @!attribute header_media
+          #   The media asset that rode a message's header, recorded as sent.
+          #
+          #   @return [Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia, nil]
+          optional :header_media,
+                   -> { Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia },
+                   api_name: :headerMedia,
+                   nil?: true
+
+          # @!attribute 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.
+          #
+          #   @return [Array<Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media>, nil]
+          optional :media,
+                   -> { Sentdm::Internal::Type::ArrayOf[Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media] },
+                   nil?: true
+
+          # @!attribute subject
+          #   MMS subject line. Null on every other channel.
+          #
+          #   @return [String, nil]
+          optional :subject, String, nil?: true
+
+          # @!method initialize(buttons: nil, content: nil, footer: nil, header: nil, header_media: nil, media: nil, subject: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody} for more
+          #   details.
+          #
           #   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.
           #
           #   @param buttons [Array<Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Button>, nil]
+          #
           #   @param content [String]
+          #
           #   @param footer [String, nil]
+          #
           #   @param header [String, nil]
+          #
+          #   @param header_media [Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia, nil] The media asset that rode a message's header, recorded as sent.
+          #
+          #   @param media [Array<Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media>, nil] MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on e
+          #
+          #   @param subject [String, nil] MMS subject line. Null on every other channel.
 
           class Button < Sentdm::Internal::Type::BaseModel
             # @!attribute postback_data
@@ -256,6 +325,64 @@ module Sentdm
             #   @param type [String]
             #   @param value [String]
           end
+
+          # @see Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody#header_media
+          class HeaderMedia < Sentdm::Internal::Type::BaseModel
+            # @!attribute type
+            #   "image", "video" or "document" — taken from the header's media variable.
+            #
+            #   @return [String, nil]
+            optional :type, String
+
+            # @!attribute url
+            #   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.
+            #
+            #   @return [String, nil]
+            optional :url, String
+
+            # @!method initialize(type: nil, url: nil)
+            #   Some parameter documentations has been truncated, see
+            #   {Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::HeaderMedia}
+            #   for more details.
+            #
+            #   The media asset that rode a message's header, recorded as sent.
+            #
+            #   @param type [String] "image", "video" or "document" — taken from the header's media variable.
+            #
+            #   @param url [String] The https URL the caller supplied for this send. Never the template's stored
+          end
+
+          class Media < Sentdm::Internal::Type::BaseModel
+            # @!attribute media_type
+            #   One of Constants.MmsMediaTypes when known. Advisory — the carrier reads the
+            #   fetched object's Content-Type, not this.
+            #
+            #   @return [String, nil]
+            optional :media_type, String, api_name: :mediaType, nil?: true
+
+            # @!attribute url
+            #
+            #   @return [String, nil]
+            optional :url, String
+
+            # @!method initialize(media_type: nil, url: nil)
+            #   Some parameter documentations has been truncated, see
+            #   {Sentdm::Models::MessageRetrieveStatusResponse::Data::MessageBody::Media} for
+            #   more details.
+            #
+            #   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.
+            #
+            #   @param media_type [String, nil] One of Constants.MmsMediaTypes when known. Advisory — the carrier reads the
+            #
+            #   @param url [String]
+          end
         end
       end
     end

data/lib/sentdm/models/message_send_params.rb

@@ -15,6 +15,25 @@ module Sentdm
       #   @return [Array<String>, nil]
       optional :channel, Sentdm::Internal::Type::ArrayOf[String], nil?: true
 
+      # @!attribute media_urls
+      #   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.
+      #
+      #   @return [Array<String>, nil]
+      optional :media_urls, Sentdm::Internal::Type::ArrayOf[String], nil?: true
+
       # @!attribute sandbox
       #   Sandbox flag - when true, the operation is simulated without side effects Useful
       #   for testing integrations without actual execution
@@ -22,6 +41,29 @@ module Sentdm
       #   @return [Boolean, nil]
       optional :sandbox, Sentdm::Internal::Type::Boolean
 
+      # @!attribute scheduled_at
+      #   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.
+      #
+      #   @return [Time, nil]
+      optional :scheduled_at, Time, nil?: true
+
+      # @!attribute subject
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :subject, String, nil?: true
+
       # @!attribute template
       #   SDK-style template reference: resolve by ID or by name, with optional
       #   parameters.
@@ -51,14 +93,20 @@ module Sentdm
       #   @return [String, nil]
       optional :x_profile_id, String
 
-      # @!method initialize(channel: nil, sandbox: nil, template: nil, text: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      # @!method initialize(channel: nil, media_urls: nil, sandbox: nil, scheduled_at: nil, subject: nil, template: nil, text: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::MessageSendParams} for more details.
       #
       #   @param channel [Array<String>, nil] Channels to broadcast on, e.g. ["whatsapp", "sms"].
       #
+      #   @param media_urls [Array<String>, nil] Attachments for this send, as publicly fetchable https URLs. Used by the MMS cha
+      #
       #   @param sandbox [Boolean] Sandbox flag - when true, the operation is simulated without side effects
       #
+      #   @param scheduled_at [Time, nil] Optional future send time as an ISO-8601 timestamp with an explicit UTC offset,
+      #
+      #   @param subject [String, nil] Subject line for this send, overriding the template's. MMS only; ignored on ever
+      #
       #   @param template [Sentdm::Models::MessageSendParams::Template, nil] SDK-style template reference: resolve by ID or by name, with optional parameters
       #
       #   @param text [String, nil] Plain-text (free-form) message body. Provide either Template or this.
@@ -85,12 +133,28 @@ module Sentdm
         optional :name, String, nil?: true
 
         # @!attribute parameters
-        #   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" }
         #
         #   @return [Hash{Symbol=>String}, nil]
         optional :parameters, Sentdm::Internal::Type::HashOf[String], nil?: true
 
         # @!method initialize(id: nil, name: nil, parameters: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Sentdm::Models::MessageSendParams::Template} for more details.
+        #
         #   SDK-style template reference: resolve by ID or by name, with optional
         #   parameters.
         #
@@ -98,7 +162,7 @@ module Sentdm
         #
         #   @param name [String, nil] Template name (mutually exclusive with id)
         #
-        #   @param parameters [Hash{Symbol=>String}, nil] Template variable parameters for personalization
+        #   @param parameters [Hash{Symbol=>String}, nil] Template variable parameters for personalization, keyed by variable name.
       end
     end
   end

data/lib/sentdm/models/message_send_response.rb

@@ -14,7 +14,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.
       #
       #   @return [Sentdm::Models::MessageSendResponse::Data, nil]
       optional :data, -> { Sentdm::Models::MessageSendResponse::Data }, nil?: true
@@ -60,7 +62,9 @@ module Sentdm
                  -> { Sentdm::Internal::Type::ArrayOf[Sentdm::Models::MessageSendResponse::Data::Recipient] }
 
         # @!attribute status
-        #   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.
         #
         #   @return [String, nil]
         optional :status, String
@@ -76,6 +80,9 @@ module Sentdm
         optional :template_name, String
 
         # @!method initialize(recipients: nil, status: nil, template_id: nil, template_name: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Sentdm::Models::MessageSendResponse::Data} for more details.
+        #
         #   The result of a multi-recipient send.
         #
         #   Declared here rather than in the service layer. POST /v3/messages used to
@@ -85,11 +92,13 @@ 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.
         #
         #   @param recipients [Array<Sentdm::Models::MessageSendResponse::Data::Recipient>]
         #
-        #   @param status [String] Overall status — QUEUED once the batch is accepted for delivery.
+        #   @param status [String] QUEUED: the batch is accepted. A request that carried scheduled_at is QUEUED
         #
         #   @param template_id [String]
         #

data/lib/sentdm/models/template_body.rb

@@ -3,6 +3,18 @@
 module Sentdm
   module Models
     class TemplateBody < Sentdm::Internal::Type::BaseModel
+      # @!attribute mms
+      #   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.
+      #
+      #   @return [Sentdm::Models::TemplateBody::Mms, nil]
+      optional :mms, -> { Sentdm::TemplateBody::Mms }, nil?: true
+
       # @!attribute multi_channel
       #   The shared body, used for every channel. One half of the choice described above.
       #
@@ -29,7 +41,7 @@ module Sentdm
       #   @return [Sentdm::Models::TemplateBodyContent, nil]
       optional :whatsapp, -> { Sentdm::TemplateBodyContent }, nil?: true
 
-      # @!method initialize(multi_channel: nil, rcs: nil, sms: nil, whatsapp: nil)
+      # @!method initialize(mms: nil, multi_channel: nil, rcs: nil, sms: nil, whatsapp: nil)
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::TemplateBody} for more details.
       #
@@ -44,6 +56,8 @@ module Sentdm
       #   channel. rcs is the one true override: it may accompany either strategy to vary
       #   the copy, but cannot stand alone.
       #
+      #   @param mms [Sentdm::Models::TemplateBody::Mms, nil] MMS-specific content — subject, text and attachments.
+      #
       #   @param multi_channel [Sentdm::Models::TemplateBodyContent, nil] The shared body, used for every channel. One half of the choice described above.
       #
       #   @param rcs [Sentdm::Models::TemplateBodyContent, nil] RCS-specific copy that overrides the chosen strategy for RCS only. The one true
@@ -51,6 +65,73 @@ module Sentdm
       #   @param sms [Sentdm::Models::TemplateBodyContent, nil] The SMS body. It does not override multiChannel, it replaces it.
       #
       #   @param whatsapp [Sentdm::Models::TemplateBodyContent, nil] The WhatsApp body. It does not override multiChannel, it replaces it.
+
+      # @see Sentdm::Models::TemplateBody#mms
+      class Mms < Sentdm::Models::TemplateBodyContent
+        # @!attribute media
+        #   Attachments carried by every send on this template, in order. A per-send
+        #   media_urls on the request replaces this list rather than adding to it, so a
+        #   template can hold a default creative and a caller can still send something
+        #   recipient-specific.
+        #
+        #   @return [Array<Sentdm::Models::TemplateBody::Mms::Media>, nil]
+        optional :media, -> { Sentdm::Internal::Type::ArrayOf[Sentdm::TemplateBody::Mms::Media] }, nil?: true
+
+        # @!attribute subject
+        #   MMS subject line. Optional — most handsets render it above the body, some ignore
+        #   it entirely. Deliberately its own field rather than riding TemplateHeader: the
+        #   header is authored once and shared across every channel, and carries Meta's
+        #   60-character cap plus its no-newline, no-emoji text rules, none of which
+        #   describe an MMS subject.
+        #
+        #   @return [String, nil]
+        optional :subject, String, nil?: true
+
+        # @!method initialize(media: nil, subject: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Sentdm::Models::TemplateBody::Mms} for more details.
+        #
+        #   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.
+        #
+        #   @param media [Array<Sentdm::Models::TemplateBody::Mms::Media>, nil] Attachments carried by every send on this template, in order. A per-send media_u
+        #
+        #   @param subject [String, nil] MMS subject line. Optional — most handsets render it above the body, some ignore
+
+        class Media < Sentdm::Internal::Type::BaseModel
+          # @!attribute media_type
+          #   One of MmsMediaTypes. Advisory: the carrier reads the Content-Type off the
+          #   fetched object, not this field. It exists so an authoring UI can render the
+          #   right preview and so a reviewer can see what was intended.
+          #
+          #   @return [String, nil]
+          optional :media_type, String, api_name: :mediaType, nil?: true
+
+          # @!attribute url
+          #   Publicly fetchable https URL. The carrier's MMSC fetches this at send time, so
+          #   it has to stay reachable and unauthenticated for the life of the send —
+          #   including retries and a DLQ replay — which is why a presigned URL is not a valid
+          #   value here.
+          #
+          #   @return [String, nil]
+          optional :url, String
+
+          # @!method initialize(media_type: nil, url: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {Sentdm::Models::TemplateBody::Mms::Media} for more details.
+          #
+          #   One attachment on an MMS template body.
+          #
+          #   @param media_type [String, nil] One of MmsMediaTypes. Advisory: the carrier reads the Content-Type off the
+          #
+          #   @param url [String] Publicly fetchable https URL. The carrier's MMSC fetches this at send time, so i
+        end
+      end
     end
   end
 end

data/lib/sentdm/models/template_header.rb

@@ -10,8 +10,56 @@ module Sentdm
       #   @return [String]
       required :template, String
 
+      # @!attribute example_url
+      #   Request-only. The s.dm URL of the asset Meta's reviewers see —
+      #   https://s.dm/s/{ID}, eight uppercase characters, uploaded to s.dm out of band.
+      #   NormalizeRichHeader folds it into the synthesized media variable's Props.Sample
+      #   and clears it, so it never persists and a stored definition is indistinguishable
+      #   from an imported one.
+      #
+      #   Stricter than the send path on purpose:
+      #   TemplateUtils.ValidateMediaVariableValues accepts any absolute https URL for the
+      #   per-send asset, because that one is the customer's and may live behind a signed
+      #   CDN link. This one is the review sample, has to outlive every resubmission, and
+      #   so must be ours. Do not "fix" one to match the other.
+      #
+      #   @return [String, nil]
+      optional :example_url, String, nil?: true
+
+      # @!attribute location
+      #   The map pin a location header drops. Meta wants none of this at creation — the
+      #   component is just {"type":"header","format":"location"} — so these values exist
+      #   for Sent: a preview, and the default a StaticResource header falls back to at
+      #   send.
+      #
+      #   @return [Sentdm::Models::TemplateHeader::Location, nil]
+      optional :location, -> { Sentdm::TemplateHeader::Location }, nil?: true
+
+      # @!attribute static_resource
+      #   Whether the asset registered at creation is reused when a caller omits the
+      #   header's variable at send time. Default false — the caller must supply it per
+      #   message, which is the behaviour every existing template has. Written only when
+      #   true, so a default-valued header serializes byte-identically to one imported
+      #   from Meta.
+      #
+      #   Stored and validated but not yet honoured at send: that lands with the Resumable
+      #   Upload work, alongside the code that lets such a template be approved in the
+      #   first place.
+      #
+      #   @return [Boolean, nil]
+      optional :static_resource, Sentdm::Internal::Type::Boolean
+
       # @!attribute type
-      #   The type of header (e.g., "text", "image", "video", "document")
+      #   The kind of header. One of:
+      #
+      #   text — up to 60 characters, at most one variable. image — png, jpg or jpeg.
+      #   Needs ExampleUrl. video — mp4. Needs ExampleUrl. gif — mp4, max 3.5MB. WhatsApp
+      #   renders larger files as an ordinary video. Needs ExampleUrl. document — pdf or
+      #   docx; only the first page is shown as a thumbnail, so pdf is the practical
+      #   choice. Needs ExampleUrl. location — a map pin, supplied through Location.
+      #
+      #   Kept lowercase because MetaToTemplateConverter writes Meta's format through
+      #   ToLowerInvariant() into this field on import, and the two are compared directly.
       #
       #   @return [String, nil]
       optional :type, String, nil?: true
@@ -22,7 +70,7 @@ module Sentdm
       #   @return [Array<Sentdm::Models::TemplateVariable>, nil]
       optional :variables, -> { Sentdm::Internal::Type::ArrayOf[Sentdm::TemplateVariable] }, nil?: true
 
-      # @!method initialize(template:, type: nil, variables: nil)
+      # @!method initialize(template:, example_url: nil, location: nil, static_resource: nil, type: nil, variables: nil)
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::TemplateHeader} for more details.
       #
@@ -30,9 +78,49 @@ module Sentdm
       #
       #   @param template [String] The header template text with optional variable placeholders (e.g., "Welcome to
       #
-      #   @param type [String, nil] The type of header (e.g., "text", "image", "video", "document")
+      #   @param example_url [String, nil] Request-only. The s.dm URL of the asset Meta's reviewers see — https://s.dm/s/{I
+      #
+      #   @param location [Sentdm::Models::TemplateHeader::Location, nil] The map pin a location header drops. Meta wants none of this at creation — the c
+      #
+      #   @param static_resource [Boolean] Whether the asset registered at creation is reused when a caller omits the heade
+      #
+      #   @param type [String, nil] The kind of header. One of:
       #
       #   @param variables [Array<Sentdm::Models::TemplateVariable>, nil] List of variables used in the header template
+
+      # @see Sentdm::Models::TemplateHeader#location
+      class Location < Sentdm::Internal::Type::BaseModel
+        # @!attribute address
+        #
+        #   @return [String]
+        required :address, String
+
+        # @!attribute latitude
+        #
+        #   @return [String]
+        required :latitude, String
+
+        # @!attribute longitude
+        #
+        #   @return [String]
+        required :longitude, String
+
+        # @!attribute name
+        #
+        #   @return [String]
+        required :name, String
+
+        # @!method initialize(address:, latitude:, longitude:, name:)
+        #   The map pin a location header drops. Meta wants none of this at creation — the
+        #   component is just {"type":"header","format":"location"} — so these values exist
+        #   for Sent: a preview, and the default a StaticResource header falls back to at
+        #   send.
+        #
+        #   @param address [String]
+        #   @param latitude [String]
+        #   @param longitude [String]
+        #   @param name [String]
+      end
     end
   end
 end

data/lib/sentdm/models/template_variable.rb

@@ -54,6 +54,11 @@ module Sentdm
         required :media_type, String, api_name: :mediaType
 
         # @!attribute sample
+        #   Example value substituted into the template when previewing it and when
+        #   submitting it to Meta for review. Free text by nature, so the converter accepts
+        #   a JSON number or boolean here and normalizes it — see
+        #   JsonScalarToStringConverter for why — and guarantees it is always serialized
+        #   back out as a JSON string.
         #
         #   @return [String]
         required :sample, String
@@ -84,12 +89,21 @@ module Sentdm
         optional :short_url, String, api_name: :shortUrl, nil?: true
 
         # @!method initialize(media_type:, sample:, url:, variable_type:, alt: nil, regex: nil, short_url: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Sentdm::Models::TemplateVariable::Props} for more details.
+        #
         #   @param media_type [String]
-        #   @param sample [String]
+        #
+        #   @param sample [String] Example value substituted into the template when previewing it and when submitti
+        #
         #   @param url [String]
+        #
         #   @param variable_type [String]
+        #
         #   @param alt [String, nil]
+        #
         #   @param regex [String, nil]
+        #
         #   @param short_url [String, nil]
       end
     end