ruby-whatsapp 0.4.2 → 0.6.1

data/lib/ruby/whatsapp/business_phone_number/username/claim.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Claims a business username for a phone number, or moves one you already hold onto
+      # a different number of yours.
+      #
+      # A validated instance rather than a bare class method: Meta publishes the username
+      # format as a set of client-side rules, and the edge is rate limited, so a request
+      # that was never going to be accepted should not be spent. Named {Claim} rather than
+      # `Create`/`Update`/`Set` — posting again *replaces* the current username, `Update`
+      # would suggest the partial-update semantics of {Profile::Update}, and `Set` would
+      # shadow `::Set` inside this namespace.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Claim
+        include ActiveModel::Validations
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username"
+          MIN_LENGTH = 3
+          MAX_LENGTH = 35
+          CHARSET_PATTERN = /\A[a-z0-9._]+\z/
+          LETTER_PATTERN = /[a-z]/
+          RESERVED_PREFIX = "www"
+        end
+
+        # What happens when the username is already in use on another business phone
+        # number in the *same* portfolio.
+        module TransferActions
+          NONE = "none"
+          FORCE_TRANSFER = "force_transfer"
+
+          ALL = [NONE, FORCE_TRANSFER].freeze
+
+          # Normalizes caller input to Meta's documented casing, which is lowercase here —
+          # unlike this module's other enums. Unrecognized values are returned untouched so
+          # the inclusion validator can report them.
+          # @param value [String, Symbol, nil]
+          # @return [String, nil]
+          def self.normalize(value)
+            return if value.nil?
+
+            candidate = value.to_s.downcase
+            ALL.include?(candidate) ? candidate : value.to_s
+          end
+        end
+
+        # The domain-like endings Meta lists. **Its list is explicitly open-ended** ("and
+        # so on"), so this cannot be complete: a suffix outside it is rejected server-side
+        # with error `100` instead. Checked locally anyway, because catching the common
+        # cases without spending a rate-limited request is worth more than the false sense
+        # of completeness costs.
+        DOMAIN_SUFFIXES = %w[.com .org .net .int .edu .gov .mil .us .in .html].freeze
+
+        # @!attribute [rw] username
+        #   @return [String] The desired username, downcased.
+        attr_accessor :username
+
+        # @!attribute [rw] transfer_action
+        #   @return [String] One of {TransferActions::ALL}.
+        attr_accessor :transfer_action
+
+        validate :validate_username_format
+        validates :username, presence: true
+        # Length is nil-exempt so a missing username reports only "can't be blank" — the
+        # presence validator above is what must catch nil, and a shared `allow_nil` would
+        # have exempted it too.
+        validates :username, length: { minimum: Defaults::MIN_LENGTH, maximum: Defaults::MAX_LENGTH },
+          allow_nil: true
+        validates :transfer_action, inclusion: { in: TransferActions::ALL }
+
+        # @param username [String] The desired username. Meta compares usernames
+        #   case-insensitively, so a mixed-case value is downcased here rather than
+        #   rejected — `"JaspersMarket"` and `"jaspersmarket"` are the same name, and
+        #   refusing one Meta would have accepted is the failure mode this module avoids.
+        #   `.` and `_` *are* significant: `myid`, `my.id`, and `my_id` are three names.
+        # @param transfer_action [String, Symbol] `"none"` (the default) fails with error
+        #   `147005` if another of your numbers holds the name; `"force_transfer"` moves it.
+        # @raise [ActiveModel::ValidationError] if the username breaks a documented rule.
+        def initialize(username:, transfer_action: TransferActions::NONE)
+          @username = username&.to_s&.downcase
+          @transfer_action = TransferActions.normalize(transfer_action)
+
+          validate!
+        end
+
+        # @return [Hash] The claim payload. `transfer_action` is always sent rather than
+        #   compacted away when it is the default: it is a per-request behavior flag, not a
+        #   stored field, so convention 7's "nil means leave alone" does not apply — and
+        #   sending it explicitly pins the behavior if Meta ever changes its own default,
+        #   which matters for an operation whose other value takes a name off another number.
+        def serialize
+          { username:, transfer_action: }
+        end
+
+        class << self
+          # @example Move a username onto this number from another of yours
+          #   Claim.call(username: "jaspersmarket", transfer_action: :force_transfer)
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @param username [String] See {#initialize}.
+          # @param transfer_action [String, Symbol] See {#initialize}.
+          # @return [Details] Carrying `status` only; `username` is `nil`, since Meta
+          #   answers with the state rather than echoing the name back.
+          # @raise [ActiveModel::ValidationError] if the username breaks a documented rule.
+          # @raise [Error] if no phone number ID is configured, or the request fails. Error
+          #   `147005` means another of your numbers holds the name — retry with
+          #   `transfer_action: "force_transfer"`. `147001` means it is unavailable,
+          #   `147002` that the portfolio's messaging limit is too low, and
+          #   `147003`/`147004` that the number must first be linked to the Facebook Page
+          #   or Instagram account already using it.
+          def call(username:, client: Client.new, transfer_action: TransferActions::NONE)
+            body = new(username:, transfer_action:).serialize
+            response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+            Details.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "claim business username"))
+            )
+          end
+        end
+
+      private
+
+        # Meta's published format rules, minus the open-ended domain-suffix list, which is
+        # handled separately.
+        # @return [void]
+        def validate_username_format
+          return if username.nil? || username.empty?
+
+          validate_charset
+          validate_has_letter
+          validate_period_placement
+          validate_not_reserved_prefix
+          validate_no_domain_suffix
+        end
+
+        # @return [void]
+        def validate_charset
+          return if username.match?(Defaults::CHARSET_PATTERN)
+
+          errors.add(:username, "may only contain a-z, 0-9, periods and underscores")
+        end
+
+        # @return [void]
+        def validate_has_letter
+          return if username.match?(Defaults::LETTER_PATTERN)
+
+          errors.add(:username, "must contain at least one letter")
+        end
+
+        # @return [void]
+        def validate_period_placement
+          errors.add(:username, "must not start or end with a period") if
+            username.start_with?(".") || username.end_with?(".")
+          errors.add(:username, "must not contain two consecutive periods") if username.include?("..")
+        end
+
+        # Read as Meta writes it: a bare `www` prefix, so `wwwidgets` is rejected too. A
+        # local false rejection is cheap and reversible; a wasted request against a rate
+        # limited edge is not, and this way the error names the exact rule.
+        # @return [void]
+        def validate_not_reserved_prefix
+          return unless username.start_with?(Defaults::RESERVED_PREFIX)
+
+          errors.add(:username, "must not start with #{Defaults::RESERVED_PREFIX}")
+        end
+
+        # @return [void]
+        def validate_no_domain_suffix
+          suffix = DOMAIN_SUFFIXES.find { |candidate| username.end_with?(candidate) }
+          return if suffix.nil?
+
+          errors.add(:username, "must not end with a domain suffix such as #{suffix}")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username/delete.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Removes the business username from a phone number, releasing it.
+      #
+      # A bare class method with nothing to validate, like {Deregister} and {Profile::Get}:
+      # the phone number is the only input and {Transport} already guards it.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Delete
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username"
+        end
+
+        class << self
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @return [BusinessPhoneNumber::Response] Reused rather than a `Username::`-specific
+          #   class, since this endpoint answers the same bare `{success}` as
+          #   {Profile::Update} and {Account::Update}.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new)
+            response = client.connection.delete(edge_path(client, Defaults::EDGE))
+
+            BusinessPhoneNumber::Response.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "delete business username"))
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username/details.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # The username state returned by {Get} and {Claim}.
+      #
+      # One class for both, rather than a response per endpoint: `GET` answers
+      # `{username, status}` and `POST` answers `{status}` — a subset, not a different
+      # shape — so `username` simply tolerates being absent, the same way
+      # {BusinessPhoneNumber::Response#id} tolerates only ever being set by {VerifyCode}.
+      # `DELETE` is the one that genuinely differs, and it reuses
+      # {BusinessPhoneNumber::Response} because a bare `{success}` is what that class is for.
+      class Details
+        # The states Meta's own responses report. Raw strings, never validated on the way
+        # in, so a value added later still round-trips — the {Account::Details} convention.
+        #
+        # The `business_username_updates` webhook reports a third state, `"deleted"`,
+        # which no API response here can return; it is deliberately absent rather than
+        # listed in an enum the write side cannot produce.
+        module Statuses
+          APPROVED = "approved"
+          RESERVED = "reserved"
+
+          ALL = [APPROVED, RESERVED].freeze
+        end
+
+        # @!attribute [rw] username
+        #   @return [String, nil] The current username. Omitted by {Claim}, which answers
+        #     with a status only — you already hold the name you passed it — and by {Get}
+        #     when the number has no username at all.
+        attr_accessor :username
+
+        # @!attribute [rw] status
+        #   @return [String, nil] One of {Statuses::ALL}.
+        attr_accessor :status
+
+        def initialize(username: nil, status: nil)
+          @username = username
+          @status = status
+        end
+
+        # @return [Boolean] Whether the username is live and visible to WhatsApp users.
+        def approved?
+          status == Statuses::APPROVED
+        end
+
+        # @return [Boolean] Whether the username is held for this number but not yet
+        #   visible — it becomes visible when Meta makes the feature generally available.
+        def reserved?
+          status == Statuses::RESERVED
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Details]
+          def deserialize(response)
+            response ||= {}
+
+            new(username: response["username"], status: response["status"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username/get.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Reads the business username currently on a phone number, and its status.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Get
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username"
+        end
+
+        class << self
+          # @example Check whether the username is live yet
+          #   Get.call.approved?  # => false, while still `reserved`
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @return [Details] Whose `username` is `nil` if the number has none set.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new)
+            response = client.connection.get(edge_path(client, Defaults::EDGE))
+
+            Details.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "get business username"))
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username/suggest.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # Lists the usernames Meta has reserved for your business portfolio.
+      #
+      # Named for the verb, like {Register}/{Subscribe}, leaving the noun {Suggestions} to
+      # the value object it returns. The one action here addressing the
+      # `username_suggestions` edge rather than `username`.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Suggest
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "username_suggestions"
+        end
+
+        class << self
+          # @example Claim the first name Meta reserved for you
+          #   Username::Claim.call(username: Username::Suggest.call.first)
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @return [Suggestions] Enumerable over the reserved usernames; empty if none.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(client: Client.new)
+            response = client.connection.get(edge_path(client, Defaults::EDGE))
+
+            Suggestions.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "get username suggestions"))
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username/suggestions.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module Username
+      # The usernames Meta has reserved for your business portfolio, returned by {Suggest}.
+      #
+      # Owns the doubly-wrapped `{"data": [{"username_suggestions": [...]}]}` envelope so
+      # callers never reach through it — the same flatten-the-meaningless-wrapper habit as
+      # {Profile::Details}, {SubscribedApp::Response::App}, and
+      # {MessageTemplates::Response::Paging}. Unlike {Profile::Details}, which reads only
+      # `data[0]` because a phone number has exactly one profile, this flattens across
+      # *every* entry: Meta's example shows one, but nothing documents that as a limit, and
+      # `flat_map` is identical for one entry while degrading correctly for more.
+      class Suggestions
+        include Enumerable
+
+        # @!attribute [rw] suggestions
+        #   @return [Array<String>] Reserved usernames, which have a higher chance of
+        #     approval than one you invent. Empty when Meta has reserved none.
+        attr_accessor :suggestions
+
+        def initialize(suggestions: [])
+          @suggestions = suggestions
+        end
+
+        # @yieldparam suggestion [String]
+        # @return [Enumerator, self]
+        def each(&)
+          return suggestions.each unless block_given?
+
+          suggestions.each(&)
+          self
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Suggestions]
+          def deserialize(response)
+            response ||= {}
+
+            new(
+              suggestions: Array(response["data"]).flat_map { |entry| Array((entry || {})["username_suggestions"]) }
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/username.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Reads, claims, and deletes the **business username** on a phone number — the
+    # searchable `@name` a WhatsApp user can find you by, as opposed to the display name,
+    # which they cannot search for.
+    #
+    # Like {Profile}, and unlike {Account}, this is not an exception to the module's
+    # `phone_id` rule: Meta exposes both edges on the phone number itself
+    # (`GET`/`POST`/`DELETE /{phone_id}/username` and
+    # `GET /{phone_id}/username_suggestions`), so all four actions reuse
+    # {BusinessPhoneNumber::Transport} unchanged. It is the first sub-namespace here to
+    # address two edges, which is exactly why `edge_path` takes the edge as an argument.
+    #
+    # A username is 1:1 with a phone number across all of WhatsApp — no two numbers,
+    # consumer or business, can hold the same one. Adopting one does **not** hide your
+    # phone number in the app; it is a discovery feature, not a privacy one, which is the
+    # opposite of what a *user* username does. The asynchronous counterpart is the
+    # `business_username_updates` webhook (see `docs/webhooks/business_username_updates.md`),
+    # which is also the only place a `"deleted"` status ever appears.
+    # See `docs/business_phone_number/username.md`.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+    module Username
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number.rb

@@ -17,6 +17,15 @@ module Whatsapp
   # {Profile} reads and updates the public card a WhatsApp user sees before they reply.
   # It addresses `phone_id` like the onboarding actions above, so it shares their transport.
   #
+  # {Username} reads, claims, and deletes the searchable `@name` a WhatsApp user can find
+  # the number by — the business half of Meta's usernames rollout, whose user half is what
+  # makes {Whatsapp::Messages::Base#recipient} necessary. Two `phone_id` edges, one
+  # transport, still no exception.
+  #
+  # {ContactBook} deletes a stored user contact — the store Meta uses to keep putting a
+  # user's phone number in your webhooks after they adopt a username. Also a `phone_id`
+  # edge, though what it affects is scoped to the whole business portfolio.
+  #
   # {Account} is the one exception to the `phone_id` rule: it reads and updates the
   # WhatsApp Business Account a number belongs to, so it addresses `waba_id` and
   # carries its own transport.

data/lib/ruby/whatsapp/message_templates/button/request_contact_info.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class MessageTemplates
+    class Button
+      # Asks the recipient to share their phone number, which they hand over with one tap.
+      #
+      # The counterpart to Meta's usernames rollout: once a user adopts a username their
+      # phone number may stop reaching you, leaving only their
+      # [BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids).
+      # This is how you ask for the number back — and it is the only way to reach such a
+      # user with a one-tap, zero-tap, or copy-code authentication template, since those
+      # require a phone number.
+      #
+      # A tap arrives as an inbound `contacts` message whose
+      # {Whatsapp::Webhook::Message::Contacts::Contact#origin} is `"contact_request"`.
+      #
+      # Allowed on `UTILITY` and `MARKETING` templates only — a cross-component rule, so it
+      # lives in {ComponentSet} rather than here.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class RequestContactInfo < Base
+        module Defaults
+          TYPE = "REQUEST_CONTACT_INFO"
+          # The only label Meta accepts, if you send one at all. What the recipient sees is
+          # rendered in their own app language, so the button cannot be customized.
+          TEXT = "Share Contact Info"
+        end
+
+        # @!attribute [rw] text
+        #   @return [String, nil] Optional, and only ever {Defaults::TEXT}.
+        attr_accessor :text
+
+        validate :validate_text
+
+        # @param text [String, nil] Omit it — the label is not customizable and Meta
+        #   localizes what the recipient sees. Accepted only as the exact literal
+        #   {Defaults::TEXT}, for callers mirroring Meta's own example payload; it is
+        #   forwarded rather than dropped, since Meta documents the field as accepted.
+        #  @raise [ActiveModel::ValidationError] if `text` is anything else.
+        def initialize(text: nil)
+          @text = text
+
+          validate!
+        end
+
+        # @return [Hash] The serialized button — type alone, unless a label was given.
+        def serialize
+          { type: Defaults::TYPE, text: }.compact
+        end
+
+      private
+
+        # Hand-rolled rather than an `inclusion:` validator, because the default message
+        # ("is not included in the list") would not tell anyone *why* one value is allowed.
+        # @return [void]
+        def validate_text
+          return if text.nil? || text == Defaults::TEXT
+
+          errors.add(:text,
+            "must be exactly #{Defaults::TEXT.inspect} if given; " \
+              "Meta localizes the label the recipient sees, so it cannot be customized")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/message_templates/button.rb

@@ -11,8 +11,10 @@ module Whatsapp
     #
     # Only the button types with a published schema are registered. Meta's Graph API
     # enum also lists FLOW, MPM, CATALOG, VOICE_CALL, VIDEO_CALL, POSTBACK,
-    # BOOKING_STATUS, PAYMENT_REQUEST and REQUEST_CONTACT_INFO, but publishes no
-    # field reference for them, so they are deliberately absent rather than guessed.
+    # BOOKING_STATUS and PAYMENT_REQUEST, but publishes no field reference for them, so
+    # they are deliberately absent rather than guessed. REQUEST_CONTACT_INFO used to be on
+    # that list; the business-scoped user ID documentation publishes its schema, so it is
+    # registered.
     # Source: https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/
     class Button
       TYPES = {
@@ -21,6 +23,7 @@ module Whatsapp
         phone_number: PhoneNumber,
         copy_code: CopyCode,
         otp: Otp,
+        request_contact_info: RequestContactInfo,
       }.freeze
 
       class << self

data/lib/ruby/whatsapp/message_templates/component_set.rb

@@ -50,6 +50,12 @@ module Whatsapp
       # Categories that may use a location header.
       LOCATION_HEADER_CATEGORIES = [Categories::UTILITY, Categories::MARKETING].freeze
 
+      # Categories that may carry a request-contact-info button. Deliberately a separate
+      # constant from LOCATION_HEADER_CATEGORIES despite holding the same two values
+      # today: they are unrelated Meta rules that merely coincide, and merging them would
+      # couple two things that can move independently.
+      REQUEST_CONTACT_INFO_CATEGORIES = [Categories::UTILITY, Categories::MARKETING].freeze
+
       # @!attribute [rw] components
       #   @return [Array<Component::Base>]
       attr_accessor :components
@@ -67,6 +73,7 @@ module Whatsapp
       validate :validate_singletons
       validate :validate_category_restrictions
       validate :validate_location_header
+      validate :validate_request_contact_info_category
       validate :validate_limited_time_offer
 
       # @param components [Array<Hash, Component::Base>] The template's components.
@@ -151,6 +158,27 @@ module Whatsapp
           "a LOCATION header is only supported on #{LOCATION_HEADER_CATEGORIES.join('/')} templates, not #{category}")
       end
 
