sentdm 0.32.0 → 0.34.0

data/lib/sentdm/models/conversation_messages_list.rb

@@ -67,7 +67,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::ConversationMessagesList::Message::MessageBody, nil]
         optional :message_body, -> { Sentdm::ConversationMessagesList::Message::MessageBody }, nil?: true
@@ -87,6 +94,24 @@ module Sentdm
         #   @return [Float, nil]
         optional :price, Float, nil?: true
 
+        # @!attribute reason
+        #   A human-readable sentence for reason_code, for example "Insufficient balance".
+        #   Omitted whenever reason_code is.
+        #
+        #   @return [String, nil]
+        optional :reason, String, nil?: true
+
+        # @!attribute reason_code
+        #   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.
+        #
+        #   @return [String, nil]
+        optional :reason_code, String, nil?: true
+
         # @!attribute region_code
         #
         #   @return [String, nil]
@@ -112,11 +137,16 @@ module Sentdm
         #   @return [String, nil]
         optional :template_name, String, nil?: true
 
-        # @!method initialize(id: nil, active_contact_price: nil, channel: nil, contact_id: nil, created_at: nil, customer_id: nil, direction: nil, events: nil, message_body: nil, phone: nil, phone_international: nil, price: nil, region_code: nil, status: nil, template_category: nil, template_id: nil, template_name: nil)
+        # @!method initialize(id: nil, active_contact_price: nil, channel: nil, contact_id: nil, created_at: nil, customer_id: nil, direction: nil, events: nil, message_body: nil, phone: nil, phone_international: nil, price: nil, reason: nil, reason_code: nil, region_code: nil, status: nil, template_category: nil, template_id: nil, template_name: nil)
         #   Some parameter documentations has been truncated, see
         #   {Sentdm::Models::ConversationMessagesList::Message} 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]
         #
@@ -142,6 +172,10 @@ module Sentdm
         #
         #   @param price [Float, nil]
         #
+        #   @param reason [String, nil] A human-readable sentence for reason_code, for example "Insufficient balance". O
+        #
+        #   @param reason_code [String, nil] Why the message is at its current status, as a stable platform code such as
+        #
         #   @param region_code [String]
         #
         #   @param status [String]
@@ -168,12 +202,37 @@ module Sentdm
           #   @return [String, nil]
           optional :description, String, nil?: true
 
-          # @!method initialize(status:, timestamp:, description: nil)
+          # @!attribute reason
+          #   A human-readable sentence for reason_code. Omitted whenever reason_code is.
+          #
+          #   @return [String, nil]
+          optional :reason, String, nil?: true
+
+          # @!attribute reason_code
+          #   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.
+          #
+          #   @return [String, nil]
+          optional :reason_code, String, nil?: true
+
+          # @!method initialize(status:, timestamp:, description: nil, reason: nil, reason_code: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {Sentdm::Models::ConversationMessagesList::Message::Event} for more details.
+          #
           #   Represents a status change event in a message's lifecycle (v3)
           #
           #   @param status [String]
+          #
           #   @param timestamp [Time]
+          #
           #   @param description [String, nil]
+          #
+          #   @param reason [String, nil] A human-readable sentence for reason_code. Omitted whenever reason_code is.
+          #
+          #   @param reason_code [String, nil] Why the message reached this status, as a stable platform code such as
+          #   DELIVERY\_
         end
 
         # @see Sentdm::Models::ConversationMessagesList::Message#message_body
