ruby-whatsapp 0.4.0 → 0.4.2

data/docs/README.md

@@ -0,0 +1,73 @@
+# ruby-whatsapp documentation
+
+Full reference for [ruby-whatsapp](https://github.com/saleszera/ruby-whatsapp). The
+[project README](../README.md) is the short version.
+
+## Start here
+
+| Page | Covers |
+| --- | --- |
+| [configuration.md](configuration.md) | Credentials, the client, connection reuse, instrumentation, which ID addresses what |
+| [errors.md](errors.md) | The full exception hierarchy, validation vs API failures, retry strategy |
+
+## Outbound — talking to customers
+
+| Page | Covers |
+| --- | --- |
+| [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 |
+
+### Message kinds
+
+[text](messages/text.md) ·
+[image](messages/image.md) ·
+[video](messages/video.md) ·
+[audio](messages/audio.md) ·
+[document](messages/document.md) ·
+[sticker](messages/sticker.md) ·
+[reaction](messages/reaction.md) ·
+[location](messages/location.md) ·
+[contacts](messages/contacts.md) ·
+[address](messages/address.md) ·
+[location request](messages/location_request.md) ·
+[template](messages/template.md) ·
+[interactive](messages/interactive.md) ·
+[mark as read](messages/mark_message_as_read.md)
+
+### Template kinds
+
+[standard](message_templates/standard.md) ·
+[authentication](message_templates/authentication.md) ·
+[carousel](message_templates/carousel.md) ·
+[limited-time offer](message_templates/limited_time_offer.md) ·
+[library](message_templates/library.md) ·
+[components reference](message_templates/components.md) ·
+[responses](message_templates/responses.md)
+
+## Inbound — hearing back
+
+| Page | Covers |
+| --- | --- |
+| [webhooks/](webhooks/README.md) | Install, verification, signature, dispatch, all 19 notification fields |
+| [webhooks/messages.md](webhooks/messages.md) | Inbound messages and delivery statuses — the one you'll actually use |
+
+## Account administration
+
+| Page | Covers |
+| --- | --- |
+| [subscribed_app/](subscribed_app/README.md) | Turning webhook delivery on and off for a WABA |
+| [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 |
+
+## Reading order
+
+New to the Cloud API? Follow the setup path in order:
+
+1. [configuration.md](configuration.md) — get credentials in place
+2. [business_phone_number/](business_phone_number/README.md) — register the number
+3. [messages/text.md](messages/text.md) — send something
+4. [subscribed_app/](subscribed_app/README.md) — turn on webhook delivery
+5. [webhooks/](webhooks/README.md) — receive the reply
+6. [message_templates/](message_templates/README.md) — message outside the 24-hour window

data/docs/business_phone_number/README.md

@@ -0,0 +1,232 @@
+# 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 — not an optional extra.
+
+`Whatsapp::BusinessPhoneNumber` wraps all four endpoints in that path:
+
+```
+RequestCode  ->  VerifyCode  ->  Register            (onboarding)
+(send OTP)       (confirm it)    (activate on Cloud API)
+
+Deregister                                            (the reverse switch)
+```
+
+Addresses your **phone number** (`phone_id`, not `waba_id`), like
+[messages](../messages/README.md) and [media](../media/README.md), and needs both the
+`whatsapp_business_messaging` and `whatsapp_business_management` permissions.
+
+> **Looking for the account itself?** [`Account::Get` / `Account::Update`](account.md)
+> read and update the WhatsApp Business Account a number belongs to — its name,
+> timezone, review and verification status. Those are the one `waba_id`-scoped corner
+> of this module.
+
+> **Looking for the profile a user sees?** [`Profile::Get` / `Profile::Update`](profile.md)
+> read and write the about line, description, address, email, websites, industry vertical,
+> and picture. Those address your phone number (`phone_id`), just 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.
+
+## The whole flow
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key  = ENV.fetch("WHATSAPP_API_KEY")
+  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID")
+end
+
+Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "SMS", language: "en_US")
+Whatsapp::BusinessPhoneNumber::VerifyCode.call(code: "123456")
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")
+Whatsapp::BusinessPhoneNumber::Deregister.call
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `RequestCode.call(code_method:, language:)` | `POST /{phone_id}/request_code` | `Response` |
+| `VerifyCode.call(code:)` | `POST /{phone_id}/verify_code` | `Response` (may carry `id`) |
+| `Register.call(pin:, data_localization_region:)` | `POST /{phone_id}/register` | `Response` |
+| `Deregister.call` | `POST /{phone_id}/deregister` | `Response` |
+| [`Account::Get.call(fields:)`](account.md) | `GET /{waba_id}` | `Account::Details` |
+| [`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` |
+
+Every action accepts an optional `client:` and raises
+`Whatsapp::BusinessPhoneNumber::Error` if `phone_id` is missing or the API rejects the
+request.
+
+## Requesting a verification code
+
+Sends a one-time code to the number, by SMS or automated voice call.
+
+```ruby
+Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "SMS", language: "en_US").success
+# => true
+```
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `code_method` | yes | `"SMS"` or `"VOICE"` — either casing accepted, emitted uppercase |
+| `language` | yes | The locale for the message, e.g. `"en_US"`. Presence only |
+
+> `language` is deliberately **not** checked against `Utils::LanguageCodes`. That list
+> is the set of locales Meta *approves templates* in; this field is closer to a
+> delivery preference, and Meta documents it as a plain string with no enum.
+
+```ruby
+Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "CARRIER_PIGEON", language: "en_US")
+# => ActiveModel::ValidationError: Code method is not included in the list
+```
+
+Both fields are always sent — neither is compacted away:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::RequestCode.new(code_method: "sms", language: "en_US").serialize
+# => { code_method: "SMS", language: "en_US" }
+```
+
+## Verifying the code
+
+```ruby
+result = Whatsapp::BusinessPhoneNumber::VerifyCode.call(code: "123456")
+
+result.success   # => true
+result.id        # => "106540352242922"  — the phone number ID, when Meta returns one
+```
+
+`code` is checked for presence only — Meta documents no format, so a wrong-but-present
+code is rejected server-side.
+
+The OTP is redacted from `#inspect`:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::VerifyCode.new(code: "123456").inspect
+# => "#<Whatsapp::BusinessPhoneNumber::VerifyCode code=[REDACTED]>"
+```
+
+## Registering
+
+The step that actually activates the number on Cloud API.
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834").success
+# => true
+```
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `pin` | yes | Exactly **6 digits** — the existing two-step verification PIN, or the one to set |
+| `data_localization_region` | no | One of 14 region codes |
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "1234")
+# => ActiveModel::ValidationError: Pin must be exactly 6 digits
+```
+
+### Data localization
+
+Passing a region enables local storage — message data at rest stays in that region:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834", data_localization_region: "CH")
+```
+
+| Region | Codes |
+| --- | --- |
+| APAC | `AU` `ID` `IN` `JP` `SG` `KR` |
+| Europe | `DE` `CH` `GB` |
+| LATAM | `BR` |
+| MEA | `BH` `ZA` `AE` |
+| NORAM | `CA` |
+
+Omitted when not given:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.new(pin: "212834").serialize
+# => { messaging_product: "whatsapp", pin: "212834" }
+
+Whatsapp::BusinessPhoneNumber::Register.new(pin: "212834", data_localization_region: "ch").serialize
+# => { messaging_product: "whatsapp", pin: "212834", data_localization_region: "CH" }
+```
+
+The PIN is redacted from `#inspect`, and no validation error message ever echoes it:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.new(pin: "212834", data_localization_region: "CH").inspect
+# => "#<Whatsapp::BusinessPhoneNumber::Register pin=[REDACTED] 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.
+
+`Deregister` takes no arguments and has nothing to validate — its payload is `{}`.
+
+## Targeting a different number
+
+Inject a client rather than mutating global configuration:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.call(
+  pin: "212834",
+  client: Whatsapp::Client.new(phone_id: "OTHER_PHONE_ID")
+)
+```
+
+## Rate limits
+
+> **`Register` / `Deregister`:** 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`:** "standard Graph API rate limits", plus possible
+> additional throttling — Meta publishes no number.
+
+This is server-side state the gem cannot observe, so there is no client-side tracking.
+It is also why every action validates locally first: a rejected attempt still counts
+against the limit.
+
+## Errors
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")
+# => Whatsapp::BusinessPhoneNumber::Error: phone_id is required for the register edge;
+#    set it via Whatsapp.configure or Client.new(phone_id:)
+
+# non-2xx response
+# => Whatsapp::BusinessPhoneNumber::Error: Failed to register business phone number:
+#    400 Bad Request - {"error":{"message":"..."}}
+```
+
+Local validation failures raise `ActiveModel::ValidationError` before any request. See
+[../errors.md](../errors.md).
+
+## Not wrapped
+
+- **Client-side rate-limit tracking** — server-side state the gem cannot observe.
+- **Two-step verification PIN management.** `Register` *consumes* an existing PIN;
+  setting or changing one is a different endpoint.
+
+---
+
+**See also:** [Reading and updating the business account](account.md) ·
+[Reading and updating the business profile](profile.md)
+
+---
+
+**Meta docs:**
+[registration](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/registration)
+· [request code](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/phone-number-verification-request-code-api)
+· [verify code](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/verify-code-api)
+· [deregister](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/phone-number-deregister-api)

data/docs/business_phone_number/account.md

@@ -0,0 +1,170 @@
+# Reading and Updating the Business Account
+
+Every business phone number belongs to a **WhatsApp Business Account** (WABA). The rest
+of this module drives a *number's* onboarding; `Whatsapp::BusinessPhoneNumber::Account`
+reads and writes the *account* that number sits inside — whether Meta has approved it,
+whether the business behind it is verified, who owns it, and what it is called.
+
+> **The one `waba_id` corner of this module.**
+> [`RequestCode`/`VerifyCode`/`Register`/`Deregister`](README.md) address your phone
+> number (`phone_id`). `Account` addresses the account (`waba_id`), like
+> [template management](../message_templates/README.md) and
+> [subscribed apps](../subscribed_app/README.md), and needs the
+> `whatsapp_business_management` permission.
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key = ENV.fetch("WHATSAPP_API_KEY")
+  config.waba_id = ENV.fetch("WHATSAPP_WABA_ID")
+end
+
+Whatsapp::BusinessPhoneNumber::Account::Get.call.name              # => "Acme Corp"
+Whatsapp::BusinessPhoneNumber::Account::Update.call(name: "Acme")  # => #<Response success=true>
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `Get.call(client:, fields:)` | `GET /{waba_id}` | `Account::Details` |
+| `Update.call(client:, name:, timezone_id:)` | `POST /{waba_id}` | `BusinessPhoneNumber::Response` |
+
+Two independent actions, so two classes — the same shape as
+[subscribed apps](../subscribed_app/README.md), not the single-object CRUD of
+[templates](../message_templates/README.md).
+
+## Reading account details
+
+```ruby
+details = Whatsapp::BusinessPhoneNumber::Account::Get.call
+
+details.id     # => "102290129340398"
+details.name   # => "Acme Corp"
+```
+
+By default Meta returns only `id` and `name`. Ask for more with `fields:` — an Array or
+a String, comma-joined for you:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Account::Get.call(fields: %w[id name country])
+Whatsapp::BusinessPhoneNumber::Account::Get.call(fields: "id,name,country")
+```
+
+`Fields::ALL` requests everything Meta publishes, without hand-typing the list:
+
+```ruby
+details = Whatsapp::BusinessPhoneNumber::Account::Get.call(
+  fields: Whatsapp::BusinessPhoneNumber::Account::Get::Fields::ALL
+)
+```
+
+| Field | Description |
+| --- | --- |
+| `id` | The account's unique identifier |
+| `name` | Human-readable account name |
+| `timezone_id` | Timezone identifier |
+| `message_template_namespace` | Namespace the account's templates live in |
+| `account_review_status` | One of `Details::ReviewStatuses::ALL` |
+| `business_verification_status` | One of `Details::VerificationStatuses::ALL` |
+| `country` | Country code |
+| `ownership_type` | One of `Details::OwnershipTypes::ALL` |
+| `primary_business_location` | Primary business location |
+
+> `fields` is **not** validated against `Fields::ALL`. Those constants are for
+> convenience, not enforcement — a field Meta adds later works without a gem release.
+> Only what Meta documents as a *client-side* rule is checked locally.
+
+### Status values
+
+Statuses come back as plain strings, with frozen constants to compare against and three
+predicates for the checks you actually make:
+
+```ruby
+details.approved?     # => true   — account_review_status == "APPROVED"
+details.verified?     # => true   — business_verification_status == "VERIFIED"
+details.self_owned?   # => true   — ownership_type == "SELF"
+```
+
+| Constant | Values |
+| --- | --- |
+| `Details::ReviewStatuses::ALL` | `APPROVED` `DEFERRED` `PENDING` `REJECTED` |
+| `Details::VerificationStatuses::ALL` | `EXPIRED` `FAILED` `INELIGIBLE` `NOT_VERIFIED` `PENDING` `PENDING_NEED_MORE_INFO` `PENDING_SUBMISSION` `REJECTED` `REVOKED` `VERIFIED` |
+| `Details::OwnershipTypes::ALL` | `CLIENT_OWNED` `ON_BEHALF_OF` `SELF` |
+
+> Read-side values are never validated on the way in. A status Meta adds later still
+> round-trips untouched, so `details.account_review_status` is always exactly what the
+> API sent — same reasoning as
+> [`MessageTemplates::Response::Node#components`](../message_templates/responses.md).
+
+Every field is optional in the response, so anything you did not request is `nil`
+rather than an error.
+
+## Updating the account
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Account::Update.call(name: "Acme Corporation").success
+# => true
+```
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `name` | no | Non-empty when given |
+| `timezone_id` | no | Non-empty when given. Meta publishes no enum — presence only |
+
+Both fields are optional, but **at least one must be present** — otherwise the request
+would spend a call to change nothing:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Account::Update.call
+# => ActiveModel::ValidationError: at least one of name or timezone_id must be provided
+
+Whatsapp::BusinessPhoneNumber::Account::Update.call(name: "")
+# => ActiveModel::ValidationError: Name can't be blank
+```
+
+An omitted field is compacted out of the body rather than sent as `null`, which Meta
+would read as an instruction to blank it:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Account::Update.new(name: "Acme Corp").serialize
+# => { name: "Acme Corp" }
+
+Whatsapp::BusinessPhoneNumber::Account::Update.new(name: "Acme Corp", timezone_id: "1").serialize
+# => { name: "Acme Corp", timezone_id: "1" }
+```
+
+`Update` returns the same `Whatsapp::BusinessPhoneNumber::Response` as the four
+onboarding actions — the endpoint answers with a bare `{ "success": true }`, so there is
+no separate response class for it.
+
+## Errors
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Account::Get.call
+# => Whatsapp::BusinessPhoneNumber::Error: waba_id is required for business account
+#    details; set it via Whatsapp.configure or Client.new(waba_id:)
+
+# non-2xx response
+# => Whatsapp::BusinessPhoneNumber::Error: Failed to get business account details:
+#    404 Not Found - {"error":{"message":"WhatsApp Business Account not found",...}}
+```
+
+Both actions raise `Whatsapp::BusinessPhoneNumber::Error` — the same class the
+onboarding actions use, so one `rescue` covers the whole module. Local validation
+failures raise `ActiveModel::ValidationError` before any request. See
+[../errors.md](../errors.md).
+
+## Targeting a different account
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Account::Get.call(
+  client: Whatsapp::Client.new(waba_id: "OTHER_WABA_ID")
+)
+```
+
+---
+
+**See also:** [Reading and updating the business profile](profile.md) ·
+[Registering business phone numbers](README.md)
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/whatsapp-business-account-api>

data/docs/business_phone_number/profile.md

@@ -0,0 +1,220 @@
+# Reading and Updating the Business Profile
+
+A business phone number has a **business profile** — the public card a WhatsApp user sees
+before they reply: the about line, the description, where the business is, how else to reach
+it, and what industry it is in. The rest of this module drives whether a number *works*;
+`Whatsapp::BusinessPhoneNumber::Profile` decides how it *looks*.
+
+> **Same `phone_id` as the onboarding actions.** Meta exposes the profile as an edge on the
+> phone number itself, so `Profile` addresses `phone_id` exactly like
+> [`RequestCode`/`VerifyCode`/`Register`/`Deregister`](README.md) — unlike
+> [`Account`](account.md), which is this module's one `waba_id`-scoped corner.
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key  = ENV.fetch("WHATSAPP_API_KEY")
+  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID")
+end
+
+Whatsapp::BusinessPhoneNumber::Profile::Get.call.about                    # => "Open daily 9-5"
+Whatsapp::BusinessPhoneNumber::Profile::Update.call(about: "Open 9-6")    # => #<Response success=true>
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `Get.call(client:, fields:)` | `GET /{phone_id}/whatsapp_business_profile` | `Profile::Details` |
+| `Update.call(client:, **fields)` | `POST /{phone_id}/whatsapp_business_profile` | `BusinessPhoneNumber::Response` |
+
+Two independent actions, so two classes — the same shape as [`Account`](account.md) and
+[subscribed apps](../subscribed_app/README.md), not the single-object CRUD of
+[templates](../message_templates/README.md).
+
+## Reading the profile
+
+```ruby
+profile = Whatsapp::BusinessPhoneNumber::Profile::Get.call
+
+profile.about        # => "Open daily 9-5"
+profile.vertical     # => "RETAIL"
+profile.websites     # => ["https://acme.test"]
+```
+
+Ask for specific fields with `fields:` — an Array or a String, comma-joined for you:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Get.call(fields: %w[about vertical websites])
+Whatsapp::BusinessPhoneNumber::Profile::Get.call(fields: "about,vertical,websites")
+```
+
+`Fields::ALL` requests everything Meta publishes, without hand-typing the list:
+
+```ruby
+profile = Whatsapp::BusinessPhoneNumber::Profile::Get.call(
+  fields: Whatsapp::BusinessPhoneNumber::Profile::Get::Fields::ALL
+)
+```
+
+| Field | Description |
+| --- | --- |
+| `messaging_product` | The messaging service — always `"whatsapp"` in practice |
+| `about` | The text shown in the profile's About section |
+| `address` | The business's physical address |
+| `description` | The business description |
+| `email` | The business's contact email address |
+| `profile_picture_url` | URL of the current profile picture |
+| `websites` | The business's website URLs |
+| `vertical` | One of `Profile::Verticals::ALL` |
+
+> `fields` is **not** validated against `Fields::ALL`. Those constants are for
+> convenience, not enforcement — a field Meta adds later works without a gem release.
+> Only what Meta documents as a *client-side* rule is checked locally.
+
+Meta wraps the read in a `data` array; `Profile::Details` unwraps it for you, so there is no
+`.data.first` to reach through. Every field is optional in the response, so anything you did
+not request is `nil` rather than an error.
+
+> Read-side values are never validated or normalized on the way in. A `vertical` Meta adds
+> later still round-trips untouched, so `profile.vertical` is always exactly what the API
+> sent — compare it against `Verticals::ALL` rather than expecting `Details` to have
+> rejected it. Same reasoning as [`Account::Details`](account.md#status-values)' statuses and
+> [`MessageTemplates::Response::Node#components`](../message_templates/responses.md).
+
+## Updating the profile
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Update.call(
+  about: "Open daily 9-6", vertical: "RETAIL", websites: ["https://acme.test"]
+).success
+# => true
+```
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `about` | no | At most **139** characters |
+| `address` | no | At most **256** characters |
+| `description` | no | At most **512** characters |
+| `email` | no | At most **128** characters. Format is *not* checked — see below |
+| `vertical` | no | One of `Verticals::ALL` — either casing accepted, emitted uppercase |
+| `websites` | no | At most **2** URLs |
+| `profile_picture_handle` | no | Non-empty when given. From the Resumable Upload API |
+
+Every field is optional, but **at least one must be present** — otherwise the request would
+spend a call to change nothing:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Update.call
+# => ActiveModel::ValidationError: at least one of about, address, description, email,
+#    vertical, websites, profile_picture_handle must be provided
+```
+
+The limits and the vertical enum are checked before anything is sent:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Update.call(about: "a" * 140)
+# => ActiveModel::ValidationError: About is too long (maximum is 139 characters)
+
+Whatsapp::BusinessPhoneNumber::Profile::Update.call(vertical: "SPACESHIPS")
+# => ActiveModel::ValidationError: Vertical is not included in the list
+
+Whatsapp::BusinessPhoneNumber::Profile::Update.call(websites: %w[https://a.test https://b.test https://c.test])
+# => ActiveModel::ValidationError: websites accepts at most 2 URLs
+```
+
+> **`email`'s format is deliberately not validated.** Meta checks the address server-side,
+> and a regex here would reject perfectly valid exotic addresses. This gem checks only
+> length. Same standing decision as `override_callback_uri` in
+> [subscribed apps](../subscribed_app/README.md) — no speculative hardening.
+
+`messaging_product` is always sent for you. An omitted field is compacted out of the body
+rather than sent as `null`, which Meta would read as an instruction to blank it:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Update.new(about: "Open daily").serialize
+# => { messaging_product: "whatsapp", about: "Open daily" }
+
+Whatsapp::BusinessPhoneNumber::Profile::Update.new(vertical: "retail").serialize
+# => { messaging_product: "whatsapp", vertical: "RETAIL" }
+```
+
+### Clearing the website list
+
+An **empty array** is the one falsy-looking value that survives compaction, because that is
+how Meta clears the list — and it counts as "changing something", so it satisfies the
+at-least-one-field rule on its own:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Update.new(websites: []).serialize
+# => { messaging_product: "whatsapp", websites: [] }
+```
+
+### Industry verticals
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Verticals::ALL
+```
+
+| Constant | Values |
+| --- | --- |
+| `Verticals::ALL` | `ALCOHOL` `APPAREL` `AUTO` `BEAUTY` `EDU` `ENTERTAIN` `EVENT_PLAN` `FINANCE` `GOVT` `GROCERY` `HEALTH` `HOTEL` `NONPROFIT` `ONLINE_GAMBLING` `OTC_DRUGS` `OTHER` `PHYSICAL_GAMBLING` `PROF_SERVICES` `RESTAURANT` `RETAIL` `TRAVEL` |
+
+Either casing is accepted and normalized on the way out, so `"retail"`, `:retail`, and
+`"RETAIL"` are the same request.
+
+### The profile picture
+
+`profile_picture_handle` is forwarded as an opaque string. The handle itself comes from
+Meta's **Resumable Upload API**, which this gem does not wrap:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Update.call(profile_picture_handle: "4::aW1hZ2UvcG5n...")
+```
+
+> **A media ID will not work here.** [`Media#upload`](../media/README.md) returns a media ID
+> for *sending* messages — a different thing from an upload handle. Same standing exclusion
+> as media handles for [template headers](../message_templates/README.md#not-wrapped).
+
+`Update` returns the same `Whatsapp::BusinessPhoneNumber::Response` as the four onboarding
+actions — the endpoint answers with a bare `{ "success": true }`, so there is no separate
+response class for it.
+
+## Errors
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Get.call
+# => Whatsapp::BusinessPhoneNumber::Error: phone_id is required for the
+#    whatsapp_business_profile edge; set it via Whatsapp.configure or Client.new(phone_id:)
+
+# non-2xx response
+# => Whatsapp::BusinessPhoneNumber::Error: Failed to update business profile:
+#    400 Bad Request - {"error":{"message":"Invalid parameter: email must be a valid ..."}}
+```
+
+Both actions raise `Whatsapp::BusinessPhoneNumber::Error` — the same class the onboarding
+actions use, so one `rescue` covers the whole module. Local validation failures raise
+`ActiveModel::ValidationError` before any request. See [../errors.md](../errors.md).
+
+## Targeting a different number
+
+Inject a client rather than mutating global configuration:
+
+```ruby
+Whatsapp::BusinessPhoneNumber::Profile::Get.call(
+  client: Whatsapp::Client.new(phone_id: "OTHER_PHONE_ID")
+)
+```
+
+## Not wrapped
+
+- **The Resumable Upload API** that mints a `profile_picture_handle` — the handle is accepted
+  and forwarded, but not produced.
+- **Profile read caching.** Meta suggests caching profile reads for moderate periods;
+  invalidation is an application concern.
+
+---
+
+**See also:** [Reading and updating the business account](account.md) ·
+[Registering business phone numbers](README.md)
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-profile-api>