ruby-whatsapp 0.4.2 → 0.6.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fa9a4e0fe14f7868639ddb3fe8285801aba43d4c92ae5decf7f8d7e5e80882e
-  data.tar.gz: 534f91cc1841a1be0b9740619360287dcc0ee9cfc6d82b3ba12fde421cdbc81e
+  metadata.gz: 5c33c221aee102d5b25468617f808a4f91c2e54a5659922576cd542dff802458
+  data.tar.gz: 10d24cb87f52e82ba182b4360bd25c6e2ae1fe9b8bb78d4d6141c17b2dc6c91f
 SHA512:
-  metadata.gz: dd34f6bd15f531af85b31feeeb767290abcb82c291b03cbd02398ce310cb752140c31ba9e1b37b5e36db796c4992126be2dadc12b1041a2ab67f114c71a20a6c
-  data.tar.gz: 1a5afbd7d50790859e60340e87856574f7b53f6c647191c5b7d639023efd1e6129e2f37010c6f513dbc429aaa4b09d3ac87903dca86dff0e8d6f0cce4dcf20bd
+  metadata.gz: bd104f12c9ec44b4b07e5912f18e98ae4646a4eb1f51869b27dcc978b76ee06d385e81a6d41ce449b96460f08e0d2ddfb56b4d57ce410d3493f45e243f71883c
+  data.tar.gz: 79366a3af17543676a403b43b23e2df31b5c4219f2b440a2a438053ee8fa651f6513651e85b237693f30749afe085879d948c828a6090337c5e14508398ba7a3

data/CHANGELOG.md

