sentdm 0.32.0 → 0.34.0

data/lib/sentdm/resources/messages.rb

@@ -13,12 +13,20 @@ module Sentdm
     # **A message needs a sender.** What you can send, where, and at what cost is
     # decided by the markets under **Channels** — so a recipient in a country you hold
     # no sender for is refused here rather than queued.
+    #
+    # **A message can be resent on its id.** `POST /v3/messages/{id}/resend` puts a
+    # finished message — typically one BLOCKED for insufficient balance — back through
+    # the send pipeline. It is a new attempt, not a free retry: every policy runs
+    # again, the message is billed again, and its status webhooks fire again. A
+    # FILTERED message is never resendable.
     class Messages
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::MessageRetrieveActivitiesParams} for more details.
       #
       # Retrieves the activity log for a specific message. Activities track the message
-      # lifecycle including acceptance, processing, sending, delivery, and any errors.
+      # lifecycle including acceptance, processing, sending, delivery, and any errors. A
+      # SCHEDULED entry carries scheduled_at, the release instant in UTC as it stood at
+      # that moment. Other entries have no scheduled_at key.
       #
       # @overload retrieve_activities(id, x_profile_id: nil, request_options: {})
       #
@@ -46,7 +54,11 @@ module Sentdm
       # {Sentdm::Models::MessageRetrieveStatusParams} for more details.
       #
       # Retrieves the current status and details of a message by ID. Includes delivery
-      # status, timestamps, and error information if applicable.
+      # status, timestamps, and error information if applicable. A message that is or
+      # was held for a later time (a send you scheduled with scheduled_at, or a
+      # quiet-hours hold) is returned as a ScheduledMessageResponse: the same fields
+      # plus scheduled_at, the release instant in UTC. A message sent immediately has no
+      # scheduled_at key.
       #
       # @overload retrieve_status(id, x_profile_id: nil, request_options: {})
       #
@@ -82,14 +94,30 @@ module Sentdm
       # insufficient balance, a template not approved for sending, or free-form content
       # with no open conversation with the contact. The send is accepted with 202 and
       # the affected messages are reported as BLOCKED on GET /messages/{id} and the
-      # message.blocked webhook.
-      #
-      # @overload send_(channel: nil, sandbox: nil, template: nil, text: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      # message.blocked webhook. To send later, set scheduled_at (ISO-8601 with an
+      # explicit UTC offset; a value without one is rejected) between 1 minute and 30
+      # days ahead: the response is a ScheduledSendMessageResponse (the same fields plus
+      # scheduled_at; status is still QUEUED), each message then moves to SCHEDULED, is
+      # held and released at that time (within a few minutes), and a message.scheduled
+      # webhook fires once it is held. Balance and template approval are evaluated at
+      # release, not at acceptance. Quiet hours are not checked when the request is
+      # accepted: if the time falls inside a legally protected quiet-hours window for a
+      # recipient, that message is moved to the next allowed time at release and a
+      # second message.scheduled webhook reports the new scheduled_at. An account may
+      # hold at most 1,000,000 scheduled messages at once (429 LIMIT_001).
+      #
+      # @overload send_(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: {})
       #
       # @param channel [Array<String>, nil] Body param: Channels to broadcast on, e.g. ["whatsapp", "sms"].
       #
+      # @param media_urls [Array<String>, nil] Body param: Attachments for this send, as publicly fetchable https URLs. Used by
+      #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
+      # @param scheduled_at [Time, nil] Body param: Optional future send time as an ISO-8601 timestamp with an explicit
+      #
+      # @param subject [String, nil] Body param: Subject line for this send, overriding the template's. MMS only; ign
+      #
       # @param template [Sentdm::Models::MessageSendParams::Template, nil] Body param: SDK-style template reference: resolve by ID or by name, with optiona
       #
       # @param text [String, nil] Body param: Plain-text (free-form) message body. Provide either Template or this

data/lib/sentdm/resources/templates.rb

@@ -19,7 +19,9 @@ module Sentdm
       # from the template's content and can be changed afterwards with
       # `PUT /v3/templates/{id}`.
       #
