ruby-whatsapp 0.4.0 → 0.6.1

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

@@ -8,13 +8,29 @@ module Whatsapp
   # the first place. It is a different concern from {Whatsapp::SubscribedApp}, which
   # turns webhook delivery on and off for a whole WhatsApp Business Account: this
   # module is per phone number and is a prerequisite for messaging itself, not just
-  # for notifications. Addresses `phone_id`, like {Whatsapp::Media} and
-  # {Whatsapp::Messages}, not `waba_id`.
+  # for notifications. The onboarding actions address `phone_id`, like
+  # {Whatsapp::Media} and {Whatsapp::Messages}.
   #
   # The full flow, in order: {RequestCode} -> {VerifyCode} -> {Register}, with
   # {Deregister} as the reverse switch.
-  # See `lib/ruby/whatsapp/business_phone_number/CLAUDE.md` and
-  # `docs/business-phone-number-api.md`.
+  #
+  # {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.
+  # See `lib/ruby/whatsapp/business_phone_number/CLAUDE.md`,
+  # `docs/business_phone_number/README.md`, and `docs/business_phone_number/profile.md`.
   # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
   module BusinessPhoneNumber
     class Error < Whatsapp::Error; end

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/message_templates.rb

@@ -25,6 +25,7 @@ module Whatsapp
   #   templates.find(template_id: created.id).status # => "PENDING"
   # Source: https://developers.facebook.com/docs/graph-api/reference/whats-app-business-account/message_templates/
   class MessageTemplates
+    include PathBuilding
     include ResponseHandling
 
     class TemplateError < Whatsapp::Error; end
@@ -204,12 +205,7 @@ module Whatsapp
     # @return [String] The versioned path for a WABA-scoped edge.
     # @raise [TemplateError] if no WABA ID is configured.
     def edge_path(edge)
-      if blank_value?(client.waba_id)
-        raise TemplateError,
-          "waba_id is required for template management; set it via Whatsapp.configure or Client.new(waba_id:)"
-      end
-
-      client.path_for(client.waba_id, edge)
+      scoped_path(client, :waba_id, edge, error_class: TemplateError, purpose: "template management")
     end
 
     # @return [Hash] Only the editable fields that were supplied.

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

data/lib/ruby/whatsapp/messages/interactive/request_contact_info.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  class Messages
+    class Interactive
+      # Asks the recipient to share their phone number, which they hand over with one tap.
+      #
+      # The interactive-message counterpart to
+      # {Whatsapp::MessageTemplates::Button::RequestContactInfo}: use this inside the
+      # 24-hour service window, and the template button to open a conversation. Either way
+      # this is how you get a phone number back from someone who has adopted a username and
+      # reaches you only as a
+      # [BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids).
+      #
+      # The only action kind with nothing for the caller to supply — the whole payload is
+      # `{ name: "request_contact_info" }` — which is why {Interactive} marks it
+      # parameterless and stops requiring an `action:`. Compare
+      # {Whatsapp::Messages::LocationRequest}, whose action is the same shape.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class RequestContactInfo < Base
+        module Defaults
+          ACTION_NAME = "request_contact_info"
+        end
+
+        # @!attribute [rw] name
+        #   @return [String] Always {Defaults::ACTION_NAME}.
+        attr_accessor :name
+
+        validates :name, inclusion: { in: [Defaults::ACTION_NAME] }
+
+        # @param name [String] The action name. Defaulted, since Meta accepts exactly one
+        #   value; the keyword exists so a caller spelling out
+        #   `action: { name: "request_contact_info" }` — mirroring Meta's example payload —
+        #   still works.
+        #  @raise [ActiveModel::ValidationError] if `name` is anything else.
+        def initialize(name: Defaults::ACTION_NAME)
+          @name = name
+
+          validate!
+        end
+
+        class << self
+          # Takes a keyword splat rather than named parameters, because {Interactive} calls
+          # it as `serialize(**action)` with an empty hash for this kind.
+          # @return [Hash] Serialized representation of the request.
+          def serialize(**)
+            new(**).serialize
+          end
+        end
+
+        # @return [Hash] Serialized representation of the request — no `parameters` key,
+        #   unlike every other action kind, because there is nothing to parameterize.
+        def serialize
+          { name: }
+        end
+      end
+    end
+  end
+end

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

@@ -19,6 +19,10 @@ module Whatsapp
         url_button: { klass: UrlButton, api_type: "cta_url" },
         media_carousel: { klass: MediaCarousel, api_type: "carousel" },
         product_carousel: { klass: ProductCarousel, api_type: "product_list" },