+      # Unlike CATEGORY_RESTRICTED_TYPES, which keys on *component* types, this rule is
+      # carried by a button nested inside a BUTTONS component — so it drills in the way
+      # #validate_location_header drills into a header, using the `api_types` that
+      # {Component::Buttons} already exposes.
+      #
+      # Only the top-level BUTTONS component is scanned, not carousel-card buttons: a
+      # CAROUSEL already forces MARKETING via CATEGORY_RESTRICTED_TYPES, which is an
+      # allowed category here, so a card-level scan could never fire.
+      # @return [void]
+      def validate_request_contact_info_category
+        return if category.nil?
+
+        buttons = find(Component::Buttons::Defaults::TYPE)
+        return unless buttons&.api_types&.include?(Button::RequestContactInfo::Defaults::TYPE)
+        return if REQUEST_CONTACT_INFO_CATEGORIES.include?(category)
+
+        errors.add(:components,
+          "a #{Button::RequestContactInfo::Defaults::TYPE} button is only supported on " \
+            "#{REQUEST_CONTACT_INFO_CATEGORIES.join('/')} templates, not #{category}")
+      end
+
       # A limited-time offer reshapes the rest of the template: no footer, a shorter
       # body, a media-only header, and a copy-code button that must come first.
       # @return [void]