-      # @overload create(category: nil, creation_source: nil, definition: nil, language: nil, sandbox: nil, submit_for_review: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      # @overload create(auto_create_for_sp: nil, category: nil, creation_source: nil, definition: nil, language: nil, sandbox: nil, submit_for_review: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      #
+      # @param auto_create_for_sp [Boolean] Body param: Create this template automatically on every sender profile of the or
       #
       # @param category [String, nil] Body param: Template category: MARKETING, UTILITY, AUTHENTICATION (optional, aut
       #

data/lib/sentdm/resources/webhooks.rb

@@ -19,7 +19,7 @@ module Sentdm
       #
       # Creates a new webhook endpoint for the authenticated customer.
       #
-      # @overload create(display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, retry_count: nil, sandbox: nil, timeout_seconds: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      # @overload create(display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, retry_count: nil, sandbox: nil, sender_profile: nil, timeout_seconds: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
       # @param display_name [String] Body param
       #
@@ -33,6 +33,8 @@ module Sentdm
       #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
+      # @param sender_profile [Sentdm::Models::WebhookCreateParams::SenderProfile, nil] Body param: Request-only: the events an organization webhook's sender profile cl
+      #
       # @param timeout_seconds [Integer] Body param
       #
       # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
@@ -89,7 +91,7 @@ module Sentdm
       #
       # Updates an existing webhook for the authenticated customer.
       #
-      # @overload update(id, display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, retry_count: nil, sandbox: nil, timeout_seconds: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      # @overload update(id, display_name: nil, endpoint_url: nil, event_filters: nil, event_types: nil, retry_count: nil, sandbox: nil, sender_profile: nil, timeout_seconds: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
       # @param id [String] Path param
       #
@@ -105,6 +107,8 @@ module Sentdm
       #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
+      # @param sender_profile [Sentdm::Models::WebhookUpdateParams::SenderProfile, nil] Body param: Request-only: the events an organization webhook's sender profile cl
+      #
       # @param timeout_seconds [Integer] Body param
       #
       # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
@@ -221,7 +225,9 @@ module Sentdm
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::WebhookListEventsParams} for more details.
       #
-      # Retrieves a paginated list of delivery events for the specified webhook.
+      # Retrieves a paginated list of delivery events for the specified webhook. If the
+      # webhook is cloned onto your sender profiles, the list includes what those clones
+      # received; read payload.account_id to tell whose event it is.
       #
       # @overload list_events(id, page: nil, page_size: nil, search: nil, x_profile_id: nil, request_options: {})
       #

data/lib/sentdm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sentdm
-  VERSION = "0.32.0"
+  VERSION = "0.34.0"
 end

data/lib/sentdm.rb

@@ -58,6 +58,7 @@ require_relative "sentdm/internal/templates_page"
 require_relative "sentdm/internal/webhook_events_page"
 require_relative "sentdm/internal/webhooks_page"
 require_relative "sentdm/models/mutation_request"
+require_relative "sentdm/models/template_body_content"
 require_relative "sentdm/models/api_meta"
 require_relative "sentdm/models/api_response_of_contact"
 require_relative "sentdm/models/api_response_of_contact_message_summary"
@@ -130,7 +131,6 @@ require_relative "sentdm/models/tcr_brand_relationship"
 require_relative "sentdm/models/tcr_vertical"
 require_relative "sentdm/models/template"
 require_relative "sentdm/models/template_body"
-require_relative "sentdm/models/template_body_content"
 require_relative "sentdm/models/template_button"
 require_relative "sentdm/models/template_button_props"
 require_relative "sentdm/models/template_create_params"

data/rbi/sentdm/client.rbi

@@ -78,6 +78,12 @@ module Sentdm
     # **A message needs a sender.** What you can send, where, and at what cost is
     # decided by the markets under **Channels** — so a recipient in a country you hold
     # no sender for is refused here rather than queued.
+    #
+    # **A message can be resent on its id.** `POST /v3/messages/{id}/resend` puts a
+    # finished message — typically one BLOCKED for insufficient balance — back through
+    # the send pipeline. It is a new attempt, not a free retry: every policy runs
+    # again, the message is billed again, and its status webhooks fire again. A
+    # FILTERED message is never resendable.
     sig { returns(Sentdm::Resources::Messages) }
     attr_reader :messages
 

