ruby-whatsapp 0.4.2 → 0.6.1

data/docs/webhooks/smb_app_state_sync.md

@@ -3,30 +3,63 @@
 Contact-book and app-state changes synced from the WhatsApp Business app. Arrives
 alongside [`history`](history.md) when a number moves onto Cloud API.
 
-`Whatsapp::Webhook::SmbAppStateSync` · confidence: **low-moderate**
+`Whatsapp::Webhook::SmbAppStateSync` · confidence: **high**
 
 ## Payload
 
 ```json
 { "field": "smb_app_state_sync",
-  "value": { "state_sync": [{ "type": "contact",
-                              "action": "add",
-                              "contact": { "full_name": "Jane Doe", "phone_number": "+1" } }] } }
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "state_sync": [
+      { "type": "contact",
+        "contact": { "full_name": "Pablo Morales",
+                     "first_name": "Pablo",
+                     "phone_number": "16505551234",
+                     "user_id": "US.13491208655302741918",
+                     "username": "pablomorales" },
+        "action": "add",
+        "metadata": { "timestamp": "1750030073" } }
+    ] } }
 ```
 
 ## Accessors
 
 | Accessor | Type |
 | --- | --- |
+| `messaging_product` | `"whatsapp"` |
+| `metadata` | `Metadata` — the business phone number whose address book this is |
 | `state_sync` | `Array<SmbAppStateSync::StateSync>` |
+| `raw` | The untouched `value` hash |
 
 ### `StateSync`
 
 | Accessor | Meaning |
 | --- | --- |
-| `type` | e.g. `contact` |
+| `type` | `"contact"` is the only documented kind |
 | `action` | e.g. `add`, `update`, `remove` |