data/lib/ruby/whatsapp/message_templates/response/paging.rb

@@ -3,7 +3,8 @@
 module Whatsapp
   class MessageTemplates
     module Response
-      # Graph API cursor pagination for a template list.
+      # Graph API cursor pagination for a template list. Nothing in it is
+      # template-specific, so {Whatsapp::Schedule::Response::Collection} reuses it.
       #
       # Flattens the nested `paging.cursors` object, since the intermediate level
       # carries no information of its own.

data/lib/ruby/whatsapp/messages/base.rb

@@ -10,16 +10,41 @@ module Whatsapp
         RECIPIENT_TYPE = "individual"
       end
 
+      # The two ways to address a message. Drives both the "at least one" guard and its
+      # message, so the rule and its wording cannot drift apart.
+      RECIPIENT_ATTRIBUTES = %i[to recipient].freeze
+
       # @!attribute [rw] to
-      #   @return [String]
+      #   @return [String, nil] The recipient's phone number. Optional since Meta added
+      #     {#recipient}, but still the identifier that wins if both are given.
       attr_accessor :to
 
-      validates :to, presence: true
+      # @!attribute [rw] recipient
+      #   @return [String, nil] The recipient's business-scoped user ID (BSUID), e.g.
+      #     `"US.13491208655302741918"`, or a parent BSUID, e.g.
+      #     `"US.ENT.11815799212886844830"` — a country code, a period, and up to 128
+      #     alphanumeric characters, with `ENT.` inserted for a parent BSUID. Pass the
+      #     whole value; omitting or altering any part of it fails the request.
+      #
+      #     Deliberately not format-checked here. Meta describes the shape but publishes
+      #     no client-side rule for it, and the canonical source of a BSUID is this gem's
+      #     own webhook side ({Whatsapp::Webhook::Contact#user_id} and friends), which
+      #     keeps it as a raw string — rejecting on the way out what was accepted on the
+      #     way in would be the worst possible asymmetry.
+      attr_accessor :recipient
+
+      validate :validate_recipient_present
+      validates :to, presence: true, allow_nil: true
+      validates :recipient, presence: true, allow_nil: true
 
-      # @param to [String] The recipient's phone number.
+      # @param to [String, nil] The recipient's phone number.
+      # @param recipient [String, nil] The recipient's BSUID or parent BSUID. Supply
+      #   either or both of `to`/`recipient`; Meta gives `to` precedence when both are
+      #   present.
       #  @raise [ActiveModel::ValidationError] if validation fails.
-      def initialize(to:)
+      def initialize(to: nil, recipient: nil)
         @to = to
+        @recipient = recipient
       end
 
       def serialize
@@ -36,11 +61,28 @@ module Whatsapp
         {
           messaging_product: Messaging::PRODUCT,
           recipient_type: Messaging::RECIPIENT_TYPE,
-          to:,
+          **recipient_fields,
           type:,
           **body,
         }
       end
+
+    private
+
+      # Only the recipient pair is compacted, not the whole envelope: an absent
+      # identifier must be left out rather than sent as null, but compacting the outer
+      # hash would also swallow a `nil` a subclass passes in `body`.
+      # @return [Hash] Whichever of `to`/`recipient` was given.
+      def recipient_fields
+        { to:, recipient: }.compact
+      end
+
+      # @return [void]
+      def validate_recipient_present
+        return if RECIPIENT_ATTRIBUTES.any? { |attribute| !public_send(attribute).nil? }
+
+        errors.add(:base, "at least one of #{RECIPIENT_ATTRIBUTES.join(' or ')} must be provided")
+      end
     end
   end
 end