data/rbi/sentdm/models/channel_event_payload.rbi

@@ -18,7 +18,9 @@ module Sentdm
       # The account whose market this is, named as on every other family. When an
       # organization receives an event for one of its sender profiles this is the
       # profile, so a reseller compares it with its own id and anything different is one
-      # of its profiles.
+      # of its profiles. Matches customer_id on GET /v3/channels and the sender
+      # profile's id. Together with channel, country, and number_type, it identifies the
+      # market.
       sig { returns(T.nilable(String)) }
       attr_reader :account_id
 
@@ -34,18 +36,51 @@ module Sentdm
       sig { params(channel: String).void }
       attr_writer :channel
 
+      # What a market has been given: the identity it registers under, its programme,
+      # and any documents attached.
+      #
+      # What it does not carry is what the market asks for. That is the subject of GET
+      # /v3/compliance/requirements, and it is the same answer for every caller — a
+      # description of what a compliance regime wants, not a record of one customer's
+      # progress through it. It was reported here as well for a while, which put the
+      # same array in six response shapes and left a caller deciding which of two
+      # sources to believe.
+      #
+      # Present on a list read for markets that register (carrying brand and campaign),
+      # but with documents absent — documents are not fetched for a list, because a
+      # catalog lookup and a document read per market would multiply across a page.
+      # Absent documents is distinct from an empty list: absent says they were not
+      # fetched; empty says the market has been given none. The parent object is null
+      # only when the market registers with nobody and compliance was not computed —
+      # nothing to show at all.
+      sig { returns(T.nilable(Sentdm::ChannelEventPayload::Compliance)) }
+      attr_reader :compliance
+
+      sig do
+        params(
+          compliance: T.nilable(Sentdm::ChannelEventPayload::Compliance::OrHash)
+        ).void
+      end
+      attr_writer :compliance
+
       # The kind of sender the market uses, for example TEN_DLC, LOCAL, or ALPHANUMERIC.
       # Omitted when the subject has no sender type of its own.
       sig { returns(T.nilable(String)) }
       attr_accessor :number_type
 
-      # Why the market reached this state, when a reason was given — a correction
-      # explained, or a campaign lapse. Free text, passed through from the registry or
-      # carrier that wrote it, so treat it as a message to show a human rather than a
-      # value to branch on.
+      # Why the market reached this state, as a sentence to show a person: the specific
+      # explanation when one was given (a correction explained, a campaign lapse),
+      # otherwise what reason_code means for this market. Not a value to branch on.
       sig { returns(T.nilable(String)) }
       attr_accessor :reason
 
+      # Why the market is not ACTIVE, as a stable code: an ErrorCodes CHANNEL_xxx value
+      # such as CHANNEL_001 (something you owe) or CHANNEL_002 (a correction was
+      # requested). The same code the channels resource reports for the market. Switch
+      # on this rather than on reason. Omitted while ACTIVE.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :reason_code
+
       # The sender itself — a number in E.164, or an alphanumeric sender ID.
       #
       # Always present, and null until a sender exists. The key is on every delivery so
@@ -109,8 +144,11 @@ module Sentdm
           country: String,
           account_id: String,
           channel: String,
+          compliance:
+            T.nilable(Sentdm::ChannelEventPayload::Compliance::OrHash),
           number_type: T.nilable(String),
           reason: T.nilable(String),
+          reason_code: T.nilable(String),
           sender_value: T.nilable(String),
           status: String,
           updated_at: String
@@ -125,20 +163,44 @@ module Sentdm
         # The account whose market this is, named as on every other family. When an
         # organization receives an event for one of its sender profiles this is the
         # profile, so a reseller compares it with its own id and anything different is one
-        # of its profiles.
+        # of its profiles. Matches customer_id on GET /v3/channels and the sender
+        # profile's id. Together with channel, country, and number_type, it identifies the
+        # market.
         account_id: nil,
         # The channel this market belongs to: sms, whatsapp, or rcs. Never sent — that
         # value belongs to message events, where it names the smart-routing brand rather
         # than a channel that can be provisioned.
         channel: nil,