@@ -1,3 +1,161 @@
+## [0.6.2] - 2026-10-22
+
+### Fixed
+
+- **A single-section list message no longer needs a section title.** Meta requires
+  `sections[].title` only when a list has more than one section, but
+  `Interactive::ListButtons::Section` demanded one always — `title:` was a required
+  keyword with a presence validation — so a valid single-section list without a title
+  could not be built. `Section` now takes `title:` as optional (still max 24 characters)
+  and omits the key from the payload when it is absent, and `ListButtons` enforces Meta's
+  actual rule: with two or more sections, every one must have a title, otherwise it fails
+  with "Sections must each have a title when there is more than one section". A blank
+  title (`""` or whitespace) is treated as absent — omitted from a single section, and
+  counted as missing when there are several — rather than sent as an empty heading.
+
+## [0.6.1] - 2026-10-21
+
+### Added
+
+- **`Whatsapp::Schedule`** — `List` and `Create` wrap a WhatsApp Business Account's
+  campaign schedules (`/{waba_id}/schedules`): an approved template sent to an audience
+  at a Unix `delivery_time`. `Create` checks all six documented-required fields before
+  the request, and requires `delivery_time` to be an integer. It checks nothing else,
+  since Meta publishes no length limits and no rule that the time must be in the future.
+  `List` takes `fields`, `limit`, `after`, and `before`, and returns an `Enumerable`
+  `Response::Collection` of `Response::Node`s with `next_cursor`. Its paging reuses
+  `MessageTemplates::Response::Paging` rather than duplicating it. `Node#status` stays
+  the raw string, with `Statuses` constants and `scheduled?`/`sending?`/`completed?`/
+  `failed?` for comparison. Meta's default `fields` omit `id`, so
+  `List::Fields::ALL` is offered to ask for it. Every failure raises the new
+  `Whatsapp::Schedule::Error`.
+
+## [0.6.0] - 2026-10-20
+
+Completes the Business-Scoped User ID (BSUID) work that 0.5.0 began. 0.5.0 covered the
+inbound webhook half; this covers the send side, the four webhook fields Meta's BSUID
+documentation changed but 0.5.0 did not touch, the two new phone-number APIs, and the
+button that asks a username adopter for their phone number back.
+
+### Fixed
+
+- **`Whatsapp::Webhook::UserPreferences` and `::History` could never populate.** Both read
+  their payload one nesting level too high — `value["wa_id"]` and `value["metadata"]`,
+  where Meta nests entries under a repeat of the field's own name
+  (`value["user_preferences"][]`, `value["history"][]`), the convention `UserIdUpdate`
+  already followed. Every accessor on both classes returned `nil` or `[]` for a real
+  payload. The BSUID documentation is the first published example for either field, which
+  is what caught it; both specs now carry those payloads verbatim as regression guards.
+  **Breaking:** `UserPreferences`' `wa_id`/`detail`/`value`/`timestamp` move to
+  `change.value.preferences.first.*`, and `History#threads` moves to
+  `chunks.first.threads` — `#phase`/`#chunk_order`/`#progress` keep their names and now
+  actually work.
+- **Corrected `Status#recipient_user_id`'s documented behavior.** The docs and one spec
+  claimed it appears only when you addressed a message to a BSUID. Per Meta's May 4, 2026
+  correction it is sent on _every_ status however the message was addressed, and omitted
+  only on a `failed` status for a message sent to a phone number. The deserializer was
+  always right; the claim around it was not. Also newly documented: the status webhook's
+  `contacts[]` accompanies `sent`/`delivered`/`read` but is omitted entirely for `failed`,
+  and `contacts[].profile.username` is omitted on `sent`.
+
+### Added
+
+- **Send to a BSUID.** `Whatsapp::Messages::Base` gains `recipient` alongside `to`, so a
+  BSUID read off a webhook can be replied to without ever knowing the phone number. Supply
+  either or both — Meta gives `to` precedence — and at least one is required, which is now
+  a validation rather than a missing-keyword `ArgumentError`. Because all 13 message kinds
+  already forwarded with `super(**)`, and the `KINDS` factory splats `**payload`, this
+  reached every kind and `send_<kind>!` method without touching either. `envelope` compacts
+  the recipient pair only, so an omitted identifier is left out rather than sent as null.
+  `Messages::Response::Contacts` gains `user_id` and makes `wa_id` optional to match —
+  noting that Meta omits `user_id` whenever the message went to a phone number, _including_
+  when both identifiers were supplied, so a nil `user_id` does not mean the recipient has
+  no BSUID. The BSUID is deliberately not format-checked: its canonical source is this
+  gem's own webhook side, which keeps it a raw string, and rejecting on the way out what
+  was accepted on the way in would be the worst possible asymmetry.
+- **`Whatsapp::BusinessPhoneNumber::Username`** — `Get`, `Claim`, `Delete`, and `Suggest`
+  wrap the searchable `@name` a WhatsApp user can find a number by. Four endpoints, three
+  wire shapes, two new value classes: `Username::Details` covers both `Get` and `Claim`
+  since `{status}` is a subset of `{username, status}`, `Username::Suggestions` owns the
+  doubly-wrapped suggestions envelope and is `Enumerable`, and `Delete` reuses the existing
+  `BusinessPhoneNumber::Response` for its bare `{success}`. Every one of Meta's published
+  username format rules is checked before the request, since the edge is rate limited — bar
+  the domain-suffix rule, whose published list ends in "and so on", so a suffix outside the
+  documented ten is left to the API. Mixed case is downcased rather than rejected, because
+  Meta compares usernames case-insensitively. `Details::Statuses` deliberately omits
+  `"deleted"`: that value reaches you only through the `business_username_updates` webhook,
+  and a write-side enum must not name a state no endpoint here can return.
+- **`Whatsapp::BusinessPhoneNumber::ContactBook::Delete`** — removes a stored user contact
+  from the store Meta uses to keep putting a username adopter's phone number in your
+  webhooks. Returns its own `ContactBook::Deletion` rather than the shared `Response`,
+  because `deleted` is a second independent boolean that changes how `success` reads:
+  `success: true, deleted: false` means the request was fine and there was simply nothing
+  stored. Rejects a parent BSUID locally — the one BSUID-shape assertion in the gem, and
+  safe because it tests for a documented extra segment rather than a country-code grammar
+  Meta has never published. Both new namespaces reuse `BusinessPhoneNumber::Transport`
+  unchanged; there are still only two transports in that directory, three sub-namespaces
+  later.
+- **`REQUEST_CONTACT_INFO`**, in both forms: a `MessageTemplates::Button` type for opening
+  a conversation with the ask, and a `Messages::Interactive` action kind
+  (`type: :request_contact_info`) for making it inside the 24-hour service window. Both
+  were previously recorded as deliberately absent for want of a published schema; the BSUID
+  documentation publishes one. The template button's `UTILITY`/`MARKETING` restriction lives
+  in `ComponentSet` alongside the other cross-component rules, and is checked by drilling
+  into the `BUTTONS` component rather than through `CATEGORY_RESTRICTED_TYPES`, which keys
+  on component types. The interactive kind is the first with nothing for a caller to
+  supply, so `ACTION_TYPES` gained a `parameterless` flag and `action:` is no longer
+  required for it.
+- **Four more webhook fields brought up to their published schemas.**
+  `Whatsapp::Webhook::SmbMessageEchoes` gains a value-level `contacts` array and wraps each
+  echo in a new `SmbMessageEchoes::Echo` carrying `to`/`to_user_id`/`to_parent_user_id` —
+  a wrapper rather than three more accessors on `Message::Base`, because an inbound message
+  can never carry a recipient, and three permanently-nil readers on fifteen classes would
+  turn a helpful `NoMethodError` into a silent `nil`. **Breaking:** `echo.body` becomes
+  `echo.message.body`. `SmbAppStateSync` gains `messaging_product`/`metadata` and types its
+  synced contact as `SmbAppStateSync::Contact` (`full_name`, `first_name`, `phone_number`,
+  `user_id`, `parent_user_id`, `username`), with the per-entry `metadata.timestamp`
+  flattened onto the entry. **Breaking:** `sync.contact["phone_number"]` becomes
+  `sync.contact.phone_number`, and an entry with no contact returns `nil` rather than `{}`.
+  All four fields, plus `UserPreferences` and `History`, now expose `raw`.
+- **`revoke` and `edit` message types**, registered in `Message::MESSAGE_TYPES` rather than
+  falling through to `Message::Unknown`. `Revoke` carries `original_message_id`; `Edit`
+  carries that plus a nested `message` recursed back through `Message.deserialize`, so an
+  edited image behaves exactly like an inbound one — content only, so the nested payload's
+  own `from`/`id`/`timestamp` read `nil`. Both also arrive through `smb_message_echoes`
+  when the business edits or revokes from the WhatsApp Business app.
+- **`Message::Base#group_id`**, set when an inbound message came from a group chat.
+  Extracted once in `common_attributes`, so every message type has it. The matching
+  group-status identifiers on `Status` are deliberately _not_ added, and are now recorded
+  under a new "Not implemented" section in `lib/ruby/whatsapp/webhook/CLAUDE.md` along with
+  the `calls` and `group_participants_update` fields: they only appear on a status for a
+  message sent to a group, and this gem wraps no Groups API, so it can never receive one.
+
+## [0.5.0] - 2026-08-24
+
+- Add Business-Scoped User ID (BSUID) support to inbound webhooks: Meta is rolling out
+  WhatsApp usernames, after which a user's phone number can be omitted from a webhook
+  entirely, leaving their BSUID (`user_id`, e.g. `"US.13491208655302741918"`) as the only
+  stable identifier. `Whatsapp::Webhook::Contact`, `Message::Base` (and therefore every
+  message type: `Text`, the `Media` family, `Location`, `Contacts`, `Interactive`,
+  `Button`, `Order`, `System`, `Reaction`, `Unknown`), and `Status` now all carry
+  `user_id`/`from_user_id`/`recipient_user_id`, alongside `parent_user_id` variants for
+  businesses enrolled in [parent BSUIDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#parent-business-scoped-user-ids).
+  `Contact` additionally gains `username`. `Message::Contacts::Contact` gains `vcard`/
+  `origin` for cards shared via a `REQUEST_CONTACT_INFO` button, and `Message::System`
+  gains its own `user_id`/`parent_user_id` for the customer's new BSUID after a
+  `user_changed_user_id` event. `Message::Context` carries `from_user_id`/
+  `from_parent_user_id` too, so a quoted reply still identifies its sender once the phone
+  number is gone. `from_user_id`/`from_parent_user_id` are extracted once in
+  `Message::Base.common_attributes`, so every message type gained them without any
+  per-type changes.
+- Add two new confirmed webhook fields from the same BSUID rollout:
+  `Whatsapp::Webhook::UserIdUpdate` (a user's BSUID changed — composes the existing
+  `Metadata`/`Contact` plus `Entry`/`IdChange` for the `{previous, current}` change
+  records) and `Whatsapp::Webhook::BusinessUsernameUpdates` (a business phone number's
+  username moved between `approved`/`reserved`/`deleted`). Both also expose `raw`, the
+  untouched `value` hash, so a payload whose shape differs from Meta's published example
+  is still recoverable rather than silently deserializing to an empty object.
+
 ## [0.4.2] - 2026-08-19
 
 - Add WhatsApp Business Profile management: `Whatsapp::BusinessPhoneNumber::Profile::Get` reads the public card a WhatsApp user sees before they reply — about text, description, address, email, websites, industry vertical, and profile picture URL — and `::Profile::Update` writes them. Unlike `::Account`, this is not an exception to the module's `phone_id` rule: Meta exposes the profile as an edge on the phone number itself (`GET`/`POST /{phone_id}/whatsapp_business_profile`), so both actions reuse the existing `BusinessPhoneNumber::Transport#edge_path` unchanged — no new transport, no new ID to configure. `Update` validates the 21-value `Profile::Verticals` enum and Meta's documented limits (about 139, address 256, description 512, email 128 characters, at most 2 websites) before any request is made, and compacts omitted fields out of the body rather than sending null — which Meta reads as an instruction to blank them — with an empty `websites` array surviving on purpose, since that is how the list is cleared. `email`'s format is deliberately left to Meta, which validates it server-side; a regex here would reject valid exotic addresses. It reuses the existing `BusinessPhoneNumber::Response`, since the endpoint answers a bare `{success}`.

data/README.md

@@ -48,6 +48,7 @@ onboarding, and reading or updating the business account itself.
 - [🔔 Webhooks](#-webhooks)
 - [📷 Media](#-media)
 - [🔌 Subscribed Apps](#-subscribed-apps)
+- [📅 Scheduling Campaigns](#-scheduling-campaigns)
 - [📞 Business Phone Numbers](#-business-phone-numbers)
 - [🚨 Errors](#-errors)
 - [🧩 Compatibility](#-compatibility)
@@ -69,9 +70,14 @@ onboarding, and reading or updating the business account itself.
 - **Secrets stay out of logs.** `api_key`, `app_secret`, and `verify_token` are
   redacted from every `#inspect`, including credentials in transit like a
   registration PIN.
-- **Inbound webhooks, fully typed.** An object tree for all 19 documented Meta
+- **Inbound webhooks, fully typed.** An object tree for all 21 documented Meta
   notification fields, plus HMAC signature verification and a Rails controller
   generator.
+- **Usernames and BSUIDs, both directions.** Once a WhatsApp user adopts a username,
+  their phone number can vanish from your payloads. Inbound notifications still identify
+  their sender through a Business-Scoped User ID, and `recipient:` sends straight back to
+  one — so a BSUID read off a webhook can be replied to without ever knowing the number.
+  Your own business username is managed too, along with Meta's contact book.
 - **Persistent HTTP connections** via `HTTP.persistent`, reused across requests, with
   pluggable logging.
 - **Four runtime dependencies**, no Rails requirement. Rails integration activates
@@ -120,13 +126,16 @@ end
 phone_id  ──►  Messages · Media · BusinessPhoneNumber
                permission: whatsapp_business_messaging
 
-waba_id   ──►  MessageTemplates · SubscribedApp · BusinessPhoneNumber::Account
+waba_id   ──►  MessageTemplates · SubscribedApp · Schedule · BusinessPhoneNumber::Account
                permission: whatsapp_business_management
 ```
 
 `BusinessPhoneNumber` appears on both sides: its onboarding actions address a phone
 number, its `Account` actions the account that number belongs to.
 
+`Schedule`'s permission is an assumption: Meta's Schedules reference names none, so it
+is grouped under `whatsapp_business_management` only because it addresses the WABA.
+
 `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.
 
@@ -155,9 +164,10 @@ response.contacts.first.wa_id  # => "15551234567"
 | [**Configuration**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/configuration.md) | Credentials, the client, connection reuse, instrumentation |
 | [**Messages**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/README.md) | Every message kind, one page each, with exact payloads |
 | [**Message Templates**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/message_templates/README.md) | Creating and managing templates: standard, auth, carousel, offers, library |
-| [**Webhooks**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/webhooks/README.md) | Install, verification, signatures, and all 19 notification fields |
+| [**Webhooks**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/webhooks/README.md) | Install, verification, signatures, and all 21 notification fields |
 | [**Media**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/media/README.md) | Upload, download, delete, and the token-safety allowlist |
 | [**Subscribed Apps**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/subscribed_app/README.md) | Turning webhook delivery on and off for an account |
+| [**Campaign Schedules**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/schedule/README.md) | Sending an approved template to an audience at a set time |
 | [**Business Phone Numbers**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/README.md) | Onboarding: request code → verify → register |
 | [**Business Account**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/account.md) | Reading and updating the account: name, timezone, review status |
 | [**Business Profile**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/profile.md) | The profile a user sees: about, description, address, vertical, picture |
@@ -167,7 +177,13 @@ Or start at the [documentation index](https://github.com/saleszera/ruby-whatsapp
 
 ## 💬 Sending Messages
 
-Every registered kind gets its own `Whatsapp::Messages.send_<kind>!` class method:
+Every registered kind gets its own `Whatsapp::Messages.send_<kind>!` class method.
+Address a recipient by phone number, by BSUID, or both — at least one is required:
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi")                   # phone number
+Whatsapp::Messages.send_text!(recipient: "US.13491208655302741918", body: "Hi") # BSUID
+```
 
 ```ruby
 Whatsapp::Messages.send_interactive!(
@@ -245,7 +261,7 @@ plus list, find, update, and delete.
 
 ## 🔔 Webhooks
 
-Meta pushes inbound messages, delivery statuses, and ~18 other notification types to a
+Meta pushes inbound messages, delivery statuses, and 20 other notification types to a
 callback URL you register. Inside a Rails app:
 
 ```bash
@@ -282,8 +298,9 @@ message.id      # => "wamid.HBg..."
 message.body    # => "Does it come in another color?"
 ```
 
-All 19 documented fields get a class. Only `messages` has a Meta-published schema; the
-other 18 are best-effort and flagged as such, per field.
+All 21 documented fields get a class. `messages`, `user_id_update`, and
+`business_username_updates`, `user_preferences`, and `history` have a Meta-published schema; the other 16 are best-effort
+and flagged as such, per field.
 
 → **[Webhooks](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/webhooks/README.md)**
 · [inbound messages & statuses](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/webhooks/messages.md)
@@ -321,6 +338,26 @@ Tech Providers routing several accounts to different callback URLs pass an
 
 → **[Subscribed apps](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/subscribed_app/README.md)**
 
+## 📅 Scheduling Campaigns
+
+Send an approved template to an audience at a set time, and list what is scheduled:
+
+```ruby
+Whatsapp::Schedule::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                                                            # => "9876543210"
+
+page = Whatsapp::Schedule::List.call(fields: Whatsapp::Schedule::List::Fields::ALL, limit: 50)
+page.select(&:scheduled?).map(&:name)                           # => ["Black Friday"]
+Whatsapp::Schedule::List.call(after: page.next_cursor) if page.next_cursor
+```
+
+Meta's default fields leave out `id`, so ask for it with `fields:` when you need it.
+
+→ **[Campaign schedules](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/schedule/README.md)**
+
 ## 📞 Business Phone Numbers
 
 A phone number is unusable with Cloud API until it is **registered** — the prerequisite
@@ -372,9 +409,34 @@ Whatsapp::BusinessPhoneNumber::Profile::Update.call(
 Character limits, the 21-value vertical enum, and the two-website cap are all checked
 before the request goes out.
 
+The **business username** — the searchable `@name` a user can find you by — is managed on
+the same `phone_id`:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Username::Suggest.call.to_a
+# => ["jaspersmarket", "jaspers_market"]   — names Meta reserved for you
+
+Whatsapp::BusinessPhoneNumber::Username::Claim.call(username: "jaspersmarket").reserved?
+# => true, until Meta makes the feature generally available
+
+Whatsapp::BusinessPhoneNumber::Username::Get.call.approved?  # => false, for now
+```
+
+Every one of Meta's format rules is checked locally first, so a name that was never going
+to be accepted doesn't cost you a rate-limited attempt. And Meta's **contact book** — the
+store that keeps putting a username adopter's phone number in your webhooks — can be
+pruned:
+
+```ruby
+result = Whatsapp::BusinessPhoneNumber::ContactBook::Delete.call(bsuid: "US.13491208655302741918")
+result.deleted  # => false means there was simply nothing stored, not a failure
+```
+
 → **[Business phone numbers](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/README.md)**
 · [the business account](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/account.md)
 · [the business profile](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/profile.md)
+· [business usernames](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/username.md)
+· [the contact book](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/contact_book.md)
 
 ## 🚨 Errors
 
@@ -388,6 +450,7 @@ you can rescue narrowly:
 | `Whatsapp::Media::MediaError` | Anything in `Media` |
 | `Whatsapp::MessageTemplates::TemplateError` | Anything in `MessageTemplates` |
 | `Whatsapp::SubscribedApp::Error` | Anything in `SubscribedApp` |
+| `Whatsapp::Schedule::Error` | Anything in `Schedule` |
 | `Whatsapp::BusinessPhoneNumber::Error` | Anything in `BusinessPhoneNumber`, including `Account` |
 
 Local validation failures raise `ActiveModel::ValidationError` instead — they happen at

data/docs/README.md

@@ -17,6 +17,7 @@ Full reference for [ruby-whatsapp](https://github.com/saleszera/ruby-whatsapp).
 | [messages/](messages/README.md) | Sending every message kind, the shared envelope, responses |
 | [media/](media/README.md) | Upload, download, delete, and the token-safety allowlist |
 | [message_templates/](message_templates/README.md) | Creating and managing the templates you send |
+| [schedule/](schedule/README.md) | Scheduling an approved template to go out to an audience later |
 
 ### Message kinds
 
@@ -49,7 +50,7 @@ Full reference for [ruby-whatsapp](https://github.com/saleszera/ruby-whatsapp).
 
 | Page | Covers |
 | --- | --- |
-| [webhooks/](webhooks/README.md) | Install, verification, signature, dispatch, all 19 notification fields |
+| [webhooks/](webhooks/README.md) | Install, verification, signature, dispatch, all 21 notification fields |
 | [webhooks/messages.md](webhooks/messages.md) | Inbound messages and delivery statuses — the one you'll actually use |
 
 ## Account administration
@@ -60,6 +61,8 @@ Full reference for [ruby-whatsapp](https://github.com/saleszera/ruby-whatsapp).
 | [business_phone_number/](business_phone_number/README.md) | Onboarding a phone number: request code → verify → register |
 | [business_phone_number/account.md](business_phone_number/account.md) | Reading and updating the business account itself |
 | [business_phone_number/profile.md](business_phone_number/profile.md) | Reading and updating the business profile a user sees |
+| [business_phone_number/username.md](business_phone_number/username.md) | Claiming and managing the searchable business username |
+| [business_phone_number/contact_book.md](business_phone_number/contact_book.md) | Removing a stored user contact from Meta's contact book |
 
 ## Reading order
 

data/docs/business_phone_number/README.md

@@ -27,6 +27,11 @@ Addresses your **phone number** (`phone_id`, not `waba_id`), like
 > and picture. Those address your phone number (`phone_id`), just like the four actions
 > below.
 
+> **Looking for the username?** [`Username::Get` / `Claim` / `Delete` / `Suggest`](username.md)
+> read and set the searchable `@name` a WhatsApp user can find the number by, and
+> [`ContactBook::Delete`](contact_book.md) forgets a stored user contact. Both address
+> `phone_id`, like the four actions below.
+
 > **Unrelated to [`SubscribedApp`](../subscribed_app/README.md).** That turns *webhook
 > delivery* on and off for a whole WhatsApp Business Account. This is per phone number
 > and has nothing to do with notifications.
@@ -55,6 +60,11 @@ Whatsapp::BusinessPhoneNumber::Deregister.call
 | [`Account::Update.call(name:, timezone_id:)`](account.md) | `POST /{waba_id}` | `Response` |
 | [`Profile::Get.call(fields:)`](profile.md) | `GET /{phone_id}/whatsapp_business_profile` | `Profile::Details` |
 | [`Profile::Update.call(**fields)`](profile.md) | `POST /{phone_id}/whatsapp_business_profile` | `Response` |
+| [`Username::Get.call`](username.md) | `GET /{phone_id}/username` | `Username::Details` |
+| [`Username::Claim.call(username:, transfer_action:)`](username.md) | `POST /{phone_id}/username` | `Username::Details` |
+| [`Username::Delete.call`](username.md) | `DELETE /{phone_id}/username` | `Response` |
+| [`Username::Suggest.call`](username.md) | `GET /{phone_id}/username_suggestions` | `Username::Suggestions` |
+| [`ContactBook::Delete.call(bsuid:)`](contact_book.md) | `DELETE /{phone_id}/contact_book` | `ContactBook::Deletion` |
 
 Every action accepts an optional `client:` and raises
 `Whatsapp::BusinessPhoneNumber::Error` if `phone_id` is missing or the API rejects the
@@ -221,7 +231,8 @@ Local validation failures raise `ActiveModel::ValidationError` before any reques
 ---
 
 **See also:** [Reading and updating the business account](account.md) ·
-[Reading and updating the business profile](profile.md)
+[Reading and updating the business profile](profile.md) ·
+[Business usernames](username.md) · [Contact book](contact_book.md)
 
 ---
 

data/docs/business_phone_number/contact_book.md

@@ -0,0 +1,90 @@
+# Contact book
+
+Meta keeps a **contact book** for your business portfolio: the phone numbers and BSUIDs
+of users you have interacted with. Its purpose is thread continuity — once a user adopts
+a username, Meta will keep putting their phone number in your webhooks if they are in
+your contact book, instead of leaving you with only their
+[BSUID](../webhooks/messages.md#business-scoped-user-ids-bsuid).
+
+The store itself is hosted by Meta and needs no integration work; entries appear on their
+own as you exchange messages or calls, and when a user taps a `REQUEST_CONTACT_INFO`
+button (which arrives as a [`contacts` message](../webhooks/messages.md#contacts) with
+`origin == "contact_request"`). This page covers the one operation Meta exposes on it:
+removing an entry.
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `ContactBook::Delete.call(bsuid:)` | `DELETE /{phone_id}/contact_book` | `ContactBook::Deletion` |
+
+## Deleting an entry
+
+```ruby
+result = Whatsapp::BusinessPhoneNumber::ContactBook::Delete.call(bsuid: "US.13491208655302741918")
+
+result.success  # => true  — the request was processed
+result.deleted  # => true  — an entry existed and is gone
+```
+
+The two booleans are independent, which is why this returns its own class rather than the
+shared `Response`:
+
+| `success` | `deleted` | Meaning |
+| --- | --- | --- |
+| `true` | `true` | An entry existed and was removed |
+| `true` | `false` | The request was fine; there was nothing stored for that BSUID |
+| `false` | — | The request was not processed |
+
+So `deleted == false` is **not** a failure. Check `success` for that, or rescue
+`Whatsapp::BusinessPhoneNumber::Error`.
+
+## What it affects
+
+> **The edge is on one phone number; the effect is portfolio-wide.** Contact books are
+> scoped to the business portfolio, so deleting an entry removes that user's phone number
+> from webhooks for **every** business phone number in the portfolio — not just the one
+> you addressed.
+
+And the consequence to expect: after a deletion, `wa_id`/`from` may start being omitted
+from your webhooks for that user, leaving their BSUID as the only identifier. That is the
+feature working, not a bug — but code that keys off `wa_id` will notice.
+
+The phone number can come back, without a new deletion, if the user messages or calls you
+again (or you them) within the 30-day window Meta caches, since that recreates the entry.
+
+## Rules
+
+- **Standard BSUIDs only.** Parent BSUIDs are not supported. Since this release hands you
+  `user_id` and `parent_user_id` side by side on half a dozen webhook classes, the mix-up
+  is easy, so it is caught locally:
+
+  ```ruby
+  Whatsapp::BusinessPhoneNumber::ContactBook::Delete.call(bsuid: "US.ENT.11815799212886844830")
+  # => ActiveModel::ValidationError: Bsuid looks like a parent BSUID;
+  #    the contact book accepts standard BSUIDs only
+  ```
+
+  Detected by segment count rather than by matching `ENT`, which would bet that `ENT` is
+  the only marker Meta will ever use.
+
+- **Same portfolio.** The BSUID must belong to the same portfolio as the phone number.
+  That is account state the gem cannot see, so it is left to the API — a mismatch comes
+  back as `Whatsapp::BusinessPhoneNumber::Error`.
+
+## Disabling the feature entirely
+
+The contact book can be turned off in **Meta Business Suite → Business settings →
+Business info**. Disabling it stops all storage and deletes everything already stored;
+re-enabling starts fresh, with no way to restore the old contents. There is no API for
+this, so it is not wrapped.
+
+## Not wrapped
+
+Meta documents only the delete on this edge. A future read or write belongs in this same
+namespace.
+
+---
+
+**See also:** [Business usernames](username.md) ·
+[BSUIDs in webhooks](../webhooks/messages.md#business-scoped-user-ids-bsuid)
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

data/docs/business_phone_number/username.md

@@ -0,0 +1,157 @@
+# Business usernames
+
+A business username is the searchable `@name` a WhatsApp user can find you by. It is the
+business half of Meta's usernames rollout — the user half is what makes
+[`recipient:`](../messages/README.md#addressing-to-recipient-or-both) necessary when
+sending.
+
+Two things it is **not**: it does not hide your business phone number in the app (unlike
+a *user* username, which hides theirs), and it does not replace your display name. When
+you have both, the display name shows first.
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Username::Get.call
+Whatsapp::BusinessPhoneNumber::Username::Claim.call(username: "jaspersmarket")
+Whatsapp::BusinessPhoneNumber::Username::Suggest.call
+Whatsapp::BusinessPhoneNumber::Username::Delete.call
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `Get.call` | `GET /{phone_id}/username` | `Username::Details` |
+| `Claim.call(username:, transfer_action:)` | `POST /{phone_id}/username` | `Username::Details` |
+| `Delete.call` | `DELETE /{phone_id}/username` | `Response` |
+| `Suggest.call` | `GET /{phone_id}/username_suggestions` | `Username::Suggestions` |
+
+## Reading the current username
+
+```ruby
+details = Whatsapp::BusinessPhoneNumber::Username::Get.call
+
+details.username   # => "jaspersmarket", or nil if the number has none
+details.status     # => "approved" | "reserved"
+details.approved?  # => true once it is visible to WhatsApp users
+details.reserved?  # => held for you, but not visible yet
+```
+
+`status` stays a raw String and is never validated on the way in, so a value Meta adds
+later still round-trips. Compare against `Details::Statuses::ALL` (`%w[approved reserved]`).
+
+## The lifecycle
+
+```
+Suggest  ──▶  Claim  ──▶  reserved  ──▶  approved
+(what Meta    (ask for               (Meta makes the feature
+ reserved      one)                   generally available)
+ for you)
+```
+
+`reserved` means the name is yours but not yet shown to users. It becomes `approved` on
+its own — you do not claim it twice. Either poll `Get`, or subscribe to the
+[`business_username_updates`](../webhooks/business_username_updates.md) webhook, which
+is the asynchronous counterpart to everything on this page.
+
+## Claiming one
+
+```ruby
+details = Whatsapp::BusinessPhoneNumber::Username::Claim.call(username: "jaspersmarket")
+details.status  # => "reserved"
+```
+
+`Claim` answers with a status only — `details.username` is `nil`, because you already
+hold the name you passed in.
+
+Starting with names Meta reserved for you gives a higher chance of approval:
+
+```ruby
+suggestions = Whatsapp::BusinessPhoneNumber::Username::Suggest.call
+
+suggestions.to_a    # => ["jaspersmarket", "jaspers_market"]
+suggestions.first   # => "jaspersmarket" — it's Enumerable
+
+Whatsapp::BusinessPhoneNumber::Username::Claim.call(username: suggestions.first)
+```
+
+### Format rules
+
+Checked locally, before any request — the edge is rate limited, so a name that was never
+going to be accepted should not cost you an attempt:
+
+| Rule | Rejected example |
+| --- | --- |
+| Only `a-z`, `0-9`, `.` and `_` | `jaspers-market`, `jasperś` |
+| 3–35 characters | `ab`, `a` × 36 |
+| At least one letter | `12345` |
+| Must not start or end with `.` | `.jaspers`, `jaspers.` |
+| No two consecutive `.` | `jaspers..market` |
+| Must not start with `www` | `www.jaspers` |
+| Must not end with a domain suffix | `jaspers.com`, `jaspers.html` |
+
+Each failure raises `ActiveModel::ValidationError` naming the rule.
+
+Three things worth knowing about how these are applied:
+
+- **Mixed case is downcased, not rejected.** Meta compares usernames case-insensitively,
+  so `"JaspersMarket"` is sent as `"jaspersmarket"`. Refusing a name Meta would have
+  accepted is the failure mode this gem avoids.
+- **`.` and `_` are significant.** `myid`, `my.id`, and `my_id` are three different names.
+- **`www` is read literally**, so `wwwidgets` is rejected too. Meta writes the rule as a
+  bare prefix; a reversible local rejection beats a wasted request.
+
+> The domain-suffix list is **`.com .org .net .int .edu .gov .mil .us .in .html`** —
+> and Meta's own list ends in "and so on", so it cannot be complete. A suffix outside it
+> reaches the API and comes back as error `100`.
+
+### Moving a username between your own numbers
+
+If another phone number *in the same portfolio* holds the name, `Claim` fails with
+`147005`. Resend with a forced transfer:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Username::Claim.call(
+  username: "jaspersmarket",
+  transfer_action: :force_transfer
+)
+```
+
+> **This takes the name off the other number.** There is deliberately no automatic
+> retry — a destructive step stays an explicit one.
+
+## Deleting one
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Username::Delete.call.success  # => true
+```
+
+Note this reports `success`, not a status: a delete arrives back through the
+[webhook](../webhooks/business_username_updates.md) as `status: "deleted"`, which is the
+only place that value ever appears — `Details::Statuses::ALL` deliberately omits it.
+
+## Errors
+
+| Code | Meaning and remedy |
+| --- | --- |
+| `10` | The token's system user needs Full control, or Partial access for Phone numbers, on the WABA |
+| `33` | Invalid phone number ID, deleted WABA, or the app lacks `whatsapp_business_management` |
+| `100` | The username format is invalid — including a domain suffix outside the list above |
+| `147001` | Already claimed, or failed Meta's internal checks. Try another |
+| `147002` | The portfolio's [messaging limit](https://developers.facebook.com/documentation/business-messaging/whatsapp/messaging-limits) is too low |
+| `147003` | Link the number to the Facebook Page already using this name |
+| `147004` | Link the number to the Instagram account already using this name |
+| `147005` | Another of your numbers holds it — resend with `transfer_action: "force_transfer"` |
+| `133010` | The number must be [registered](README.md) for API use first |
+
+All arrive as `Whatsapp::BusinessPhoneNumber::Error` with Meta's message attached.
+
+## Targeting a different number
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Username::Get.call(client: Whatsapp::Client.new(phone_id: "OTHER_ID"))
+```
+
+---
+
+**See also:** [`business_username_updates` webhook](../webhooks/business_username_updates.md) ·
+[Sending to a BSUID](../messages/README.md#business-scoped-user-ids-bsuid)
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids