ruby-whatsapp 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1149fca141867e8a80ee6276d8e39ea1a814630964d6d219119fb80c919de35b
-  data.tar.gz: a2d1a15a8a17f9b0065cf36ded985a329b35b9a7e7ef6408b0ba817551d90085
+  metadata.gz: 8b4ff5c9b9ee2bea36b889af8a3d153bb2e166d233ad9bfc51e20f9ec19ab9e7
+  data.tar.gz: 8d419f24aae3b21d0218bb95c68c4f75dec56ebdafb4c0447d7ec29e8def7b7b
 SHA512:
-  metadata.gz: 6bd1b41cd41a1745923e23445d1df5fc4af58bcccf52c3e88346b5064276bcc0d046f25e23a7905987393e5dab13571b04f92fcde7fbf1cd8a2bde6ede839330
-  data.tar.gz: a4e8dbb9bafa710512201d6b1e588c9b0193e64a43f3afc4cb08acec5a5fc45f1ce80ec3f5fe3da98f876b0a4cf26bbf6ef432d9f3305d6cab15ef05502bf14f
+  metadata.gz: 9c7d6fbfe3783788238af4ec52c683a122099f85fd7c408d94e09bc9a672b5594167e2de6bc05dfb85148f517bfee8c159d7f3f579191ae66020d05f3797cac5
+  data.tar.gz: 0d55554385a2fb98318996292131a59c64bed7206766d3b20d7c3033077232e02d5a24878db7e31b12e66b35270698ad892f1e0759468ae656baeda39e271f92

data/CHANGELOG.md

@@ -1,4 +1,14 @@
-## [Unreleased]
+## [0.4.0] - 2026-08-14
+
+- Add subscribed apps management: `Whatsapp::SubscribedApp::List`, `::Subscribe`, and `::Unsubscribe` wrap the `subscribed_apps` edge — the switch that turns a WABA's webhook delivery on or off, as opposed to `Whatsapp::Webhook`, which only deserializes notifications once Meta is already sending them. Responses expose `Collection`, `Subscription`, and `Unsubscription`, each composed from a shared `App` value object.
+- Add business phone number registration: `Whatsapp::BusinessPhoneNumber::Register` and `::Deregister` wrap the two endpoints that make a phone number usable — or not — with Cloud API. `Register` validates the 6-digit two-step verification PIN and the `data_localization_region` locally before any request is made.
+- Add the phone number verification flow that precedes registration: `Whatsapp::BusinessPhoneNumber::RequestCode` sends a verification code by SMS or voice call, and `::VerifyCode` confirms it, completing the `RequestCode` → `VerifyCode` → `Register` onboarding sequence. `Response` now carries an optional `id`, returned by `VerifyCode`.
+
+## [0.3.1] - 2026-08-13
+
+- Fix `Client#inspect` leaking the raw `api_key` in its default output — and, through it, any object holding a client (`Media#inspect`, `MessageTemplates#inspect`). Now redacted the same way `Configuration#inspect` already was. If a token may have reached an error tracker or console output that captures local variables, rotate it.
+- Fix `Client#path_for` passing IDs into the request path unencoded. A caller-supplied ID (e.g. `template_id`, `media_id`) could inject a query string or redirect an authenticated request to a different Graph API edge. Segments are now percent-encoded.
+- Fix `Webhook::Signature.valid?` raising `TypeError` instead of returning `false` for a `nil` payload.
 
 ## [0.3.0] - 2026-08-05
 

data/README.md