+        # The one kind whose registry key and wire value coincide — the registry exists
+        # because they usually differ, so this is not a copy-paste slip. `parameterless`
+        # marks the one kind with nothing for a caller to supply; see #validate_action.
+        request_contact_info: { klass: RequestContactInfo, api_type: "request_contact_info", parameterless: true },
       }.freeze
 
       # @!attribute [rw] type
@@ -43,16 +47,17 @@ module Whatsapp
 
       validates :type, presence: true, inclusion: { in: ACTION_TYPES.keys }
       validates :body, presence: true
-      validates :action, presence: true
+      validate :validate_action
 
       # @param type [Symbol, String] The action kind (see {ACTION_TYPES}).
       # @param body [String] The body text of the interactive message.
-      # @param action [Hash] The action content, forwarded to the action class.
+      # @param action [Hash] The action content, forwarded to the action class. Defaults to
+      #   empty, which only the parameterless `:request_contact_info` kind accepts.
       # @param header [Hash, nil] The header content (optional).
       # @param footer [Hash, nil] The footer content (optional).
-      # @param kwargs [Hash] Additional keyword arguments (e.g. :to).
+      # @param kwargs [Hash] Additional keyword arguments passed to {Base} (:to / :recipient).
       #  @raise [ActiveModel::ValidationError] if validation fails.
-      def initialize(type:, body:, action:, header: nil, footer: nil, **)
+      def initialize(type:, body:, action: {}, header: nil, footer: nil, **)
         super(**)
 
         @type = type.to_sym
@@ -87,6 +92,19 @@ module Whatsapp
         ACTION_TYPES.fetch(type)
       end
 
+      # An empty `action` is blank, so a plain presence validator would reject the one kind
+      # that legitimately has nothing to supply. Reads the registry with `[]` rather than
+      # the `fetch`-backed #action_config, so an unknown `type` falls through to the
+      # inclusion validator above instead of raising KeyError from inside a validator.
+      # @return [void]
+      def validate_action
+        config = ACTION_TYPES[type]
+        return if config.nil? || config[:parameterless]
+        return if action.present?
+
+        errors.add(:action, "can't be blank")
+      end
+
       # @return [Hash, nil] The serialized header information.
       def serialized_header
         return unless header

data/lib/ruby/whatsapp/messages/response/contacts.rb

@@ -5,18 +5,34 @@ module Whatsapp
     class Response
       class Contacts
         # @!attribute [rw] input
-        #   @return [String]
+        #   @return [String] Whatever you addressed the message to: the phone number, the
+        #     BSUID or parent BSUID, or a group ID.
         attr_accessor :input
 
         # @!attribute [rw] wa_id
-        #   @return [String]
+        #   @return [String, nil] The recipient's WhatsApp ID. Present only if the message
+        #     was sent to their phone number; omitted otherwise.
         attr_accessor :wa_id
 
+        # @!attribute [rw] user_id
+        #   @return [String, nil] The recipient's business-scoped user ID (BSUID), or parent
+        #     BSUID — Meta returns either in this one field, unlike the webhook classes,
+        #     which separate `user_id` from `parent_user_id`.
+        #
+        #     Omitted whenever the message went to a phone number, **including when both
+        #     `to` and `recipient` were supplied**, since Meta gives `to` precedence and
+        #     answers as though `recipient` had not been sent. A `nil` here therefore does
+        #     not mean the recipient has no BSUID.
+        attr_accessor :user_id
+
         # @param input [String] The input value of the contact.
-        # @param wa_id [String] The WhatsApp ID of the contact.
-        def initialize(input:, wa_id:)
+        # @param wa_id [String, nil] The WhatsApp ID of the contact, if it was addressed by
+        #   phone number.
+        # @param user_id [String, nil] The contact's BSUID, if it was addressed by one.
+        def initialize(input:, wa_id: nil, user_id: nil)
           @input = input
           @wa_id = wa_id
+          @user_id = user_id
         end
 
         class << self
@@ -26,7 +42,8 @@ module Whatsapp
           def deserialize(data)
             new(
               input: data["input"],
-              wa_id: data["wa_id"]
+              wa_id: data["wa_id"],
+              user_id: data["user_id"]
             )
           end
         end