-| `contact` | **Raw Hash** — the shape is undocumented |
+| `contact` | An `SmbAppStateSync::Contact`, or `nil` |
+| `timestamp` | Flattened up from the entry's own `metadata.timestamp` |
+
+The entry's `metadata` is **not** the value-level `Metadata` — it carries only a
+timestamp, so the wrapper is dropped rather than typed.
+
+### `Contact`
+
+| Accessor | Meaning |
+| --- | --- |
+| `full_name` | |
+| `first_name` | |
+| `phone_number` | Omitted once the contact adopts a username |
+| `user_id` | Their [BSUID](messages.md#business-scoped-user-ids-bsuid) |
+| `parent_user_id` | Their parent BSUID, present only if enrolled |
+| `username` | Set only if adopted. Read **flat** here, unlike `Contact#username` on `messages`, which Meta nests under `profile` |
+
+This is the gem's third `Contact`, and none are interchangeable:
+[`Webhook::Contact`](messages.md#value-accessors) is a notification's sender identity,
+[`Message::Contacts::Contact`](messages.md#contacts) is a shared contact *card*, and this
+is a device address-book row.
 
 ## Handling it
 
@@ -37,17 +70,22 @@ when "smb_app_state_sync"
 
     case sync.action
     when "add", "update"
-      Contact.upsert_from_meta(sync.contact)
+      Contact.upsert_from_meta(bsuid: sync.contact.user_id, phone: sync.contact.phone_number,
+                               name: sync.contact.full_name, username: sync.contact.username)
     when "remove"
-      Contact.find_by(phone: sync.contact["phone_number"])&.destroy
+      Contact.find_by(bsuid: sync.contact.user_id)&.destroy
     end
   end
 ```
 
-> **Best-effort schema, low-moderate confidence.** `contact` is left as a raw hash
-> precisely because its keys are unverified. Validate against a real payload before
-> depending on it in production.
+> **Changed in 0.6.0.** `StateSync#contact` used to be a raw Hash, because Meta had
+> published no shape for it. It is now a typed `Contact`, so `sync.contact["phone_number"]`
+> becomes `sync.contact.phone_number`, and an entry carrying no contact returns `nil`
+> rather than `{}`.
+
+> The `state_sync` key itself is still inferred from the field name rather than confirmed
+> by a published example — hence `raw`, so a drifted key leaves a trace.
 
 ---
 
-**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

data/docs/webhooks/smb_message_echoes.md

@@ -2,20 +2,32 @@
 
 Echoes of messages sent **from the WhatsApp Business app** rather than through the API.
 Without this, a number used by both your code and a human agent in the app would show
-you only half the conversation.
+you only half the conversation. Messages the business *revoked* or *edited* from the app
+arrive here too.
 
-`Whatsapp::Webhook::SmbMessageEchoes` · confidence: **moderate**
+`Whatsapp::Webhook::SmbMessageEchoes` · confidence: **high**
 
 ## Payload
 
 ```json
 { "field": "smb_message_echoes",
-  "value": { "messaging_product": "whatsapp",
-             "metadata": { "display_phone_number": "15550783881",
-                           "phone_number_id": "106540352242922" },
-             "message_echoes": [{ "from": "15550783881",
-                                  "type": "text",
-                                  "text": { "body": "Thanks for shopping with us!" } }] } }
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "contacts": [
+      { "profile": { "username": "pablomorales" },
+        "wa_id": "16505551234",
+        "user_id": "US.13491208655302741918" }
+    ],
+    "message_echoes": [
+      { "from": "15550783881",
+        "to": "16505551234",
+        "to_user_id": "US.13491208655302741918",
+        "id": "wamid.HBg",
+        "timestamp": "1750030073",
+        "type": "text",
+        "text": { "body": "Thanks for shopping with us!" } }
+    ] } }
 ```
 
 ## Accessors
@@ -24,31 +36,56 @@ you only half the conversation.
 | --- | --- |
 | `messaging_product` | `"whatsapp"` |
 | `metadata` | `Metadata` — `display_phone_number`, `phone_number_id` |
-| `message_echoes` | `Array<Message::*>` |
+| `contacts` | `Array<Contact>` — the customers these went to |
+| `message_echoes` | `Array<SmbMessageEchoes::Echo>` |
+| `raw` | The untouched `value` hash |
 
-`message_echoes` reuses the same `Message.deserialize` dispatcher as
-[`messages`](messages.md), so every echoed message is a fully typed `Message::Text`,
-`Message::Image`, and so on — with the same accessors.
+### `Echo`
+
+| Accessor | Meaning |
+| --- | --- |
+| `to` | The customer's phone number, or `nil` once they adopt a username |
+| `to_user_id` | Their [BSUID](messages.md#business-scoped-user-ids-bsuid) |
+| `to_parent_user_id` | Their parent BSUID, present only if enrolled |
+| `message` | The echoed `Message::*`, dispatched by `type` |
+
+`Echo#message` goes through the same `Message.deserialize` dispatcher as
+[`messages`](messages.md), so an echo is a fully typed `Message::Text`, `Message::Image`,
+`Message::Revoke`, `Message::Edit`, and so on — with the same accessors.
+
+Why a wrapper rather than three more accessors on `Message::Base`? Because an *inbound*
+message can never carry a recipient. Putting `to`/`to_user_id`/`to_parent_user_id` on the
+envelope shared by every message type would hand fifteen classes three permanently-`nil`
+readers, and would turn the `NoMethodError` that currently tells you `message.to` is
+meaningless into a silent `nil`.
 
 ## Handling it
 
 ```ruby
 when "smb_message_echoes"
   change.value.message_echoes.each do |echo|
-    Conversation.for(echo.from).messages.create!(
-      wamid: echo.id, direction: :outbound, source: :business_app, body: echo.try(:body)
+    # The customer may have no phone number; the BSUID always identifies them
+    conversation = Conversation.for(bsuid: echo.to_user_id, wa_id: echo.to)
+
+    conversation.messages.create!(
+      wamid: echo.message.id,
+      direction: :outbound,
+      source: :business_app,
+      body: echo.message.try(:body)
     )
   end
 ```
 
-Note `from` is *your* business number here, not the customer's — these are messages
-you sent.
+Note `echo.message.from` is *your* business number, not the customer's — these are
+messages you sent. The customer is on `echo.to*`.
+
+> **Changed in 0.6.0.** `message_echoes` used to be an `Array<Message::*>` directly;
+> each entry is now an `Echo` wrapping that message, so `echo.body` becomes
+> `echo.message.body`. The wrapper is what carries the new recipient identifiers.
 
-> **Moderate confidence on structure, low on the key name.** Meta states these mirror
-> the standard message shape, which is why `Message.deserialize` is reused, but the
-> exact `message_echoes` key is unverified. Validate against a real payload before
-> depending on it in production.
+> The `message_echoes` key itself is still inferred from the field name rather than
+> confirmed by a published example — hence `raw`, so a drifted key leaves a trace.
 
 ---
 
-**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

data/docs/webhooks/user_id_update.md

@@ -0,0 +1,84 @@
+# `user_id_update`
+
+A WhatsApp user's business-scoped user ID (BSUID) changed — most commonly because they
+changed their phone number (see the [`system` message type's `user_changed_user_id`
+event](messages.md#system) for the same event surfaced on the `messages` field).
+
+`Whatsapp::Webhook::UserIdUpdate` · confidence: **confirmed** — Meta publishes a real
+JSON example
+
+## Payload
+
+```json
+{ "field": "user_id_update",
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "contacts": [{ "profile": { "name": "Jane Doe" }, "wa_id": "16505551234" }],
+    "user_id_update": [
+      {
+        "wa_id": "16505551234",
+        "detail": "User id for Jane Doe has been updated.",
+        "user_id": { "previous": "US.OLD", "current": "US.NEW" },
+        "parent_user_id": { "previous": "US.ENT.OLD", "current": "US.ENT.NEW" },
+        "timestamp": "1750030073"
+      }
+    ]
+  } }
+```
+
+`parent_user_id` is present only if you have enrolled in [parent
+BSUIDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#parent-business-scoped-user-ids).
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `messaging_product` | `"whatsapp"` |
+| `metadata` | `Metadata` — `display_phone_number`, `phone_number_id` |
+| `contacts` | `Array<Contact>` — the [same BSUID-aware `Contact`](messages.md#business-scoped-user-ids-bsuid) used by `messages` |
+| `updates` | `Array<UserIdUpdate::Entry>` |
+
+### `Entry`
+
+| Accessor | Meaning |
+| --- | --- |
+| `wa_id` | The user's phone number, if available |
+| `detail` | Human-readable description of the change |
+| `user_id` | `UserIdUpdate::IdChange` or `nil` — the user's previous and current BSUID |
+| `parent_user_id` | `UserIdUpdate::IdChange` or `nil` — previous and current parent BSUID |
+| `timestamp` | Unix seconds, as a String |
+
+### `IdChange`
+
+`Whatsapp::Webhook::UserIdUpdate::IdChange` — a sibling of `Entry`, not nested inside it.
+One class serves both `user_id` and `parent_user_id`, since they are the same shape, and
+each is `nil` rather than an all-nil object when its key is absent.
+
+| Accessor | Meaning |
+| --- | --- |
+| `previous` | The BSUID before the change |
+| `current` | The BSUID after the change |
+
+## Handling it
+
+```ruby
+when "user_id_update"
+  change.value.updates.each do |update|
+    next unless update.user_id  # nil when the entry carries only a parent BSUID change
+
+    user = User.find_by(bsuid: update.user_id.previous)
+    next Rails.logger.warn("[whatsapp] unknown BSUID #{update.user_id.previous}") unless user
+
+    user.update!(bsuid: update.user_id.current)
+  end
+```
+
+Report a miss rather than letting `&.update!` swallow it — a rotation you never applied
+leaves you writing to a dead BSUID with no diagnostics. Log or alert; do not `raise`, or
+Meta will retry a request that can never succeed. `change.value.raw` carries the untouched
+payload if you need to see what actually arrived.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#user_id_update-webhooks>

data/docs/webhooks/user_preferences.md

@@ -4,45 +4,84 @@ A customer changed their marketing preferences — most importantly, opting **ou
 Respecting this is not optional: continuing to send marketing to someone who stopped
 you damages your quality rating and breaches Meta's policy.
 
-`Whatsapp::Webhook::UserPreferences` · confidence: **moderate**
+`Whatsapp::Webhook::UserPreferences` · confidence: **confirmed**
 
 ## Payload
 
 ```json
 { "field": "user_preferences",
-  "value": { "wa_id": "16505551234",
-             "detail": "stopped marketing messages",
-             "value": "stop",
-             "timestamp": "1750263773" } }
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "contacts": [
+      { "profile": { "name": "Pablo M.", "username": "pablomorales" },
+        "wa_id": "16505551234",
+        "user_id": "US.13491208655302741918" }
+    ],
+    "user_preferences": [
+      { "wa_id": "16505551234",
+        "user_id": "US.13491208655302741918",
+        "detail": "User requested to stop marketing messages",
+        "category": "marketing_messages",
+        "value": "stop",
+        "timestamp": 1750030073 }
+    ] } }
 ```
 
-## Accessors
+Note the nesting: the entries sit under a repeat of the field's own name, the same shape
+[`user_id_update`](user_id_update.md) uses.
+
+## Value accessors
+
+| Accessor | Type |
+| --- | --- |
+| `messaging_product` | `String` — always `"whatsapp"` |
+| `metadata` | `Metadata` — the business phone number this arrived on |
+| `contacts` | `Array<Contact>` — `profile_name`, `username`, `wa_id`, `user_id`, `parent_user_id` |
+| `preferences` | `Array<UserPreferences::Entry>` |
+| `raw` | The untouched `value` hash |
+
+## Entry accessors
 
 | Accessor | Meaning |
 | --- | --- |
-| `wa_id` | The customer's WhatsApp ID |
+| `wa_id` | The customer's phone number, or `nil` once they adopt a username |
+| `user_id` | Their [BSUID](messages.md#business-scoped-user-ids-bsuid) — the identifier that is always there |
+| `parent_user_id` | Their parent BSUID, present only if enrolled |
 | `detail` | Human-readable description |
+| `category` | `"marketing_messages"` is the only documented value |
 | `value` | `"stop"` or `"resume"` |
-| `timestamp` | Unix seconds, as a String |
+| `timestamp` | Unix seconds. Meta sends a **number** here, unlike the String timestamps on `messages` |
+
+> `Entry#value` sits inside the change's own `value` hash, so the full path reads
+> `change.value.preferences.first.value`. Meta's naming, not ours.
 
 ## Handling it
 
+An opt-out from a username adopter may carry no phone number at all, so key off the
+BSUID and fall back to `wa_id` — not the other way round:
+
 ```ruby
 when "user_preferences"
-  pref = change.value
+  change.value.preferences.each do |preference|
+    customer =
+      Customer.find_by(bsuid: preference.user_id) ||
+      Customer.find_by(wa_id: preference.wa_id)
 
-  Customer
-    .find_by(wa_id: pref.wa_id)
-    &.update!(marketing_opt_in: pref.value != "stop",
-              marketing_opt_in_changed_at: Time.at(pref.timestamp.to_i))
+    customer&.update!(
+      marketing_opt_in: preference.value != "stop",
+      marketing_opt_in_changed_at: Time.at(preference.timestamp.to_i)
+    )
+  end
 ```
 
 Gate every `MARKETING`-category [template send](../messages/template.md) on this flag.
 `UTILITY` and `AUTHENTICATION` templates are unaffected.
 
-> **Best-effort schema.** Meta publishes no JSON example for this field. Validate
-> against a real payload before depending on it in production.
+> **Changed in 0.6.0.** This field used to expose `wa_id`/`detail`/`value`/`timestamp`
+> directly on `change.value`. Meta nests them one level deeper than the gem assumed, so
+> those accessors could never return anything but `nil`; they are now on `Entry`.
 
 ---
 
-**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module ContactBook
+      # Deletes one user's entry from your contact book.
+      #
+      # A validated instance rather than a bare class method: Meta documents a rule this
+      # can check — parent BSUIDs are not accepted here — and the edge is rate limited, so
+      # a request that was never going to be accepted should not be spent.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+      class Delete
+        include ActiveModel::Validations
+        extend ResponseHandling
+        extend Transport
+
+        module Defaults
+          EDGE = "contact_book"
+          MESSAGING_PRODUCT = "whatsapp"
+          # A parent BSUID carries an extra segment (`US.ENT.118...`) where a standard one
+          # has just the country code and identifier (`US.134...`), so counting separators
+          # distinguishes them without asserting a country-code grammar Meta has not
+          # published. See {#validate_standard_bsuid}.
+          PARENT_SEPARATOR_COUNT = 1
+        end
+
+        # @!attribute [rw] bsuid
+        #   @return [String] The business-scoped user ID whose entry to remove.
+        attr_accessor :bsuid
+
+        validate :validate_standard_bsuid
+        validates :bsuid, presence: true
+
+        # @param bsuid [String] The user's standard BSUID, e.g.
+        #   `"US.13491208655302741918"`. Must belong to the same business portfolio as the
+        #   phone number — Meta checks that server-side, since it is account state this gem
+        #   cannot see. Parent BSUIDs are not supported and are rejected locally.
+        # @raise [ActiveModel::ValidationError] if the BSUID is missing or looks like a parent.
+        def initialize(bsuid:)
+          @bsuid = bsuid
+
+          validate!
+        end
+
+        # @return [Hash] The query parameters. Sent as a query string rather than a body
+        #   because the edge is a `DELETE` — the one action in this directory whose
+        #   `#serialize` is not a JSON payload. `messaging_product` is documented required,
+        #   so it is always sent.
+        def serialize
+          { messaging_product: Defaults::MESSAGING_PRODUCT, bsuid: }
+        end
+
+        class << self
+          # @example Forget a user who asked to be forgotten
+          #   ContactBook::Delete.call(bsuid: "US.13491208655302741918")
+          # @param client [Whatsapp::Client] The WhatsApp client instance.
+          # @param bsuid [String] See {#initialize}.
+          # @return [Deletion] Whose `deleted` is `false` if no entry existed.
+          # @raise [ActiveModel::ValidationError] if the BSUID is missing or looks like a parent.
+          # @raise [Error] if no phone number ID is configured, or the request fails.
+          def call(bsuid:, client: Client.new)
+            params = new(bsuid:).serialize
+            response = client.connection.delete(edge_path(client, Defaults::EDGE), params:)
+
+            Deletion.deserialize(
+              parse_json(handle_response!(response, error_class: Error, action: "delete contact book entry"))
+            )
+          end
+        end
+
+      private
+
+        # Meta states plainly that parent BSUIDs are rejected here, and this release hands
+        # callers `user_id` and `parent_user_id` side by side on half a dozen webhook
+        # classes, so mixing them up is the predictable mistake. Detected by segment count
+        # rather than by matching `ENT`, which would bet that `ENT` is the only marker Meta
+        # will ever insert — an inference either way, so the weaker one wins.
+        # @return [void]
+        def validate_standard_bsuid
+          return if bsuid.nil? || bsuid.to_s.count(".") <= Defaults::PARENT_SEPARATOR_COUNT
+
+          errors.add(:bsuid, "looks like a parent BSUID; the contact book accepts standard BSUIDs only")
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/business_phone_number/contact_book/deletion.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    module ContactBook
+      # The result of a {Delete}: whether the request worked, and whether it found anything.
+      #
+      # Its own class rather than {BusinessPhoneNumber::Response}, which carries only
+      # `success` (plus the `id` {VerifyCode} sets). `deleted` is a second, independent
+      # boolean that changes how `success` reads — `success: true, deleted: false` means
+      # the request was fine and there was simply no entry — and collapsing the two would
+      # lose that. Adding it to the class every onboarding action returns would also put a
+      # field on five actions that can never set it.
+      class Deletion
+        # @!attribute [rw] messaging_product
+        #   @return [String, nil] Always `"whatsapp"`.
+        attr_accessor :messaging_product
+
+        # @!attribute [rw] success
+        #   @return [Boolean] Whether the request was processed.
+        attr_accessor :success
+
+        # @!attribute [rw] deleted
+        #   @return [Boolean] Whether an entry existed and was removed. `false` alongside a
+        #     `true` {#success} means there was nothing stored for that BSUID — not a failure.
+        attr_accessor :deleted
+
+        def initialize(messaging_product: nil, success: false, deleted: false)
+          @messaging_product = messaging_product
+          @success = success
+          @deleted = deleted
+        end
+
+        class << self
+          # @param response [Hash, nil] The parsed response body.
+          # @return [Deletion]
+          def deserialize(response)
+            response ||= {}
+
+            new(
+              messaging_product: response["messaging_product"],
+              success: response["success"] == true,
+              deleted: response["deleted"] == true
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module BusinessPhoneNumber
+    # Removes a stored user contact from your **contact book** — the store Meta keeps of
+    # the phone numbers and BSUIDs you have interacted with, and uses to keep putting a
+    # user's phone number in your webhooks after they adopt a username.
+    #
+    # Addressed as a `phone_id` edge (`DELETE /{phone_id}/contact_book`), so it reuses
+    # {BusinessPhoneNumber::Transport} unchanged, like {Profile} and {Username}. It sits
+    # here rather than in a top-level module for two reasons: this directory is the
+    # administration of one phone number, as opposed to {Whatsapp::Media} and
+    # {Whatsapp::Messages}, which are the traffic itself; and a top-level module would
+    # need its own error class for a single endpoint, where living here means one
+    # `rescue BusinessPhoneNumber::Error` still covers the whole directory.
+    #
+    # Note the asymmetry between how it is addressed and what it affects: the edge is on
+    # one phone number, but the contact book is scoped to the whole **business portfolio**,
+    # so a deletion removes that user's phone number from webhooks for *every* number in
+    # the portfolio. See `docs/business_phone_number/contact_book.md`.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+    module ContactBook
+    end
+  end
+end

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

@@ -2,10 +2,10 @@
 
 module Whatsapp
   module BusinessPhoneNumber
-    # The one piece shared by {Register}, {Deregister}, {RequestCode}, {VerifyCode}, and
-    # {Profile}: all of them address a phone-number-scoped edge, 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).
+    # The one piece shared by {Register}, {Deregister}, {RequestCode}, {VerifyCode},
+    # {Profile}, {Username}, and {ContactBook}: all of them address a phone-number-scoped
+    # edge, 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).
     #
     # The guard itself and its message live in {Whatsapp::PathBuilding}, shared with every
     # other ID-scoped feature; what stays here is the ID this module addresses.
@@ -16,7 +16,8 @@ module Whatsapp
 
       # @param client [Whatsapp::Client]
       # @param action [String] The edge to address ("register", "deregister",
-      #   "request_code", "verify_code", or "whatsapp_business_profile").
+      #   "request_code", "verify_code", "whatsapp_business_profile", "username",
+      #   "username_suggestions", or "contact_book").
       # @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)