@@ -30,6 +30,8 @@ A small, dependency-light Ruby client for the [Meta WhatsApp Cloud API](https://
 - [Handling Responses](#handling-responses)
 - [Media](#media)
 - [Managing Templates](#managing-templates)
+- [Managing Subscribed Apps](#managing-subscribed-apps)
+- [Registering Business Phone Numbers](#registering-business-phone-numbers)
 - [Webhooks](#webhooks)
 - [Development](#development)
 - [Contributing](#contributing)
@@ -64,7 +66,7 @@ Whatsapp.configure do |config|
 end
 ```
 
-`api_key`, `app_secret`, and `verify_token` are redacted from `Configuration#inspect`, so they will not leak into logs.
+`api_key`, `app_secret`, and `verify_token` are redacted from `Configuration#inspect` and `Client#inspect`, so they will not leak into logs or error reports.
 
 ## Quick Start
 
@@ -89,6 +91,8 @@ response.messages.first.id # => "wamid.HBgLMTU1NTU1NTU1NTUV..."
 - **Hardened media downloads** — `Media#download` refuses to attach the bearer token to non-HTTPS URLs or hosts outside an allowlist, so a token can never leak to an attacker-influenced URL.
 - **Structured response parsing** — `Whatsapp::Messages::Response` exposes typed `#contacts` and `#messages` instead of raw JSON.
 - **Template management** — create, list, edit and delete the message templates on your WhatsApp Business Account from Ruby, with Meta's documented rules checked client-side so a rejection costs a validation error instead of a 24-hour review cycle.
+- **Subscribed apps management** — subscribe or unsubscribe this app from a WhatsApp Business Account's webhook notifications, and list who's currently subscribed, straight from Ruby.
+- **Business phone number onboarding** — request and verify a phone number's verification code, then register or deregister it with Cloud API, with the 6-digit two-step verification PIN and local-storage region checked client-side before any request is made.
 - **Inbound webhook parsing** — a typed object tree for all 19 documented Meta notification field types, plus signature verification.
 
 ## Sending Messages
@@ -556,6 +560,155 @@ templates.create_from_library(
   `message_template_status_update` and friends under [Webhooks](#webhooks).
 - Text containing `#{{1}}` needs single quotes in Ruby, or `#{` starts interpolation.
 
+## Managing Subscribed Apps
+
+Before your app receives any [webhook](#webhooks) notifications for a WhatsApp
+Business Account, it needs to be subscribed to it. `Whatsapp::SubscribedApp` wraps the
+`subscribed_apps` edge: one class per action, since — unlike templates — these three
+actions don't share an identity or validation rules to justify one combined class.
+
+This addresses your **WhatsApp Business Account** (`waba_id`, not `phone_id`) and needs
+the `whatsapp_business_management` permission, same as [template management](#managing-templates).
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key = ENV["WHATSAPP_API_KEY"]
+  config.waba_id = ENV["WHATSAPP_WABA_ID"]
+end
+
+Whatsapp::SubscribedApp::Subscribe.call                         # subscribe this app
+Whatsapp::SubscribedApp::List.call.map(&:name)                  # => ["My App"]
+Whatsapp::SubscribedApp::Unsubscribe.call                       # stop all webhook delivery
+```
+
+### Subscribing
+
+```ruby
+result = Whatsapp::SubscribedApp::Subscribe.call
+result.success       # => true
+result.map(&:name)   # => ["My App"] — every app now subscribed, Meta's own echo
+```
+
+Tech Providers routing several WABAs' notifications to different callback URLs pass an
+override instead of relying on the one callback URL configured on the app itself:
+
+```ruby
+Whatsapp::SubscribedApp::Subscribe.call(
+  override_callback_uri: "https://example.com/webhooks/acme_corp",
+  verify_token: "a-per-account-secret"
+)
+```
+
+### Listing
+
+```ruby
+apps = Whatsapp::SubscribedApp::List.call
+apps.map(&:name)          # Collection is Enumerable
+apps.first.link           # => "https://www.facebook.com/games/?app_id=..."
+
+Whatsapp::SubscribedApp::List.call(fields: %w[id name])  # restrict the fields returned
+```
+
+### Unsubscribing
+
+```ruby
+Whatsapp::SubscribedApp::Unsubscribe.call.success   # => true
+```
+
+Stops all webhook deliveries for this WABA immediately.
+
+Every action accepts an optional `client:` keyword (defaults to a new
+`Whatsapp::Client` built from `Whatsapp.configuration`), and raises
+`Whatsapp::SubscribedApp::Error` if no `waba_id` is configured or the API rejects the
+request.
+
+## Registering Business Phone Numbers
+
+A business phone number is unusable with Cloud API until it is **registered** —
+registration is the prerequisite that makes sending, media, and templates work for that
+number at all. `Whatsapp::BusinessPhoneNumber` wraps all four endpoints in that
+onboarding flow:
+
+```
+RequestCode  ->  VerifyCode  ->  Register            (onboarding)
+(send OTP)       (confirm it)    (activate on Cloud API)
+
+Deregister                                            (the reverse switch)
+```
+
+This addresses your **phone number** (`phone_id`, not `waba_id`), like
+[messages](#sending-messages) and [media](#media), and needs the
+`whatsapp_business_messaging` and `whatsapp_business_management` permissions.
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key  = ENV["WHATSAPP_API_KEY"]
+  config.phone_id = ENV["WHATSAPP_PHONE_ID"]
+end
+
+Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "SMS", language: "en_US")  # send an OTP
+Whatsapp::BusinessPhoneNumber::VerifyCode.call(code: "123456")                         # confirm it
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")   # register with your two-step verification PIN
+Whatsapp::BusinessPhoneNumber::Deregister.call                # release the number from Cloud API
+```
+
+### Requesting a verification code
+
+```ruby
+Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "SMS", language: "en_US").success   # => true
+```
+
+`code_method` must be `"SMS"` or `"VOICE"`; `language` is the locale for the
+verification message (e.g. `"en_US"`). Both are required — an invalid or missing value
+raises `ActiveModel::ValidationError` before any request is made.
+
+### Verifying the code
+
+```ruby
+result = Whatsapp::BusinessPhoneNumber::VerifyCode.call(code: "123456")
+result.success   # => true
+result.id        # => the phone number ID, when Meta returns one
+```
+
+### Registering
+
+```ruby
+result = Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")
+result.success   # => true
+```
+
+`pin` must be exactly 6 digits — the existing two-step verification PIN if one is
+already set, otherwise the PIN to set. An invalid PIN raises
+`ActiveModel::ValidationError` before any request is made.
+
+Pass `data_localization_region` to enable local storage in one of Meta's supported
+regions (`AU ID IN JP SG KR DE CH GB BR BH ZA AE CA`):
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834", data_localization_region: "CH")
+```
+
+### Deregistering
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Deregister.call.success   # => true
+```
+
+Deregistering makes the number unusable with Cloud API and disables local storage — it
+does **not** delete the number or its message history. A number in use with both Cloud
+API and the WhatsApp Business app cannot be deregistered.
+
+Every action accepts an optional `client:` keyword (defaults to a new
+`Whatsapp::Client` built from `Whatsapp.configuration` — pass one with a different
+`phone_id:` to target another number), and raises
+`Whatsapp::BusinessPhoneNumber::Error` if no `phone_id` is configured or the API rejects
+the request.
+
+> **Rate limits:** `Register`/`Deregister` are capped at 10 requests per business number
+> in a 72-hour moving window; exceeding it returns error `133016` and blocks the
+> operation for the next 72 hours. `RequestCode`/`VerifyCode` document only "standard
+> Graph API rate limits" plus possible additional throttling, with no published number.
+
 ## Webhooks
 
 Meta pushes inbound messages, delivery statuses, and ~18 other account/template

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Deregisters a business phone number from Cloud API. This makes the number
+    # unusable with Cloud API and disables local storage — it does not delete the
+    # number or its message history.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/phone-number-deregister-api
+    class Deregister
+      extend ResponseHandling
+      extend Transport
+
+      module Defaults
+        EDGE = "deregister"
+      end
+
+      # Meta documents no parameters for this edge — nothing to validate, so unlike
+      # {Register} this class carries no attributes and no `ActiveModel::Validations`.
+      # @return [Hash] Always empty.
+      def serialize
+        {}
+      end
+
+      class << self
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response]
+        # @raise [Error] if no phone number ID is configured, or the request fails.
+        def call(client: Client.new)
+          response = client.connection.post(edge_path(client, Defaults::EDGE), json: new.serialize)
+
+          Response.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "deregister business phone number"))
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Registers a business phone number with Cloud API, consuming its two-step
+    # verification PIN. This is the prerequisite for every other endpoint in this
+    # gem — a number cannot send, receive, or be otherwise addressed until it is
+    # registered.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
+    class Register
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      module Defaults
+        MESSAGING_PRODUCT = "whatsapp"
+        EDGE = "register"
+        PIN_PATTERN = /\A\d{6}\z/
+      end
+
+      # The regions Meta supports for local storage, grouped as Meta's docs group
+      # them. 2-letter ISO 3166 country codes.
+      module DataLocalizationRegions
+        APAC = %w[AU ID IN JP SG KR].freeze
+        EUROPE = %w[DE CH GB].freeze
+        LATAM = %w[BR].freeze
+        MEA = %w[BH ZA AE].freeze
+        NORAM = %w[CA].freeze
+
+        ALL = [*APAC, *EUROPE, *LATAM, *MEA, *NORAM].freeze
+
+        # Normalizes caller input to a canonical uppercase region code.
+        # 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.upcase
+          ALL.include?(candidate) ? candidate : value.to_s
+        end
+      end
+
+      # @!attribute [rw] pin
+      #   @return [String] The 6-digit two-step verification PIN.
+      attr_accessor :pin
+
+      # @!attribute [rw] data_localization_region
+      #   @return [String, nil] A 2-letter ISO 3166 country code enabling local storage.
+      attr_accessor :data_localization_region
+
+      validate :validate_pin
+      validates :data_localization_region, inclusion: { in: DataLocalizationRegions::ALL }, allow_nil: true
+
+      # @param pin [String, Integer] The 6-digit two-step verification PIN. If
+      #   two-step verification is already enabled on the number, this must be the
+      #   existing PIN.
+      # @param data_localization_region [String, Symbol, nil] One of
+      #   {DataLocalizationRegions::ALL}, either casing.
+      # @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(pin:, data_localization_region: nil)
+        @pin = pin
+        @data_localization_region = DataLocalizationRegions.normalize(data_localization_region)
+
+        validate!
+      end
+
+      # @return [Hash] The registration payload.
+      def serialize
+        { messaging_product: Defaults::MESSAGING_PRODUCT, pin: pin.to_s, data_localization_region: }.compact
+      end
+
+      # Redacts the pin so it never leaks into logs or console output.
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} pin=[REDACTED] data_localization_region=#{data_localization_region.inspect}>"
+      end
+
+      class << self
+        # @param pin [String, Integer] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @param data_localization_region [String, Symbol, nil] See {#initialize}.
+        # @return [Response]
+        # @raise [ActiveModel::ValidationError] if the pin or region is invalid.
+        # @raise [Error] if no phone number ID is configured, or the request fails.
+        def call(pin:, client: Client.new, data_localization_region: nil)
+          body = new(pin:, data_localization_region:).serialize
+          response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+          Response.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "register business phone number"))
+          )
+        end
+      end
+
+    private
+
+      # @return [void]
+      def validate_pin
+        errors.add(:pin, "must be exactly 6 digits") unless pin.to_s.match?(Defaults::PIN_PATTERN)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Requests a verification code (by SMS or voice call) for a business phone number —
+    # the first step of the onboarding flow this module wraps end to end:
+    # `RequestCode` -> {VerifyCode} -> {Register}.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/phone-number-verification-request-code-api
+    class RequestCode
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      module Defaults
+        EDGE = "request_code"
+      end
+
+      # How Meta delivers the verification code.
+      module CodeMethods
+        SMS = "SMS"
+        VOICE = "VOICE"
+
+        ALL = [SMS, VOICE].freeze
+
+        # Normalizes caller input to a canonical uppercase code method.
+        # Unrecognized values are returned as a string (preserving the original
+        # casing) so the inclusion validator can reject them.
+        # @param value [String, Symbol, nil]
+        # @return [String, nil]
+        def self.normalize(value)
+          return if value.nil?
+
+          candidate = value.to_s.upcase
+          ALL.include?(candidate) ? candidate : value.to_s
+        end
+      end
+
+      # @!attribute [rw] code_method
+      #   @return [String] One of {CodeMethods::ALL}.
+      attr_accessor :code_method
+
+      # @!attribute [rw] language
+      #   @return [String] The locale for the verification message (e.g. `"en_US"`).
+      attr_accessor :language
+
+      validates :code_method, presence: true, inclusion: { in: CodeMethods::ALL }
+      validates :language, presence: true
+
+      # @param code_method [String, Symbol] One of {CodeMethods::ALL}, either casing.
+      # @param language [String] The locale for the verification message. Meta
+      #   publishes no enum for this field, so only presence is checked — unlike
+      #   {Register}'s `pin`, which has a documented format.
+      # @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(code_method:, language:)
+        @code_method = CodeMethods.normalize(code_method)
+        @language = language
+
+        validate!
+      end
+
+      # @return [Hash] The request-code payload. Both fields are documented required,
+      #   so neither is ever compacted away.
+      def serialize
+        { code_method:, language: }
+      end
+
+      class << self
+        # @param code_method [String, Symbol] See {#initialize}.
+        # @param language [String] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response]
+        # @raise [ActiveModel::ValidationError] if the code method or language is invalid.
+        # @raise [Error] if no phone number ID is configured, or the request fails.
+        def call(code_method:, language:, client: Client.new)
+          body = new(code_method:, language:).serialize
+          response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+          Response.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "request verification code"))
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # The response shared by all four phone-number actions: `{success}`, with an
+    # optional `id` that only `VerifyCode` ever populates. One class covers all of
+    # them — unlike {Whatsapp::SubscribedApp}'s `Response::*` namespace — since
+    # {Register}, {Deregister}, {RequestCode}, and {VerifyCode} all return this same
+    # shape, `id` included or not.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
+    class Response
+      # @!attribute [rw] success
+      #   @return [Boolean] Whether the action succeeded.
+      attr_accessor :success
+
+      # @!attribute [rw] id
+      #   @return [String, nil] The phone number ID, only ever present on
+      #     {VerifyCode}'s response.
+      attr_accessor :id
+
+      # @param success [Boolean]
+      # @param id [String, nil]
+      def initialize(success: false, id: nil)
+        @success = success
+        @id = id
+      end
+
+      class << self
+        # @param response [Hash, nil] The parsed response body.
+        # @return [Response]
+        def deserialize(response)
+          response ||= {}
+
+          new(success: response["success"] == true, id: response["id"])
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # The one piece shared by {Register}, {Deregister}, {RequestCode}, and
+    # {VerifyCode}: all four address the same phone-number-scoped resource, differing
+    # only in edge name and body. Extended (not included) because {#edge_path} is used
+    # from class-level `.call` methods (as a private class method).
+    module Transport
+    private
+
+      # @param client [Whatsapp::Client]
+      # @param action [String] The edge to address ("register", "deregister",
+      #   "request_code", or "verify_code").
+      # @return [String] The versioned path to the phone number's action edge.
+      # @raise [Error] if no phone number ID is configured.
+      def edge_path(client, action)
+        if client.phone_id.nil? || client.phone_id.to_s.empty?
+          raise Error,
+            "phone_id is required for the #{action} edge; " \
+              "set it via Whatsapp.configure or Client.new(phone_id:)"
+        end
+
+        client.path_for(client.phone_id, action)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Confirms the verification code sent by {RequestCode}, the second step of the
+    # onboarding flow this module wraps end to end: {RequestCode} -> `VerifyCode` ->
+    # {Register}.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/verify-code-api
+    class VerifyCode
+      include ActiveModel::Validations
+      extend ResponseHandling
+      extend Transport
+
+      module Defaults
+        EDGE = "verify_code"
+      end
+
+      # @!attribute [rw] code
+      #   @return [String] The verification code received via SMS or voice call.
+      attr_accessor :code
+
+      validates :code, presence: true
+
+      # @param code [String, Integer] The verification code received via SMS or voice
+      #   call. Meta documents this as a plain string with no format rule, unlike
+      #   {Register}'s `pin`, so only presence is checked.
+      # @raise [ActiveModel::ValidationError] if validation fails.
+      def initialize(code:)
+        @code = code
+
+        validate!
+      end
+
+      # @return [Hash] The verify-code payload.
+      def serialize
+        { code: code.to_s }
+      end
+
+      # Redacts the code so it never leaks into logs or console output, same as
+      # {Register#inspect} redacts the pin.
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} code=[REDACTED]>"
+      end
+
+      class << self
+        # @param code [String, Integer] See {#initialize}.
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response]
+        # @raise [ActiveModel::ValidationError] if the code is blank.
+        # @raise [Error] if no phone number ID is configured, or the request fails.
+        def call(code:, client: Client.new)
+          body = new(code:).serialize
+          response = client.connection.post(edge_path(client, Defaults::EDGE), json: body)
+
+          Response.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "verify code"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Onboards and deboards a business phone number with Cloud API: requesting and
+  # verifying a phone number's verification code, then registering or deregistering it.
+  #
+  # This is the switch that makes a phone number usable — or not — with Cloud API in
+  # 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`.
+  #
+  # 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`.
+  # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration
+  module BusinessPhoneNumber
+    class Error < Whatsapp::Error; end
+  end
+end

data/lib/ruby/whatsapp/client.rb

@@ -5,6 +5,9 @@ module Whatsapp
     # Default request timeout in seconds.
     DEFAULT_TIMEOUT = 30
 
+    # Characters that must be percent-escaped in a path segment (everything except RFC 3986 "unreserved").
+    SEGMENT_UNRESERVED = /[^A-Za-z0-9\-._~]/
+
     # @!attribute [rw] host
     # @return [String]
     attr_accessor :host
@@ -69,14 +72,32 @@ module Whatsapp
       end
     end
 
-    # Builds a versioned request path.
+    # Builds a versioned request path. Segments are percent-encoded so a caller-supplied
+    # ID can't inject a query string or redirect to a different Graph edge.
     # @example
     #   path_for(phone_id, "messages") #=> "/v24.0/<phone_id>/messages"
     #   path_for(media_id)             #=> "/v24.0/<media_id>"
     # @param segments [Array<String>] Path segments appended after the version.
     # @return [String] The full request path.
     def path_for(*segments)
-      "/#{[version, *segments].join('/')}"
+      "/#{[version, *segments].map { |segment| encode_segment(segment) }.join('/')}"
+    end
+
+    # Redacts the api_key so it never leaks into logs or console output.
+    # @return [String]
+    def inspect
+      redacted_api_key = api_key.nil? ? "nil" : "[REDACTED]"
+      "#<#{self.class.name} host=#{host.inspect} version=#{version.inspect} " \
+        "api_key=#{redacted_api_key} phone_id=#{phone_id.inspect} waba_id=#{waba_id.inspect}>"
+    end
+
+  private
+
+    # Percent-encodes one path segment, byte-wise so multibyte input is handled correctly.
+    # @param segment [#to_s] The segment to encode.
+    # @return [String]
+    def encode_segment(segment)
+      segment.to_s.b.gsub(SEGMENT_UNRESERVED) { |byte| format("%%%02X", byte.ord) }
     end
   end
 end

data/lib/ruby/whatsapp/subscribed_app/list.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Lists the apps currently subscribed to a WABA's webhook notifications.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+    class List
+      extend ResponseHandling
+      extend Transport
+
+      class << self
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @param fields [Array<String>, String, nil] Restrict each app to these fields
+        #   (`id`, `name`, `link`).
+        # @return [Response::Collection]
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(client: Client.new, fields: nil)
+          params = fields ? { fields: Array(fields).join(",") } : {}
+          response = client.connection.get(edge_path(client), params:)
+
+          Response::Collection.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "list subscribed apps"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/response/app.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # One app subscribed to a WABA's webhook notifications.
+      #
+      # Meta nests `id`/`name`/`link` inside `whatsapp_business_api_data`; this class
+      # flattens that away since the wrapper carries no information of its own.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class App
+        # @!attribute [rw] id
+        #   @return [String, nil] The subscribed app's ID.
+        attr_accessor :id
+
+        # @!attribute [rw] name
+        #   @return [String, nil] The subscribed app's name.
+        attr_accessor :name
+
+        # @!attribute [rw] link
+        #   @return [String, nil] A link to the app.
+        attr_accessor :link
+
+        # @!attribute [rw] override_callback_uri
+        #   @return [String, nil] The per-WABA webhook callback override, if one is set.
+        attr_accessor :override_callback_uri
+
+        # @param id [String, nil]
+        # @param name [String, nil]
+        # @param link [String, nil]
+        # @param override_callback_uri [String, nil]
+        def initialize(id: nil, name: nil, link: nil, override_callback_uri: nil)
+          @id = id
+          @name = name
+          @link = link
+          @override_callback_uri = override_callback_uri
+        end
+
+        class << self
+          # @param data [Hash, nil] One element of the `data` array.
+          # @return [App]
+          def deserialize(data)
+            data ||= {}
+            api_data = data["whatsapp_business_api_data"] || {}
+
+            new(
+              id: api_data["id"],
+              name: api_data["name"],
+              link: api_data["link"],
+              override_callback_uri: data["override_callback_uri"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/response/collection.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # The apps currently subscribed to a WABA's webhook notifications: `{data}`.
+      #
+      # Enumerable over its apps, so `list.map(&:name)` reads naturally without
+      # reaching for `.data` first.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class Collection
+        include Enumerable
+
+        # @!attribute [rw] data
+        #   @return [Array<App>]
+        attr_accessor :data
+
+        # @param data [Array<App>]
+        def initialize(data: [])
+          @data = data
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Collection]
+          def deserialize(response)
+            response ||= {}
+
+            new(data: Array(response["data"]).map { |entry| App.deserialize(entry) })
+          end
+        end
+
+        # @yieldparam app [App]
+        # @return [Enumerator]
+        def each(&)
+          data.each(&)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/response/subscription.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # The response to subscribing this app to a WABA's webhook notifications:
+      # `{success, data}`.
+      #
+      # `data` mirrors {Collection}'s shape exactly, since Meta echoes back every app
+      # now subscribed — deserialization is delegated to {Collection.deserialize}
+      # rather than duplicating the `App` mapping.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class Subscription
+        include Enumerable
+
+        # @!attribute [rw] success
+        #   @return [Boolean] Whether the subscription succeeded.
+        attr_accessor :success
+
+        # @!attribute [rw] data
+        #   @return [Array<App>]
+        attr_accessor :data
+
+        # @param success [Boolean]
+        # @param data [Array<App>]
+        def initialize(success: false, data: [])
+          @success = success
+          @data = data
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Subscription]
+          def deserialize(response)
+            response ||= {}
+
+            new(success: response["success"] == true, data: Collection.deserialize(response).to_a)
+          end
+        end
+
+        # @yieldparam app [App]
+        # @return [Enumerator]
+        def each(&)
+          data.each(&)
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/response/unsubscription.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    module Response
+      # The response to unsubscribing this app from a WABA's webhook notifications:
+      # `{success}`.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+      class Unsubscription
+        # @!attribute [rw] success
+        #   @return [Boolean] Whether the app was unsubscribed.
+        attr_accessor :success
+
+        # @param success [Boolean]
+        def initialize(success: false)
+          @success = success
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Unsubscription]
+          def deserialize(response)
+            response ||= {}
+
+            new(success: response["success"] == true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Deserializers for the responses of the `subscribed_apps` edge.
+    #
+    # Three response shapes, one per action, so a namespace of small classes rather
+    # than a single one with optional fields:
+    #
+    #   {Collection}     `{data}`            List
+    #   {Subscription}   `{success, data}`   Subscribe
+    #   {Unsubscription} `{success}`         Unsubscribe
+    #
+    # Every class follows the gem's `.deserialize(data)` convention and tolerates a nil
+    # or partial payload, so a field Meta stops sending cannot raise.
+    module Response
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/subscribe.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Subscribes this app to a WABA's webhook notifications.
+    #
+    # `override_callback_uri`/`verify_token` are for Tech Providers routing several
+    # WABAs' notifications to different callback URLs instead of the one configured on
+    # the app itself.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+    class Subscribe
+      extend ResponseHandling
+      extend Transport
+
+      class << self
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @param override_callback_uri [String, nil] A per-WABA webhook callback override.
+        # @param verify_token [String, nil] The token Meta echoes back if it re-verifies
+        #   `override_callback_uri`.
+        # @return [Response::Subscription]
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(client: Client.new, override_callback_uri: nil, verify_token: nil)
+          body = { override_callback_uri:, verify_token: }.compact
+          response = client.connection.post(edge_path(client), json: body)
+
+          Response::Subscription.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "subscribe app"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/transport.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # The one piece shared by {List}, {Subscribe}, and {Unsubscribe}: all three address
+    # the same WABA-scoped edge, differing only in HTTP verb and body. Extended (not
+    # included) since those classes are class-method-only.
+    module Transport
+    private
+
+      # @param client [Whatsapp::Client]
+      # @return [String] The versioned path to the `subscribed_apps` edge.
+      # @raise [Error] if no WABA ID is configured.
+      def edge_path(client)
+        if client.waba_id.nil? || client.waba_id.to_s.empty?
+          raise Error, "waba_id is required for subscribed apps; set it via Whatsapp.configure or Client.new(waba_id:)"
+        end
+
+        client.path_for(client.waba_id, "subscribed_apps")
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app/unsubscribe.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module SubscribedApp
+    # Unsubscribes this app from a WABA's webhook notifications. All webhook
+    # deliveries for that WABA stop immediately.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+    class Unsubscribe
+      extend ResponseHandling
+      extend Transport
+
+      class << self
+        # @param client [Whatsapp::Client] The WhatsApp client instance.
+        # @return [Response::Unsubscription]
+        # @raise [Error] if no WABA ID is configured, or the request fails.
+        def call(client: Client.new)
+          response = client.connection.delete(edge_path(client))
+
+          Response::Unsubscription.deserialize(
+            parse_json(handle_response!(response, error_class: Error, action: "unsubscribe app"))
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/subscribed_app.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  # Subscribes or unsubscribes this app from a WhatsApp Business Account's webhook
+  # notifications, and lists which apps are currently subscribed.
+  #
+  # This is what turns webhook delivery on and off in the first place — the opposite
+  # concern from {Whatsapp::Webhook}, which only deserializes notifications once Meta
+  # is already sending them. Addresses `waba_id`, not `phone_id`, like
+  # {Whatsapp::MessageTemplates}. See `lib/ruby/whatsapp/subscribed_app/CLAUDE.md`.
+  # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/subscribed-apps-api
+  module SubscribedApp
+    class Error < Whatsapp::Error; end
+  end
+end

data/lib/ruby/whatsapp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Whatsapp
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/ruby/whatsapp/webhook/signature.rb

@@ -9,13 +9,14 @@ module Whatsapp
       PREFIX = "sha256="
 
       class << self
-        # @param payload [String] The raw (unparsed) request body.
+        # @param payload [String, nil] The raw (unparsed) request body.
         # @param header [String, nil] The `X-Hub-Signature-256` header value.
         # @param app_secret [String, nil] The secret to verify against. Defaults to the
         #   globally configured secret; pass an explicit value for multi-tenant apps where
         #   each account has its own Meta App (and therefore its own secret).
         # @return [Boolean] Whether the header matches the computed signature.
         def valid?(payload:, header:, app_secret: Whatsapp.configuration.app_secret)
+          return false if payload.nil?
           return false if header.nil? || header.empty?
           return false if app_secret.nil? || app_secret.empty?
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-whatsapp
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Raniery
@@ -83,6 +83,13 @@ files:
 - README.md
 - Rakefile
 - lib/ruby/whatsapp.rb
+- lib/ruby/whatsapp/business_phone_number.rb
+- lib/ruby/whatsapp/business_phone_number/deregister.rb
+- lib/ruby/whatsapp/business_phone_number/register.rb
+- lib/ruby/whatsapp/business_phone_number/request_code.rb
+- lib/ruby/whatsapp/business_phone_number/response.rb
+- lib/ruby/whatsapp/business_phone_number/transport.rb
+- lib/ruby/whatsapp/business_phone_number/verify_code.rb
 - lib/ruby/whatsapp/client.rb
 - lib/ruby/whatsapp/configuration.rb
 - lib/ruby/whatsapp/instrumentation.rb
@@ -171,6 +178,16 @@ files:
 - lib/ruby/whatsapp/railtie.rb
 - lib/ruby/whatsapp/request_error.rb
 - lib/ruby/whatsapp/response_handling.rb
+- lib/ruby/whatsapp/subscribed_app.rb
+- lib/ruby/whatsapp/subscribed_app/list.rb
+- lib/ruby/whatsapp/subscribed_app/response.rb
+- lib/ruby/whatsapp/subscribed_app/response/app.rb
+- lib/ruby/whatsapp/subscribed_app/response/collection.rb
+- lib/ruby/whatsapp/subscribed_app/response/subscription.rb
+- lib/ruby/whatsapp/subscribed_app/response/unsubscription.rb
+- lib/ruby/whatsapp/subscribed_app/subscribe.rb
+- lib/ruby/whatsapp/subscribed_app/transport.rb
+- lib/ruby/whatsapp/subscribed_app/unsubscribe.rb
 - lib/ruby/whatsapp/utils/language_codes.rb
 - lib/ruby/whatsapp/version.rb
 - lib/ruby/whatsapp/webhook.rb