@@ -202,14 +261,65 @@ 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::ConversationMessagesList::Message::MessageBody::HeaderMedia, nil]
+          optional :header_media,
+                   -> { Sentdm::ConversationMessagesList::Message::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::ConversationMessagesList::Message::MessageBody::Media>, nil]
+          optional :media,
+                   -> {
+                     Sentdm::Internal::Type::ArrayOf[Sentdm::ConversationMessagesList::Message::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::ConversationMessagesList::Message::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::ConversationMessagesList::Message::MessageBody::Button>, nil]
+          #
           #   @param content [String]
+          #
           #   @param footer [String, nil]
+          #
           #   @param header [String, nil]
+          #
+          #   @param header_media [Sentdm::Models::ConversationMessagesList::Message::MessageBody::HeaderMedia, nil] The media asset that rode a message's header, recorded as sent.
+          #
+          #   @param media [Array<Sentdm::Models::ConversationMessagesList::Message::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
@@ -238,6 +348,104 @@ module Sentdm
             #   @param type [String]
             #   @param value [String]
           end
+
+          # @see Sentdm::Models::ConversationMessagesList::Message::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::ConversationMessagesList::Message::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 MmsMediaTypes when the content type is known. Advisory — a reader should
+            #   trust the fetched object's own Content-Type.
+            #
+            #   @return [String, nil]
+            optional :media_type, String, api_name: :mediaType, nil?: true
+
+            # @!attribute mime_type
+            #   Content type as the provider declared it. Null when it declared none.
+            #
+            #   @return [String, nil]
+            optional :mime_type, String, api_name: :mimeType, nil?: true
+
+            # @!attribute size_bytes
+            #   Size as the provider declared it. Never measured here — nothing downloads the
+            #   file.
+            #
+            #   @return [Integer, nil]
+            optional :size_bytes, Integer, api_name: :sizeBytes, nil?: true
+
+            # @!attribute source_hash_sha256
+            #   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.
+            #
+            #   @return [String, nil]
+            optional :source_hash_sha256, String, api_name: :sourceHashSha256, nil?: true
+
+            # @!attribute url
+            #   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.
+            #
+            #   @return [String, nil]
+            optional :url, String, nil?: true
+
+            # @!method initialize(media_type: nil, mime_type: nil, size_bytes: nil, source_hash_sha256: nil, url: nil)
+            #   Some parameter documentations has been truncated, see
+            #   {Sentdm::Models::ConversationMessagesList::Message::MessageBody::Media} for more
+            #   details.
+            #
+            #   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.
+            #
+            #   @param media_type [String, nil] One of MmsMediaTypes when the content type is known. Advisory — a reader should
+            #
+            #   @param mime_type [String, nil] Content type as the provider declared it. Null when it declared none.
+            #
+            #   @param size_bytes [Integer, nil] Size as the provider declared it. Never measured here — nothing downloads the fi
+            #
+            #   @param source_hash_sha256 [String, nil] Inbound only: the SHA-256 the provider declared alongside the attachment, when i
+            #
+            #   @param url [String, nil] Where the file lives. Outbound: the URL the customer gave us and the carrier fet
+          end
         end
       end
     end

data/lib/sentdm/models/inbound_message_event_payload.rb

@@ -22,11 +22,28 @@ module Sentdm
       optional :account_id, String
 
       # @!attribute channel
-      #   The channel the message arrived on, for example sms or whatsapp.
+      #   The channel the message arrived on, for example sms or mms.
       #
       #   @return [String, nil]
       optional :channel, String
 
+      # @!attribute media
+      #   Attachments the contact sent, present only on channels that carry them (mms
+      #   today) and omitted entirely otherwise.
+      #
+      #   Each url points at the carrier's own copy of the file — sent.dm records where
+      #   the attachment is, not the attachment itself. The link is unauthenticated and
+      #   expires on the carrier's schedule, which differs between them: assume days, not
+      #   months. Download what you need on receipt; re-reading the message through GET
+      #   /v3/messages/{id} returns the same stored link, not a fresh one, so once it
+      #   lapses the entry remains with whatever the carrier declared about the file but
+      #   the file is no longer reachable.
+      #
+      #   @return [Array<Sentdm::Models::InboundMessageEventPayload::Media>, nil]
+      optional :media,
+               -> { Sentdm::Internal::Type::ArrayOf[Sentdm::InboundMessageEventPayload::Media] },
+               nil?: true
+
       # @!attribute message_id
       #   The inbound message.
       #
@@ -54,7 +71,7 @@ module Sentdm
       #   @return [String, nil]
       optional :updated_at, String
 
-      # @!method initialize(inbound_number:, received_at:, account_id: nil, channel: nil, message_id: nil, outbound_number: nil, text: nil, updated_at: nil)
+      # @!method initialize(inbound_number:, received_at:, account_id: nil, channel: nil, media: nil, message_id: nil, outbound_number: nil, text: nil, updated_at: nil)
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::InboundMessageEventPayload} for more details.
       #
@@ -67,7 +84,9 @@ module Sentdm
       #
       #   @param account_id [String] The account the message belongs to.
       #
-      #   @param channel [String] The channel the message arrived on, for example sms or whatsapp.
+      #   @param channel [String] The channel the message arrived on, for example sms or mms.
+      #
+      #   @param media [Array<Sentdm::Models::InboundMessageEventPayload::Media>, nil] Attachments the contact sent, present only on channels that carry them (mms toda
       #
       #   @param message_id [String] The inbound message.
       #
