sentdm 0.31.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc53282fa9d44937f4eca7cd2519066c9230dd80c07e757976aaf19ed84bc4cd
-  data.tar.gz: ae37ec96f9bbd5415b93931e5f5b45f86bf2cfd9aa5496c3e48a4e4cf55c601c
+  metadata.gz: 88e9bb540faf8a7261b5e38bb2b040df80d8f02124ae52f313d7d0019fe84042
+  data.tar.gz: 52b07edc509cd9c60d586cffede3b951ba9e8f8de1b34776c1b9d86655dd2dfc
 SHA512:
-  metadata.gz: ad4d72570b0f014b5c0ae8ed154c6eda9cbf18fe6b765bd2159ac2468474c85dfba17e0d662f38c987ea0330eceb7e77d33137ebbb7df2591c65bae1f5415342
-  data.tar.gz: 6c941c5ce504b94a154865c6d1fa3ddcfcf90f58889e0514c0f74c89c324eb0c3312b55cd8ad4f5a32274b8ac28e8d65805496be73ad757621fd1a5a19e30c2e
+  metadata.gz: 83049b88e719812408bf187ebb7d8723c45368fc89ff7d21dce6cdd2cdd2c74f892da306081d5b9af50df59668a69160b91a11bd6796d978560738bbfd3a0fc5
+  data.tar.gz: 95eb98fb732c34e1ce224cfdfec45193477bd8aae18e5daf6d5da3bee50a3018c712304da29fbf146b2f92c330d512d617a82fbeb77dd4f1a25f4752c2566929

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [0.33.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.32.0...v0.33.0) (2026-09-30)
+
+
+### Features
+
+* **api:** sync generated SDKs from the committed spec ([c68607e](https://github.com/sentdm/sent-dm-ruby/commit/c68607ed78d4a03f1c3c03d36440985cd5eedceb))
+* **api:** sync OpenAPI spec from production ([ceb47d9](https://github.com/sentdm/sent-dm-ruby/commit/ceb47d9ddc2d46144e5f81b0ef4bc7693b1f435f))
+* **api:** sync OpenAPI spec from production ([8c92eb5](https://github.com/sentdm/sent-dm-ruby/commit/8c92eb52bff195424d14d09eff8f131edc640918))
+
+## [0.32.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.31.0...v0.32.0) (2026-09-18)
+
+
+### Features
+
+* **api:** sync OpenAPI spec from production ([d1e2524](https://github.com/sentdm/sent-dm-ruby/commit/d1e2524bd0002641b5466b2eaf1ba189c9d80acf))
+
 ## [0.31.0](https://github.com/sentdm/sent-dm-ruby/compare/v0.30.0...v0.31.0) (2026-09-10)
 
 

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "sentdm", "~> 0.31.0"
+gem "sentdm", "~> 0.33.0"
 ```
 
 <!-- x-release-please-end -->

data/lib/sentdm/client.rb

@@ -83,6 +83,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.
     # @return [Sentdm::Resources::Messages]
     attr_reader :messages
 

data/lib/sentdm/models/channel_event.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Models
+    class ChannelEvent < Sentdm::Internal::Type::BaseModel
+      # @!attribute event
+      #   The specific event within the family, for example message.delivered,
+      #   message.received or contact.opt_out. Absent on events that have no subtype, so
+      #   treat it as optional.
+      #
+      #   @return [String, nil]
+      optional :event, String, nil?: true
+
+      # @!attribute field
+      #   The event family, for example message, templates or contact. Route on this
+      #   first, then on event for the specific change.
+      #
+      #   @return [String, nil]
+      optional :field, String
+
+      # @!attribute payload
+      #   Body of a channel event: where one of the customer's channels stands in
+      #   provisioning and compliance. Delivered when a milestone moves — a registration
+      #   filed, a verdict returned, a resubmission asked for, a sender gone live — so a
+      #   customer's own onboarding UI does not have to poll GET /v3/channels.
+      #
+      #   The subject is one item, never the account. A customer's "SMS channel" has no
+      #   status; a market does. Country, NumberType and SenderValue name which one, so a
+      #   customer terminating only to Kosovo never receives an event about US 10DLC.
+      #
+      #   Status is the stable half of the contract. It is the same four-value set GET
+      #   /v3/channels publishes, computed through the same code, so an event and a read
+      #   of the same market cannot disagree. A subscriber that reads nothing but the
+      #   status and the subject fields is a correct subscriber. The sub-type on the
+      #   envelope names the specific milestone and is additive — that vocabulary comes
+      #   from registries and carriers, which are parties Sent does not control.
+      #
+      #   Status means provisioning and compliance are complete, not that a send will
+      #   succeed right now. An account can be suspended, or a destination blocked by a
+      #   routing rule, without either showing up here. Those are separate surfaces and
+      #   deliberately not modelled on this payload.
+      #
+      #   @return [Sentdm::Models::ChannelEventPayload, nil]
+      optional :payload, -> { Sentdm::ChannelEventPayload }, nil?: true
+
+      # @!attribute request_id
+      #   The event-specific body.
+      #
+      #   @return [String, nil]
+      optional :request_id, String, nil?: true
+
+      # @!attribute timestamp
+      #   When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+      #   time, not the time the underlying change happened. Use the timestamp inside the
+      #   payload for the latter.
+      #
+      #   @return [String, nil]
+      optional :timestamp, String
+
+      # @!method initialize(event: nil, field: nil, payload: nil, request_id: nil, timestamp: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Sentdm::Models::ChannelEvent} for more details.
+      #
+      #   The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+      #   this shape and varies only in Payload.
+      #
+      #   @param event [String, nil] The specific event within the family, for example message.delivered,
+      #
+      #   @param field [String] The event family, for example message, templates or contact. Route on
+      #
+      #   @param payload [Sentdm::Models::ChannelEventPayload, nil] Body of a channel event: where one of the customer's channels stands in provisio
+      #
+      #   @param request_id [String, nil] The event-specific body.
+      #
+      #   @param timestamp [String] When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+    end
+  end
+end

data/lib/sentdm/models/channel_event_payload.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Models
+    class ChannelEventPayload < Sentdm::Internal::Type::BaseModel
+      # @!attribute country
+      #   The market's destination country as an ISO 3166-1 alpha-2 code, for example XK.
+      #   Always present, and the property that identifies this payload among the
+      #   delivered envelopes — see DeliveredWebhookEvents. Every event in this family
+      #   reports one market, and a market has a country.
+      #
+      #   @return [String]
+      required :country, String
+
+      # @!attribute account_id
+      #   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. Matches customer_id on GET /v3/channels and the sender
+      #   profile's id. Together with channel, country, and number_type, it identifies the
+      #   market.
+      #
+      #   @return [String, nil]
+      optional :account_id, String
+
+      # @!attribute channel
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :channel, String
+
+      # @!attribute compliance
+      #   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.
+      #
+      #   @return [Sentdm::Models::ChannelEventPayload::Compliance, nil]
+      optional :compliance, -> { Sentdm::ChannelEventPayload::Compliance }, nil?: true
+
+      # @!attribute number_type
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :number_type, String, nil?: true
+
+      # @!attribute reason
+      #   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.
+      #
+      #   @return [String, nil]
+      optional :reason, String, nil?: true
+
+      # @!attribute sender_value
+      #   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
+      #   a subscriber reads one shape rather than branching on whether the field arrived
+      #   — the same choice template_id makes on the message payload.
+      #
+      #   It can carry a value at any point in the lifecycle, not only once the market is
+      #   live: a number ordered and not yet active at the carrier is already known during
+      #   PROVISIONING, and an alphanumeric sender the customer chose themselves is known
+      #   before anything is filed. It is null while the market is still waiting on a
+      #   number, which for a US 10DLC registration is every event up to
+      #   channel.activated.
+      #
+      #   @return [String, nil]
+      optional :sender_value, String, nil?: true
+
+      # @!attribute status
+      #   Where the market stands: PENDING_REVIEW, ACTION_NEEDED, PROVISIONING, ACTIVE or
+      #   INACTIVE. PENDING_REVIEW means a registry or a carrier holds it and the wait is
+      #   theirs; ACTION_NEEDED means it is yours; PROVISIONING means the verdict is in
+      #   and Sent is acquiring the sender; INACTIVE means it had a working sender and no
+      #   longer does.
+      #
+      #   Each event name is the transition into one of these, but the two are separate
+      #   fields and may legitimately differ. A resubmission filed against a market whose
+      #   sender is already live is channel.submitted carrying ACTIVE: a correction is
+      #   with the registry and the sender keeps working. Read both.
+      #
+      #   @return [String, nil]
+      optional :status, String
+
+      # @!attribute updated_at
+      #   When the transition happened, in UTC (yyyy-MM-ddTHH:mm:ssZ).
+      #
+      #   @return [String, nil]
+      optional :updated_at, String
+
+      # @!method initialize(country:, account_id: nil, channel: nil, compliance: nil, number_type: nil, reason: nil, sender_value: nil, status: nil, updated_at: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Sentdm::Models::ChannelEventPayload} for more details.
+      #
+      #   Body of a channel event: where one of the customer's channels stands in
+      #   provisioning and compliance. Delivered when a milestone moves — a registration
+      #   filed, a verdict returned, a resubmission asked for, a sender gone live — so a
+      #   customer's own onboarding UI does not have to poll GET /v3/channels.
+      #
+      #   The subject is one item, never the account. A customer's "SMS channel" has no
+      #   status; a market does. Country, NumberType and SenderValue name which one, so a
+      #   customer terminating only to Kosovo never receives an event about US 10DLC.
+      #
+      #   Status is the stable half of the contract. It is the same four-value set GET
+      #   /v3/channels publishes, computed through the same code, so an event and a read
+      #   of the same market cannot disagree. A subscriber that reads nothing but the
+      #   status and the subject fields is a correct subscriber. The sub-type on the
+      #   envelope names the specific milestone and is additive — that vocabulary comes
+      #   from registries and carriers, which are parties Sent does not control.
+      #
+      #   Status means provisioning and compliance are complete, not that a send will
+      #   succeed right now. An account can be suspended, or a destination blocked by a
+      #   routing rule, without either showing up here. Those are separate surfaces and
+      #   deliberately not modelled on this payload.
+      #
+      #   @param country [String] The market's destination country as an ISO 3166-1 alpha-2 code, for example XK.
+      #
+      #   @param account_id [String] The account whose market this is, named as on every other family. When an organi
+      #
+      #   @param channel [String] The channel this market belongs to: sms, whatsapp, or rcs. Never
+      #
+      #   @param compliance [Sentdm::Models::ChannelEventPayload::Compliance, nil] What a market has been given: the identity it registers under, its programme, an
+      #
+      #   @param number_type [String, nil] The kind of sender the market uses, for example TEN_DLC, LOCAL, or
+      #
+      #   @param reason [String, nil] Why the market reached this state, when a reason was given — a correction explai
+      #
+      #   @param sender_value [String, nil] The sender itself — a number in E.164, or an alphanumeric sender ID.
+      #
+      #   @param status [String] Where the market stands: PENDING_REVIEW, ACTION_NEEDED, PROVISIONING,
+      #
+      #   @param updated_at [String] When the transition happened, in UTC (yyyy-MM-ddTHH:mm:ssZ).
+
+      # @see Sentdm::Models::ChannelEventPayload#compliance
+      class Compliance < Sentdm::Internal::Type::BaseModel
+        # @!attribute brand
+        #   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.
+        #
+        #   @return [Hash{Symbol=>Object}, nil]
+        optional :brand, Sentdm::Internal::Type::HashOf[Sentdm::Internal::Type::Unknown], nil?: true
+
+        # @!attribute campaign
+        #   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.
+        #
+        #   @return [Hash{Symbol=>Object}, nil]
+        optional :campaign, Sentdm::Internal::Type::HashOf[Sentdm::Internal::Type::Unknown], nil?: true
+
+        # @!attribute documents
+        #   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.
+        #
+        #   @return [Array<Sentdm::Models::ChannelEventPayload::Compliance::Document>, nil]
+        optional :documents,
+                 -> { Sentdm::Internal::Type::ArrayOf[Sentdm::ChannelEventPayload::Compliance::Document] },
+                 nil?: true
+
+        # @!method initialize(brand: nil, campaign: nil, documents: nil)
+        #   Some parameter documentations has been truncated, see
+        #   {Sentdm::Models::ChannelEventPayload::Compliance} for more details.
+        #
+        #   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.
+        #
+        #   @param brand [Hash{Symbol=>Object}, nil] The identity this market registers under, with inherit saying whose it is.
+        #
+        #   @param campaign [Hash{Symbol=>Object}, nil] The programme this market registers, with inherit saying whose it is.
+        #
+        #   @param documents [Array<Sentdm::Models::ChannelEventPayload::Compliance::Document>, nil] What has been supplied for this market.
+
+        class Document < Sentdm::Internal::Type::BaseModel
+          # @!attribute document_id
+          #   Identifier of the upload, for fetching it back through the documents endpoints.
+          #
+          #   @return [String, nil]
+          optional :document_id, String, nil?: true
+
+          # @!attribute file_name
+          #
+          #   @return [String, nil]
+          optional :file_name, String, nil?: true
+
+          # @!attribute key
+          #   The catalog's name for this document, matching the requirement it satisfies.
+          #
+          #   @return [String, nil]
+          optional :key, String
+
+          # @!method initialize(document_id: nil, file_name: nil, key: nil)
+          #   A document a market asked for and has been given.
+          #
+          #   @param document_id [String, nil] Identifier of the upload, for fetching it back through the documents endpoints.
+          #
+          #   @param file_name [String, nil]
+          #
+          #   @param key [String] The catalog's name for this document, matching the requirement it satisfies.
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/models/contact_event.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Models
+    class ContactEvent < Sentdm::Internal::Type::BaseModel
+      # @!attribute event
+      #   The specific event within the family, for example message.delivered,
+      #   message.received or contact.opt_out. Absent on events that have no subtype, so
+      #   treat it as optional.
+      #
+      #   @return [String, nil]
+      optional :event, String, nil?: true
+
+      # @!attribute field
+      #   The event family, for example message, templates or contact. Route on this
+      #   first, then on event for the specific change.
+      #
+      #   @return [String, nil]
+      optional :field, String
+
+      # @!attribute payload
+      #   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.
+      #
+      #   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.
+      #
+      #   @return [Sentdm::Models::ContactEventPayload, nil]
+      optional :payload, -> { Sentdm::ContactEventPayload }, nil?: true
+
+      # @!attribute request_id
+      #   The event-specific body.
+      #
+      #   @return [String, nil]
+      optional :request_id, String, nil?: true
+
+      # @!attribute timestamp
+      #   When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+      #   time, not the time the underlying change happened. Use the timestamp inside the
+      #   payload for the latter.
+      #
+      #   @return [String, nil]
+      optional :timestamp, String
+
+      # @!method initialize(event: nil, field: nil, payload: nil, request_id: nil, timestamp: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Sentdm::Models::ContactEvent} for more details.
+      #
+      #   The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+      #   this shape and varies only in Payload.
+      #
+      #   @param event [String, nil] The specific event within the family, for example message.delivered,
+      #
+      #   @param field [String] The event family, for example message, templates or contact. Route on
+      #
+      #   @param payload [Sentdm::Models::ContactEventPayload, nil] Body of a contact.opt_in, contact.opt_out, contact.help or
+      #
+      #   @param request_id [String, nil] The event-specific body.
+      #
+      #   @param timestamp [String] When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+    end
+  end
+end

data/lib/sentdm/models/contact_event_payload.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Models
+    class ContactEventPayload < Sentdm::Internal::Type::BaseModel
+      # @!attribute opt_out
+      #   Whether the contact is opted out after this signal — the state to write to your
+      #   own record. Same meaning as opt_out on the contact resource. On contact.help and
+      #   contact.custom_keyword this reports the contact's existing state, which neither
+      #   changes.
+      #
+      #   Two signals from the same contact can arrive out of order, because each one is
+      #   queued on its own rather than against the contact. Compare the envelope's
+      #   timestamp before you overwrite a newer state with an older one. That timestamp
+      #   is second-precision, so treat two signals stamped in the same second as
+      #   unordered and read the contact resource to settle them.
+      #
+      #   @return [Boolean]
+      required :opt_out, Sentdm::Internal::Type::Boolean
+
+      # @!attribute source
+      #   How the signal reached us. INBOUND_KEYWORD means the contact sent a message
+      #   whose text matched one of the keywords; PROVIDER_SIGNAL means the network
+      #   reported it. A provider signal usually carries no message_id or text, so read
+      #   both for null rather than inferring them from this field.
+      #
+      #   @return [String]
+      required :source, String
+
+      # @!attribute account_id
+      #   The account the contact belongs to. Present so one endpoint can serve several
+      #   accounts.
+      #
+      #   @return [String, nil]
+      optional :account_id, String
+
+      # @!attribute agent_id
+      #   The RCS agent the signal reached, when it reached one.
+      #
+      #   Omitted entirely on channels that have no agent, rather than sent as null — an
+      #   SMS or WhatsApp payload does not carry this key at all. On RCS it is the
+      #   counterpart to To: a contact reaches an agent rather than a number, so exactly
+      #   one of the two is populated and never both. If you run more than one agent, this
+      #   is what tells you which of them the contact acted on.
+      #
+      #   @return [String, nil]
+      optional :agent_id, String, nil?: true
+
+      # @!attribute channel
+      #   The channel the signal arrived on, for example sms or whatsapp.
+      #
+      #   @return [String, nil]
+      optional :channel, String
+
+      # @!attribute contact_id
+      #   The contact who raised the signal. Always populated, including for contact.help
+      #   or contact.custom_keyword from a number you have not messaged before — the
+      #   contact is created if it does not exist yet, so this identifier is always
+      #   resolvable against the contacts API.
+      #
+      #   @return [String, nil]
+      optional :contact_id, String
+
+      # @!attribute from
+      #   The contact's number, in E.164 format with the leading + — who raised the
+      #   signal. The same party message.received publishes as inbound_number.
+      #
+      #   @return [String, nil]
+      optional :from, String
+
+      # @!attribute message_id
+      #   The inbound message that carried the signal, matching message_id on the
+      #   corresponding message.received event so the two can be joined.
+      #
+      #   Sent as null when the signal did not arrive as a message — for example when a
+      #   network processed an opt-out on your behalf — and also when the message belongs
+      #   to a different account than this event, which can happen on a shared WhatsApp
+      #   number. The field is always present, so read it and check for null rather than
+      #   checking whether the key exists.
+      #
+      #   @return [String, nil]
+      optional :message_id, String, nil?: true
+
+      # @!attribute template_id
+      #   The auto-reply template whose keyword the contact matched, joinable against the
+      #   templates API.
+      #
+      #   This is what identifies which signal arrived on contact.custom_keyword: every
+      #   custom template reports the same event name, so the event alone cannot tell your
+      #   booking keyword from your opening-hours one. One template holds as many keywords
+      #   as you configured, so this is steadier to switch on than text.
+      #
+      #   Populated on the compliance sub-types too, where it names the template that
+      #   replied. Sent as null when no template was involved — a network-reported opt-out
+      #   matches no keyword. The field is always present, so read it and check for null.
+      #
+      #   @return [String, nil]
+      optional :template_id, String, nil?: true
+
+      # @!attribute text
+      #   The text the contact sent, for example STOP or UNSUBSCRIBE. Sent as null when
+      #   the signal did not arrive as text. The field is always present, so read it and
+      #   check for null rather than checking whether the key exists.
+      #
+      #   @return [String, nil]
+      optional :text, String, nil?: true
+
+      # @!attribute to
+      #   The number of yours that received the signal, in E.164 format with the leading
+      #   +. Tells a multi-number account which of its senders the contact acted on, which
+      #   nothing else on this payload answers.
+      #
+      #   This is your number, not the contact's. That is the opposite of what to means on
+      #   POST /v3/messages, where it is the list of recipients you are sending to. Reply
+      #   to From, not to this field, or the message goes back to yourself.
+      #
+      #   Sent as null when the signal did not arrive at a number of yours — an RCS signal
+      #   terminates at an agent rather than a number, and a provider-reported opt-out may
+      #   name no receiving number at all. The field is always present, so read it and
+      #   check for null rather than checking whether the key exists.
+      #
+      #   @return [String, nil]
+      optional :to, String, nil?: true
+
+      # @!method initialize(opt_out:, source:, account_id: nil, agent_id: nil, channel: nil, contact_id: nil, from: nil, message_id: nil, template_id: nil, text: nil, to: nil)
+      #   Some parameter documentations has been truncated, see
+      #   {Sentdm::Models::ContactEventPayload} for more details.
+      #
+      #   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.
+      #
+      #   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.
+      #
+      #   @param opt_out [Boolean] Whether the contact is opted out after this signal — the state to write to your
+      #
+      #   @param source [String] How the signal reached us. INBOUND_KEYWORD means the contact sent a message whos
+      #
+      #   @param account_id [String] The account the contact belongs to. Present so one endpoint can serve several ac
+      #
+      #   @param agent_id [String, nil] The RCS agent the signal reached, when it reached one.
+      #
+      #   @param channel [String] The channel the signal arrived on, for example sms or whatsapp.
+      #
+      #   @param contact_id [String] The contact who raised the signal. Always populated, including for contact.help
+      #
+      #   @param from [String] The contact's number, in E.164 format with the leading + — who raised the signal
+      #
+      #   @param message_id [String, nil] The inbound message that carried the signal, matching message_id on the
+      #
+      #   @param template_id [String, nil] The auto-reply template whose keyword the contact matched, joinable against the
+      #
+      #   @param text [String, nil] The text the contact sent, for example STOP or UNSUBSCRIBE. Sent as
+      #
+      #   @param to [String, nil] The number of yours that received the signal, in E.164 format with the leading +
+    end
+  end
+end