ruby-whatsapp 0.4.0 → 0.6.1

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>

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

data/docs/configuration.md

@@ -0,0 +1,177 @@
+# Configuration
+
+`Whatsapp.configure` sets the global defaults every `Whatsapp::Client` is built from.
+Call it once at boot.
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key  = ENV.fetch("WHATSAPP_API_KEY")
+  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID")
+end
+```
+
+## Options
+
+| Option | Default | Needed for |
+| --- | --- | --- |
+| `api_key` | `nil` | Everything — a Meta system-user or app access token |
+| `phone_id` | `nil` | [Messages](messages/README.md), [media](media/README.md), [phone-number onboarding](business_phone_number/README.md) |
+| `waba_id` | `nil` | [Template management](message_templates/README.md), [subscribed apps](subscribed_app/README.md), [campaign schedules](schedule/README.md), [the business account](business_phone_number/account.md) |
+| `verify_token` | `nil` | The [webhook GET handshake](webhooks/README.md#verification-the-get-handshake) |
+| `app_secret` | `nil` | [Webhook signature verification](webhooks/README.md#signature-the-post-check) |
+| `host` | `"https://graph.facebook.com"` | Overriding the API host |
+| `version` | `"v24.0"` | Pinning a Graph API version |
+| `media_host_allowlist` | `["lookaside.fbsbx.com", "mmg.whatsapp.net", "graph.facebook.com"]` | [Media download safety](media/README.md#the-token-never-leaves-the-allowlist) |
+
+A full configuration:
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key      = ENV.fetch("WHATSAPP_API_KEY")
+  config.phone_id     = ENV.fetch("WHATSAPP_PHONE_ID")
+  config.waba_id      = ENV.fetch("WHATSAPP_WABA_ID")
+  config.verify_token = ENV.fetch("WHATSAPP_VERIFY_TOKEN")
+  config.app_secret   = ENV.fetch("WHATSAPP_APP_SECRET")
+end
+```
+
+In Rails, put that in `config/initializers/whatsapp.rb` and read from
+`Rails.application.credentials` rather than `ENV`.
+
+## Which ID addresses what
+
+The most common source of confusion. Two different Meta objects, two different
+permissions:
+
+```
+phone_id  ──►  Messages          send_text!, send_template!, send_interactive!, ...
+               Media             upload, get_url, download, delete
+               BusinessPhoneNumber  RequestCode, VerifyCode, Register, Deregister
+               (permission: whatsapp_business_messaging)
+
+waba_id   ──►  MessageTemplates  create, list, find, update, delete, upsert
+               SubscribedApp     List, Subscribe, Unsubscribe
+               Schedule          List, Create
+               BusinessPhoneNumber::Account  Get, Update
+               (permission: whatsapp_business_management)
+```
+
+Meta's Schedules reference names no permission at all. `Schedule` is listed under
+`whatsapp_business_management` because it addresses the WABA like its neighbours, but
+that is an assumption, not something Meta documents.
+
+`BusinessPhoneNumber` is the one module that appears on both sides: its onboarding
+actions address a phone number, while its
+[`Account`](business_phone_number/account.md) actions address the account that number
+belongs to.
+
+Calling a `waba_id` API without one raises before any request is made:
+
+```ruby
+Whatsapp::MessageTemplates.new.list
+# => Whatsapp::MessageTemplates::TemplateError: waba_id is required for template
+#    management; set it via Whatsapp.configure or Client.new(waba_id:)
+```
+
+## Secrets are redacted
+
+`api_key`, `app_secret`, and `verify_token` never appear in `#inspect` output — not on
+`Configuration`, not on `Client`, and therefore not on anything holding a client
+(`Media`, `MessageTemplates`). This matters because error trackers routinely capture
+local variables.
+
+```ruby
+Whatsapp.configuration.inspect
+# => "#<Whatsapp::Configuration host=\"https://graph.facebook.com\" version=\"v24.0\"
+#     api_key=[REDACTED] phone_id=\"106540352242922\" waba_id=nil
+#     verify_token=[REDACTED] app_secret=[REDACTED]>"
+
+Whatsapp::Client.new.inspect
+# => "#<Whatsapp::Client host=\"https://graph.facebook.com\" version=\"v24.0\"
+#     api_key=[REDACTED] phone_id=\"106540352242922\" waba_id=nil>"
+```
+
+The same treatment applies to credentials in transit:
+[`Register#inspect`](business_phone_number/README.md#registering) redacts the PIN and
+`VerifyCode#inspect` redacts the OTP.
+
+## The client
+
+Every API call goes through a `Whatsapp::Client`, which wraps a persistent HTTP
+connection. All its constructor keywords default to `Whatsapp.configuration`:
+
+```ruby
+Whatsapp::Client.new(
+  host:     Whatsapp.configuration.host,
+  version:  Whatsapp.configuration.version,
+  api_key:  Whatsapp.configuration.api_key,
+  phone_id: Whatsapp.configuration.phone_id,
+  waba_id:  Whatsapp.configuration.waba_id,
+  timeout:  30,     # Client::DEFAULT_TIMEOUT, seconds
+  logger:   nil
+)
+```
+
+Every entry point in the gem accepts an optional `client:`, which is how you address a
+second phone number or business account without touching global state:
+
+```ruby
+Whatsapp::Messages.send_text!(
+  to: "+15551234567", body: "Hi",
+  client: Whatsapp::Client.new(phone_id: "OTHER_PHONE_ID")
+)
+
+Whatsapp::MessageTemplates.new(client: Whatsapp::Client.new(waba_id: "OTHER_WABA_ID")).list
+```
+
+### Connection reuse
+
+`Client#connection` memoizes `HTTP.persistent(host)`, so successive calls on the same
+client reuse one TCP connection. Build a client once and hold it for a batch of sends
+rather than constructing one per message:
+
+```ruby
+client = Whatsapp::Client.new
+
+recipients.each { |to| Whatsapp::Messages.send_text!(to:, body: "Hi", client:) }
+```
+
+### Timeouts
+
+```ruby
+Whatsapp::Client.new(timeout: 10)
+```
+
+Applies to the whole request. The default is 30 seconds.
+
+## Instrumentation
+
+Pass a `Logger` to log every request and response:
+
+```ruby
+client = Whatsapp::Client.new(logger: Logger.new($stdout))
+
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi", client: client)
+# I, [...]  INFO -- : POST https://graph.facebook.com/v24.0/106540352242922/messages
+# I, [...]  INFO -- : 200 OK
+```
+
+| Event | Logged |
+| --- | --- |
+| Request start | `<VERB> <url>` at `info` |
+| Response | `<status> <reason>` at `info` |
+| Error | `<name>: <message>` at `error` |
+
+> **The query string is deliberately dropped.** Media and template endpoints put IDs
+> in query parameters; logging them whole is how identifiers end up in log aggregators
+> forever. Only the path is logged.
+
+In Rails, pass `Rails.logger`:
+
+```ruby
+Whatsapp::Client.new(logger: Rails.logger)
+```
+
+---
+
+See also [errors.md](errors.md) for what the client raises.