+        # What a market has been given: the identity it registers under, its programme,
+        # and any documents attached.
+        #
+        # What it does not carry is what the market asks for. That is the subject of GET
+        # /v3/compliance/requirements, and it is the same answer for every caller — a
+        # description of what a compliance regime wants, not a record of one customer's
+        # progress through it. It was reported here as well for a while, which put the
+        # same array in six response shapes and left a caller deciding which of two
+        # sources to believe.
+        #
+        # Present on a list read for markets that register (carrying brand and campaign),
+        # but with documents absent — documents are not fetched for a list, because a
+        # catalog lookup and a document read per market would multiply across a page.
+        # Absent documents is distinct from an empty list: absent says they were not
+        # fetched; empty says the market has been given none. The parent object is null
+        # only when the market registers with nobody and compliance was not computed —
+        # nothing to show at all.
+        compliance: nil,
         # The kind of sender the market uses, for example TEN_DLC, LOCAL, or ALPHANUMERIC.
         # Omitted when the subject has no sender type of its own.
         number_type: nil,
-        # Why the market reached this state, when a reason was given — a correction
-        # explained, or a campaign lapse. Free text, passed through from the registry or
-        # carrier that wrote it, so treat it as a message to show a human rather than a
-        # value to branch on.
+        # Why the market reached this state, as a sentence to show a person: the specific
+        # explanation when one was given (a correction explained, a campaign lapse),
+        # otherwise what reason_code means for this market. Not a value to branch on.
         reason: nil,
+        # Why the market is not ACTIVE, as a stable code: an ErrorCodes CHANNEL_xxx value
+        # such as CHANNEL_001 (something you owe) or CHANNEL_002 (a correction was
+        # requested). The same code the channels resource reports for the market. Switch
+        # on this rather than on reason. Omitted while ACTIVE.
+        reason_code: nil,
         # The sender itself — a number in E.164, or an alphanumeric sender ID.
         #
         # Always present, and null until a sender exists. The key is on every delivery so
@@ -174,8 +236,10 @@ module Sentdm
             country: String,
             account_id: String,
             channel: String,
+            compliance: T.nilable(Sentdm::ChannelEventPayload::Compliance),
             number_type: T.nilable(String),
             reason: T.nilable(String),
+            reason_code: T.nilable(String),
             sender_value: T.nilable(String),
             status: String,
             updated_at: String
@@ -184,6 +248,205 @@ module Sentdm
       end
       def to_hash
       end