@@ -76,6 +95,54 @@ module Sentdm
       #   @param text [String, nil] The message body. Sent as null when the inbound message carried no text, for
       #
       #   @param updated_at [String] When the message was received, in UTC (yyyy-MM-ddTHH:mm:ssZ). Same value as
+
+      class Media < Sentdm::Internal::Type::BaseModel
+        # @!attribute hash_sha256
+        #   SHA-256 of the file as the carrier declared it, when it declares one. Verify
+        #   what you download against this — sent.dm never reads the bytes, so it is the
+        #   only integrity signal available.
+        #
+        #   @return [String, nil]
+        optional :hash_sha256, String, nil?: true
+
+        # @!attribute mime_type
+        #   Content type as the carrier reported it, for example image/jpeg.
+        #
+        #   @return [String, nil]
+        optional :mime_type, String, nil?: true
+
+        # @!attribute size_bytes
+        #   Size in bytes as the carrier declared it. Absent when it declared none.
+        #
+        #   @return [Integer, nil]
+        optional :size_bytes, Integer, nil?: true
+
+        # @!attribute url
+        #   Where the carrier hosts the attachment.
+        #
+        #   This link expires and is not authenticated. sent.dm relays it rather than
+        #   copying the file, so how long it stays fetchable is the carrier's decision and
+        #   differs between them — assume days, not months. Anyone holding the URL can fetch
+        #   it until it lapses. Copy the file on receipt if you need it to outlive that
+        #   window; do not store this URL as a permanent reference.
+        #
+        #   @return [String, nil]
+        optional :url, String, nil?: true
+
+        # @!method initialize(hash_sha256: nil, mime_type: nil, size_bytes: nil, url: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Sentdm::Models::InboundMessageEventPayload::Media} for more details.
+        #
+        #   One attachment on an inbound message.
+        #
+        #   @param hash_sha256 [String, nil] SHA-256 of the file as the carrier declared it, when it declares one. Verify wha
+        #
+        #   @param mime_type [String, nil] Content type as the carrier reported it, for example image/jpeg.
+        #
+        #   @param size_bytes [Integer, nil] Size in bytes as the carrier declared it. Absent when it declared none.
+        #
+        #   @param url [String, nil] Where the carrier hosts the attachment.
+      end
     end
   end
 end

data/lib/sentdm/models/me_retrieve_response.rb

@@ -77,6 +77,24 @@ module Sentdm
         #   @return [String, nil]
         optional :email, String, nil?: true
 
+        # @!attribute enable_template_auto_creation_for_sp
+        #   Whether this account may mark a template for automatic creation on its sender
+        #   profiles. Granted by Sent per account and off by default, so it is what a
+        #   template-create form reads to decide whether to offer the option at all —
+        #   marking a template without it does nothing.
+        #
+        #   Top-level rather than inside settings, which is written for type: "profile" only
+        #   and so would never carry it to the account type that can act on it.
+        #
+        #   This is the capability, not the stored flag: a profile reports false whatever
+        #   its own row holds. A sender profile owns no sender profiles, so a template it
+        #   marked would have nothing to be created on and the fan-out would never read the
+        #   flag. The admin GET /customers/{id} reports the stored value instead, because
+        #   that is the one an operator granted.
+        #
+        #   @return [Boolean, nil]
+        optional :enable_template_auto_creation_for_sp, Sentdm::Internal::Type::Boolean
+
         # @!attribute icon
         #   Account icon URL
         #
@@ -155,7 +173,7 @@ module Sentdm
         #   @return [String, nil]
         optional :type, String
 
-        # @!method initialize(id: nil, channels: nil, created_at: nil, description: nil, email: nil, icon: nil, name: nil, organization_id: nil, profiles: nil, sending_phone_number: nil, sending_phone_number_profile_id: nil, settings: nil, short_name: nil, status: nil, type: nil)
+        # @!method initialize(id: nil, channels: nil, created_at: nil, description: nil, email: nil, enable_template_auto_creation_for_sp: nil, icon: nil, name: nil, organization_id: nil, profiles: nil, sending_phone_number: nil, sending_phone_number_profile_id: nil, settings: nil, short_name: nil, status: nil, type: nil)
         #   Some parameter documentations has been truncated, see
         #   {Sentdm::Models::MeRetrieveResponse::Data} for more details.
         #