data/lib/ruby/whatsapp/path_building.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # The ID guard and path build shared by every WABA- or phone-number-scoped feature.
+  #
+  # Each feature keeps its own transport with a named method — {Whatsapp::SubscribedApp::Transport}'s
+  # `edge_path`, {Whatsapp::BusinessPhoneNumber::Account::Transport}'s `node_path` — since those
+  # names are what keep an edge and a node from being confused at a call site. This holds only
+  # the part that was identical across all of them: refusing to address an unconfigured ID, and
+  # phrasing that refusal the same way every time.
+  module PathBuilding
+  private
+
+    # @param client [Whatsapp::Client]
+    # @param id_name [Symbol] The client attribute to address (`:waba_id` or `:phone_id`).
+    # @param segments [Array<String>] Edge segments after the ID; pass none to address the node itself.
+    # @param error_class [Class] The feature's own error class, never {Whatsapp::RequestError}.
+    # @param purpose [String] What the caller was reaching for, e.g. `"subscribed apps"`.
+    # @return [String] The versioned path.
+    # @raise [Whatsapp::Error] the given error_class, if the ID is not configured.
+    def scoped_path(client, id_name, *segments, error_class:, purpose:)
+      id = client.public_send(id_name)
+
+      if id.nil? || id.to_s.empty?
+        raise error_class,
+          "#{id_name} is required for #{purpose}; " \
+            "set it via Whatsapp.configure or Client.new(#{id_name}:)"
+      end
+
+      client.path_for(id, *segments)
+    end
+  end
+end

data/lib/ruby/whatsapp/schedule/create.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Schedule
+    # Schedules an approved template to be sent to an audience at a set time.
+    #
+    # A validated instance rather than a bare class method (unlike {List}, which has
+    # nothing to check): Meta documents all six body fields as required, so a missing
+    # one fails here rather than costing a request. Nothing beyond that is checked —
+    # Meta publishes no length limits and no rule that `delivery_time` must be in the
+    # future.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api
+    class Create
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      # @!attribute [rw] hsm_id
+      #   @return [String] The ID of the approved template to send.
+      attr_accessor :hsm_id
+
+      # @!attribute [rw] audience_id
+      #   @return [String] The ID of the audience to send it to.
+      attr_accessor :audience_id
+
+      # @!attribute [rw] waba_cs_id
+      #   @return [String] What Meta documents only as "WABA customer status ID (phone
+      #     number)"; whether that means a phone number ID or the number itself is
+      #     unverified, so it is passed through as given.
+      attr_accessor :waba_cs_id
+
+      # @!attribute [rw] name
+      #   @return [String] The schedule's name.
+      attr_accessor :name
+
+      # @!attribute [rw] description
+      #   @return [String] The schedule's description.
+      attr_accessor :description
+
+      # @!attribute [rw] delivery_time
+      #   @return [Integer] When to send, as a Unix timestamp.
+      attr_accessor :delivery_time
+
+      validates :hsm_id, :audience_id, :waba_cs_id, :name, :description, presence: true
+      validates :delivery_time, numericality: { only_integer: true }
+
+      # @param hsm_id [String] See {#hsm_id}.
+      # @param audience_id [String] See {#audience_id}.
+      # @param waba_cs_id [String] See {#waba_cs_id}.
+      # @param name [String] See {#name}.
+      # @param description [String] See {#description}.
+      # @param delivery_time [Integer] A Unix timestamp; pass `time.to_i` for a `Time`.
+      # @raise [ActiveModel::ValidationError] if a field is blank, or `delivery_time`
+      #   is not an integer.
+      def initialize(hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time:)
+        @hsm_id = hsm_id
+        @audience_id = audience_id
+        @waba_cs_id = waba_cs_id
+        @name = name
+        @description = description
+        @delivery_time = delivery_time
+
+        validate!
+      end
+
+      # @return [Hash] The schedule payload. Every field is documented required, so
+      #   none is ever compacted away.
+      def serialize
+        { hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time: }
+      end
+
+      class << self
+        # @example Send a template to an audience in one hour
+        #   Create.call(
+        #     hsm_id: "1234567890", audience_id: "2345678901", waba_cs_id: "3456789012",
+        #     name: "Black Friday", description: "Black Friday promo to VIP customers",
+        #     delivery_time: Time.now.to_i + 3600
+        #   ).id
+        # @param hsm_id [String] See {#initialize}.
+        # @param audience_id [String] See {#initialize}.
+        # @param waba_cs_id [String] See {#initialize}.
+        # @param name [String] See {#initialize}.
+        # @param description [String] See {#initialize}.
+        # @param delivery_time [Integer] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response::Created]
+        # @raise [ActiveModel::ValidationError] if a field is blank, or `delivery_time`
+        #   is not an integer.
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time:, client: Client.new)
+          body = new(hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time:).serialize
+          response = client.connection.post(edge_path(client), json: body)
+
+          Response::Created.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "create schedule"))
+          )
+        end
+      end
+    end
+  end
+end