+
+      class Compliance < Sentdm::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Sentdm::ChannelEventPayload::Compliance,
+              Sentdm::Internal::AnyHash
+            )
+          end
+
+        # The identity this market registers under, with inherit saying whose it is.
+        #
+        # Reported here rather than on the profile because it belongs to the registration
+        # this market files, and only one market files one. It was a top-level block for a
+        # while, which put a per-registration value beside a list of markets and left a
+        # caller to work out which market it belonged to.
+        #
+        # Absent for a market that registers with nobody — such a market asks for no
+        # identity, so there is none to report. Absent and null mean different things:
+        # absent says this market does not ask, null would say it asks and nothing was
+        # supplied.
+        #
+        # Untyped, like the request side, because its members are declared by the market's
+        # own schema rather than by a C# class. A typed pair here would be a second
+        # definition of what a market wants, free to drift from the one that validates.
+        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+        attr_accessor :brand
+
+        # The programme this market registers, with inherit saying whose it is.
+        #
+        # One, not a list. TcrCampaigns permits several and an account built on the admin
+        # side may hold them, but this surface offers one — which is what lets the
+        # market's PATCH be an upsert rather than a collection with an addressable create
+        # behind it. An account holding several is reported as its first and refused on
+        # write, rather than half-edited.
+        #
+        # Carries no id. Nothing addresses a campaign, and an undeclared key would be
+        # refused if the caller sent this object back — which it is meant to be able to
+        # do.
+        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+        attr_accessor :campaign
+
+        # What has been supplied for this market.
+        #
+        # Files, not values — the declared halves above carry the values. A document
+        # cannot be a JSON value, so it is sent as multipart on the channel call and
+        # reported here as a reference.
+        #
+        # Absent on a list read, which fetches identity but does not compute compliance
+        # documents per market. Absent and empty mean different things: absent says the
+        # documents were not fetched; empty says the market has been given none.
+        sig do
+          returns(
+            T.nilable(
+              T::Array[Sentdm::ChannelEventPayload::Compliance::Document]
+            )
+          )
+        end
+        attr_accessor :documents
+
+        # What a market has been given: the identity it registers under, its programme,
+        # and any documents attached.
+        #
+        # What it does not carry is what the market asks for. That is the subject of GET
+        # /v3/compliance/requirements, and it is the same answer for every caller — a
+        # description of what a compliance regime wants, not a record of one customer's
+        # progress through it. It was reported here as well for a while, which put the
+        # same array in six response shapes and left a caller deciding which of two
+        # sources to believe.
+        #
+        # Present on a list read for markets that register (carrying brand and campaign),
+        # but with documents absent — documents are not fetched for a list, because a
+        # catalog lookup and a document read per market would multiply across a page.
+        # Absent documents is distinct from an empty list: absent says they were not
+        # fetched; empty says the market has been given none. The parent object is null
+        # only when the market registers with nobody and compliance was not computed —
+        # nothing to show at all.
+        sig do
+          params(
+            brand: T.nilable(T::Hash[Symbol, T.anything]),
+            campaign: T.nilable(T::Hash[Symbol, T.anything]),
+            documents:
+              T.nilable(
+                T::Array[
+                  Sentdm::ChannelEventPayload::Compliance::Document::OrHash
+                ]
+              )
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The identity this market registers under, with inherit saying whose it is.
+          #
+          # Reported here rather than on the profile because it belongs to the registration
+          # this market files, and only one market files one. It was a top-level block for a
+          # while, which put a per-registration value beside a list of markets and left a
+          # caller to work out which market it belonged to.
+          #
+          # Absent for a market that registers with nobody — such a market asks for no
+          # identity, so there is none to report. Absent and null mean different things:
+          # absent says this market does not ask, null would say it asks and nothing was
+          # supplied.
+          #
+          # Untyped, like the request side, because its members are declared by the market's
+          # own schema rather than by a C# class. A typed pair here would be a second
+          # definition of what a market wants, free to drift from the one that validates.
+          brand: nil,
+          # The programme this market registers, with inherit saying whose it is.
+          #
+          # One, not a list. TcrCampaigns permits several and an account built on the admin
+          # side may hold them, but this surface offers one — which is what lets the
+          # market's PATCH be an upsert rather than a collection with an addressable create
+          # behind it. An account holding several is reported as its first and refused on
+          # write, rather than half-edited.
+          #
+          # Carries no id. Nothing addresses a campaign, and an undeclared key would be
+          # refused if the caller sent this object back — which it is meant to be able to
+          # do.
+          campaign: nil,
+          # What has been supplied for this market.
+          #
+          # Files, not values — the declared halves above carry the values. A document
+          # cannot be a JSON value, so it is sent as multipart on the channel call and
+          # reported here as a reference.
+          #
+          # Absent on a list read, which fetches identity but does not compute compliance
+          # documents per market. Absent and empty mean different things: absent says the
+          # documents were not fetched; empty says the market has been given none.
+          documents: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              brand: T.nilable(T::Hash[Symbol, T.anything]),
+              campaign: T.nilable(T::Hash[Symbol, T.anything]),
+              documents:
+                T.nilable(
+                  T::Array[Sentdm::ChannelEventPayload::Compliance::Document]
+                )
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Document < Sentdm::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Sentdm::ChannelEventPayload::Compliance::Document,
+                Sentdm::Internal::AnyHash
+              )
+            end
+
+          # Identifier of the upload, for fetching it back through the documents endpoints.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :document_id
+
+          sig { returns(T.nilable(String)) }
+          attr_accessor :file_name
+
+          # The catalog's name for this document, matching the requirement it satisfies.
+          sig { returns(T.nilable(String)) }
+          attr_reader :key
+
+          sig { params(key: String).void }
+          attr_writer :key
+
+          # A document a market asked for and has been given.
+          sig do
+            params(
+              document_id: T.nilable(String),
+              file_name: T.nilable(String),
+              key: String
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Identifier of the upload, for fetching it back through the documents endpoints.
+            document_id: nil,
+            file_name: nil,
+            # The catalog's name for this document, matching the requirement it satisfies.
+            key: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                document_id: T.nilable(String),
+                file_name: T.nilable(String),
+                key: String
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+      end
     end
   end
 end

data/rbi/sentdm/models/contact_event.rbi

@@ -20,17 +20,25 @@ module Sentdm
       sig { params(field: String).void }
       attr_writer :field
 
-      # Body of a contact.opt_in, contact.opt_out or contact.help event. Delivered when
-      # a contact signals a consent change or asks for help.
+      # Body of a contact.opt_in, contact.opt_out, contact.help or
+      # contact.custom_keyword event. Delivered when a contact signals a consent change,
+      # asks for help, or sends one of your own auto-reply keywords.
       #
       # These events state the signal outright, so you do not have to recognise keywords
       # in the text of a message.received event. They also cover cases that produce no
       # inbound message at all, such as a network handling an opt-out on your behalf.
       #
-      # Fields are ordered identity → resulting state → provenance → join key. Nothing
-      # here restates the envelope: which of the three signals occurred is the
-      # envelope's event, and when it was emitted is its timestamp. Retries carry the
-      # same X-Webhook-Event-ID header, which is what to deduplicate on.
+      # Two of the four change consent and two do not: contact.help and
+      # contact.custom_keyword report the state the contact already had. Read opt_out
+      # for the state and the envelope's event for what happened, rather than inferring
+      # one from the other.
+      #
+      # Fields are ordered identity → resulting state → provenance → join keys. The two
+      # parties are from and to. Note that the message family has not moved to those
+      # names yet — message.received still calls the same two parties inbound_number and
+      # outbound_number. Nothing here restates the envelope: which signal occurred is
+      # the envelope's event, and when it was emitted is its timestamp. Retries carry
+      # the same X-Webhook-Event-ID header, which is what to deduplicate on.
       sig { returns(T.nilable(Sentdm::ContactEventPayload)) }
       attr_reader :payload
 
@@ -71,17 +79,25 @@ module Sentdm
         # The event family, for example message, templates or contact. Route on this
         # first, then on event for the specific change.
         field: nil,
-        # Body of a contact.opt_in, contact.opt_out or contact.help event. Delivered when
-        # a contact signals a consent change or asks for help.
+        # Body of a contact.opt_in, contact.opt_out, contact.help or
+        # contact.custom_keyword event. Delivered when a contact signals a consent change,
+        # asks for help, or sends one of your own auto-reply keywords.
         #
         # These events state the signal outright, so you do not have to recognise keywords
         # in the text of a message.received event. They also cover cases that produce no
         # inbound message at all, such as a network handling an opt-out on your behalf.
         #
-        # Fields are ordered identity → resulting state → provenance → join key. Nothing
-        # here restates the envelope: which of the three signals occurred is the
-        # envelope's event, and when it was emitted is its timestamp. Retries carry the
-        # same X-Webhook-Event-ID header, which is what to deduplicate on.
+        # Two of the four change consent and two do not: contact.help and
+        # contact.custom_keyword report the state the contact already had. Read opt_out
+        # for the state and the envelope's event for what happened, rather than inferring
+        # one from the other.
+        #
+        # Fields are ordered identity → resulting state → provenance → join keys. The two
+        # parties are from and to. Note that the message family has not moved to those
+        # names yet — message.received still calls the same two parties inbound_number and
+        # outbound_number. Nothing here restates the envelope: which signal occurred is
+        # the envelope's event, and when it was emitted is its timestamp. Retries carry
+        # the same X-Webhook-Event-ID header, which is what to deduplicate on.
         payload: nil,
         # The event-specific body.
         request_id: nil,