@@ -173,6 +191,8 @@ module Sentdm
         #
         #   @param email [String, nil] Contact email address
         #
+        #   @param enable_template_auto_creation_for_sp [Boolean] Whether this account may mark a template for automatic creation on its sender pr
+        #
         #   @param icon [String, nil] Account icon URL
         #
         #   @param name [String] Account name

data/lib/sentdm/models/message_event_payload.rb

@@ -51,6 +51,39 @@ module Sentdm
       #   @return [String, nil]
       optional :outbound_number, String
 
+      # @!attribute reason
+      #   A human-readable sentence for ReasonCode, for example "The recipient is not
+      #   registered on this channel". Omitted whenever reason_code is.
+      #
+      #   @return [String, nil]
+      optional :reason, String, nil?: true
+
+      # @!attribute reason_code
+      #   Why the message reached this status, as a stable platform code such as
+      #   DELIVERY_007 or BUSINESS_003. Present on message.failed, message.filtered and
+      #   message.blocked; omitted on every status that needs no explanation. 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 and never a carrier or vendor
+      #   code.
+      #
+      #   @return [String, nil]
+      optional :reason_code, String, nil?: true
+
+      # @!attribute schedule_reason
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :schedule_reason, String, nil?: true
+
+      # @!attribute scheduled_at
+      #   message.scheduled only: when the held message will be released for delivery, in
+      #   UTC (yyyy-MM-ddTHH:mm:ssZ). Omitted on every other event.
+      #
+      #   @return [String, nil]
+      optional :scheduled_at, String, nil?: true
+
       # @!attribute template_id
       #   The template the message was sent from, when it was sent from one.
       #
@@ -70,7 +103,7 @@ module Sentdm
       #   @return [String, nil]
       optional :updated_at, String
 
-      # @!method initialize(message_status:, account_id: nil, agent_id: nil, body: nil, channel: nil, message_id: nil, outbound_number: nil, template_id: nil, template_name: nil, updated_at: nil)
+      # @!method initialize(message_status:, account_id: nil, agent_id: nil, body: nil, channel: nil, message_id: nil, outbound_number: nil, reason: nil, reason_code: nil, schedule_reason: nil, scheduled_at: nil, template_id: nil, template_name: nil, updated_at: nil)
       #   Some parameter documentations has been truncated, see
       #   {Sentdm::Models::MessageEventPayload} for more details.
       #
@@ -92,6 +125,14 @@ module Sentdm
       #
       #   @param outbound_number [String] The recipient's number in E.164 format.
       #
+      #   @param reason [String, nil] A human-readable sentence for ReasonCode, for example "The recipient is not regi
+      #
+      #   @param reason_code [String, nil] Why the message reached this status, as a stable platform code such as
+      #
+      #   @param schedule_reason [String, nil] message.scheduled only: why the message is held, either because you scheduled it
+      #
+      #   @param scheduled_at [String, nil] message.scheduled only: when the held message will be released for delivery, in
+      #
       #   @param template_id [String, nil] The template the message was sent from, when it was sent from one.
       #
       #   @param template_name [String, nil] Name of the template the message was sent from. Omitted when the message wasn't

data/lib/sentdm/models/message_retrieve_activities_response.rb

@@ -98,9 +98,35 @@ module Sentdm
           #   @return [String, nil]
           optional :price, String, nil?: true
 
+          # @!attribute reason
+          #   A human-readable sentence for reason_code, for example "The recipient is not
+          #   registered on this channel" Omitted whenever reason_code is.
+          #
+          #   @return [String, nil]
+          optional :reason, String, nil?: true
+
+          # @!attribute reason_code
+          #   Why the message reached this status, as a stable platform code such as
+          #   DELIVERY_007 or BUSINESS_003. Present on FAILED, FILTERED and BLOCKED
+          #   activities; omitted on every status that needs no explanation. Switch on this
+          #   rather than on reason: the code is stable, the wording may be improved. Same
+          #   wire name and vocabulary as on the message and the webhook.
+          #
+          #   @return [String, nil]
+          optional :reason_code, 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 +137,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, reason: nil, reason_code: 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 +156,14 @@ 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 reason [String, nil] A human-readable sentence for reason_code, for example "The recipient is not reg
+          #
+          #   @param reason_code [String, nil] Why the message reached this status, as a stable platform code such as
+          #   DELIVERY\_
+          #
+          #   @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