ruby-whatsapp 0.4.0 → 0.6.1

data/docs/webhooks/README.md

@@ -0,0 +1,217 @@
+# Webhooks
+
+Meta pushes inbound messages, delivery statuses, and 20 other account and template
+notifications to a callback URL you register. This directory covers the *inbound*
+direction — the opposite of everything under [../messages/](../messages/README.md).
+
+> **Business-scoped user IDs (BSUID).** Meta is rolling out usernames, after which a
+> WhatsApp user's phone number may stop appearing in webhooks entirely. `Contact`,
+> `Message::Base`, and `Status` all carry BSUID fallback identifiers now — see
+> [messages.md's BSUID section](messages.md#business-scoped-user-ids-bsuid).
+
+> **Two different things.** `Whatsapp::Webhook` deserializes notifications once Meta is
+> already sending them. Turning that delivery **on** for a WhatsApp Business Account is
+> [`Whatsapp::SubscribedApp`](../subscribed_app/README.md). You need both.
+
+## Install (Rails)
+
+```bash
+bundle exec rake whatsapp:install:webhook
+```
+
+This copies a personalizable controller to
+`app/controllers/whatsapp/webhooks_controller.rb` — it never overwrites an existing
+one — and prints the routes and configuration you still need to add by hand:
+
+```ruby
+# config/routes.rb
+get  "/whatsapp/webhooks", to: "whatsapp/webhooks#verify"
+post "/whatsapp/webhooks", to: "whatsapp/webhooks#receive"
+
+# config/initializers/whatsapp.rb
+Whatsapp.configure do |config|
+  config.verify_token = Rails.application.credentials.whatsapp_verify_token
+  config.app_secret   = Rails.application.credentials.whatsapp_app_secret
+end
+```
+
+The rake task is registered by `Whatsapp::Railtie` and only exists inside a Rails app.
+Outside Rails, call the installer directly — it is plain Ruby with no Rails dependency:
+
+```ruby
+Whatsapp::Webhook::Installer.call(root: Dir.pwd)   # => :created | :skipped
+```
+
+## The generated controller
+
+Yours to edit. It handles the handshake and the signature check, then deserializes
+every notification into typed objects and leaves a `# TODO` where your handling goes:
+
+```ruby
+class Whatsapp::WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token, raise: false
+
+  def verify
+    challenge = Whatsapp::Webhook::Verification.call(params: params)
+    challenge ? render(plain: challenge) : head(:forbidden)
+  end
+
+  def receive
+    raw_body = request.body.read
+    return head(:unauthorized) unless Whatsapp::Webhook::Signature.valid?(
+      payload: raw_body, header: request.headers["X-Hub-Signature-256"]
+    )
+
+    notification = Whatsapp::Webhook::Notification.deserialize(JSON.parse(raw_body))
+    # notification.entry.each { |entry| entry.changes.each { |change| WebhookJob.perform_later(change) } }
+
+    head :ok
+  end
+end
+```
+
+> **Answer fast, work later.** Meta retries a notification that doesn't get a 2xx
+> quickly. Enqueue the work; don't do it inline.
+
+## Verification (the GET handshake)
+
+When you register the callback URL, Meta calls it once with `hub.mode`,
+`hub.verify_token`, and `hub.challenge`. Echo the challenge back if the token matches:
+
+```ruby
+Whatsapp::Webhook::Verification.call(params: params)
+# => "1158201444" — the challenge, to render as plain text
+# => nil          — mode wasn't "subscribe", or the token didn't match
+```
+
+The token comparison uses `ActiveSupport::SecurityUtils.secure_compare`. A nil or empty
+configured `verify_token` always returns `nil` rather than accepting anything.
+
+## Signature (the POST check)
+
+Every notification carries an `X-Hub-Signature-256` header: HMAC-SHA256 of the **raw
+request body** using your app secret.
+
+```ruby
+Whatsapp::Webhook::Signature.valid?(payload: raw_body, header: request.headers["X-Hub-Signature-256"])
+# => true | false
+```
+
+> **Use the raw body, not `params`.** Re-serializing a parsed hash changes the bytes
+> and the signature will never match.
+
+Returns `false` — never raises — for a nil payload, a missing or empty header, or a
+missing app secret.
+
+## Multi-tenant apps
+
+Both take the credential as an overridable keyword, defaulting to
+`Whatsapp.configuration`. That override is the multi-tenant path: an app serving many
+customers, each with their own Meta App, resolves the account first and passes its
+credentials explicitly.
+
+```ruby
+account = Account.find_by!(slug: params[:account_slug])
+
+Whatsapp::Webhook::Verification.call(params:, verify_token: account.verify_token)
+Whatsapp::Webhook::Signature.valid?(payload: raw_body, header:, app_secret: account.app_secret)
+```
+
+## The notification tree
+
+```
+{ object, entry: [ { id, changes: [ { field, value } ] } ] }
+```
+
+```ruby
+notification = Whatsapp::Webhook::Notification.deserialize(JSON.parse(raw_body))
+
+notification.object                      # => "whatsapp_business_account"
+notification.entry.first.id              # => "102290129340398"  — the WABA ID
+change = notification.entry.first.changes.first
+change.field                             # => "messages"
+change.value                             # => #<Whatsapp::Webhook::Messages ...>
+```
+
+`change.field` is one of Meta's 21 documented field names; `change.value` is that
+field's deserialized payload, resolved through a frozen `Change::FIELDS` registry —
+**never `const_get` on the field name**, since it comes straight off the internet.
+
+A field not in the registry (something Meta adds after this gem ships) falls back to
+`UnknownField` rather than raising, so your controller never 500s on an unrecognized
+notification:
+
+```ruby
+change.value                # => #<Whatsapp::Webhook::UnknownField ...>
+change.value["some_key"]    # reach into the raw hash
+change.value.to_h           # the whole thing
+```
+
+## The 21 fields
+
+| Field | Page | Confidence |
+| --- | --- | --- |
+| `messages` | [messages.md](messages.md) | **Confirmed** — Meta publishes a real payload |
+| `user_id_update` | [user_id_update.md](user_id_update.md) | **Confirmed** — Meta publishes a real payload |
+| `business_username_updates` | [business_username_updates.md](business_username_updates.md) | **Confirmed** — Meta publishes a real payload |
+| `user_preferences` | [user_preferences.md](user_preferences.md) | **Confirmed** — Meta publishes a real payload |
+| `history` | [history.md](history.md) | **Confirmed** — Meta publishes a real payload |
+| `account_alerts` | [account_alerts.md](account_alerts.md) | Moderate |
+| `account_review_update` | [account_review_update.md](account_review_update.md) | High |
+| `account_update` | [account_update.md](account_update.md) | Moderate |
+| `automatic_events` | [automatic_events.md](automatic_events.md) | Low |
+| `business_capability_update` | [business_capability_update.md](business_capability_update.md) | Moderate |
+| `message_template_components_update` | [message_template_components_update.md](message_template_components_update.md) | Moderate |
+| `message_template_quality_update` | [message_template_quality_update.md](message_template_quality_update.md) | Moderate-high |
+| `message_template_status_update` | [message_template_status_update.md](message_template_status_update.md) | High |
+| `partner_solutions` | [partner_solutions.md](partner_solutions.md) | Low |
+| `payment_configuration_update` | [payment_configuration_update.md](payment_configuration_update.md) | Moderate |
+| `phone_number_name_update` | [phone_number_name_update.md](phone_number_name_update.md) | Moderate-high |
+| `phone_number_quality_update` | [phone_number_quality_update.md](phone_number_quality_update.md) | Moderate |
+| `security` | [security.md](security.md) | Low |
+| `smb_app_state_sync` | [smb_app_state_sync.md](smb_app_state_sync.md) | High |
+| `smb_message_echoes` | [smb_message_echoes.md](smb_message_echoes.md) | High |
+| `template_category_update` | [template_category_update.md](template_category_update.md) | Moderate-high |
+
+> **On confidence.** The five **Confirmed** fields each have a Meta-published JSON
+> example, and `smb_message_echoes`/`smb_app_state_sync` have a published entry shape but
+> an array key still inferred from the field name. The other 14 field classes are
+> reconstructed from the one-line descriptions in Meta's docs plus general Cloud API knowledge. They are
+> real, tested classes — but validate one against a real payload (App Dashboard → "send
+> test payload") before depending on it in production.
+
+## Dispatching
+
+`Change#field` is a plain String, which makes a `case` the natural handler:
+
+```ruby
+notification.entry.each do |entry|
+  entry.changes.each do |change|
+    case change.field
+    when "messages"
+      change.value.messages.each { |m| handle_message(m) }
+      change.value.statuses.each { |s| handle_status(s) }
+    when "message_template_status_update"
+      Template.find_by(meta_id: change.value.message_template_id)
+              &.update!(status: change.value.event)
+    else
+      Rails.logger.info("Unhandled webhook field: #{change.field}")
+    end
+  end
+end
+```
+
+## Conventions
+
+Every class here follows the read-side pattern — no validations, no `serialize`, just
+a class-level `.deserialize(data)`:
+
+1. Plain Ruby object, `attr_accessor` per field.
+2. `.deserialize(data)` tolerates a nil or partial hash (`data ||= {}`) and missing
+   arrays (`Array(data["key"]).map { ... }`).
+3. Optional nested objects return `nil` when their source key is absent, not an
+   all-nil instance — e.g. `Message::Context.deserialize(nil) # => nil`.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview>

data/docs/webhooks/account_alerts.md

@@ -0,0 +1,44 @@
+# `account_alerts`
+
+Operational alerts about the account — messaging-limit changes, policy notices,
+capability warnings.
+
+`Whatsapp::Webhook::AccountAlerts` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "account_alerts",
+  "value": {
+    "entity_type": "WABA",
+    "entity_id": "102290129340398",
+    "alert_severity": "INFO",
+    "alert_status": "ACTIVE",
+    "alert_description": "Messaging limit increased"
+  } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `entity_type` | What the alert is about, e.g. `WABA` |
+| `entity_id` | That entity's ID |
+| `alert_severity` | e.g. `INFO`, `WARNING`, `CRITICAL` |
+| `alert_status` | e.g. `ACTIVE`, `RESOLVED` |
+| `alert_description` | Human-readable text |
+
+## Handling it
+
+```ruby
+when "account_alerts"
+  alert = change.value
+  Ops.notify(alert.alert_description) if alert.alert_severity != "INFO"
+```
+
+> **Best-effort schema.** Meta publishes no JSON example for this field. Validate
+> against a real payload before depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/docs/webhooks/account_review_update.md

@@ -0,0 +1,29 @@
+# `account_review_update`
+
+The verdict on a WhatsApp Business Account review.
+
+`Whatsapp::Webhook::AccountReviewUpdate` · confidence: **high** — one field, and Meta
+documents it plainly
+
+## Payload
+
+```json
+{ "field": "account_review_update", "value": { "decision": "APPROVED" } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `decision` | `APPROVED` or `REJECTED` |
+
+## Handling it
+
+```ruby
+when "account_review_update"
+  Account.find_by(waba_id: entry.id)&.update!(review_decision: change.value.decision)
+```
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/docs/webhooks/account_update.md

@@ -0,0 +1,54 @@
+# `account_update`
+
+Something changed about the WhatsApp Business Account itself — most importantly, a ban
+or a restriction. If you handle exactly one non-`messages` field, make it this one:
+a banned WABA stops delivering everything.
+
+`Whatsapp::Webhook::AccountUpdate` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "account_update",
+  "value": {
+    "phone_number": "15550783881",
+    "event": "DISABLED_UPDATE",
+    "ban_info": { "waba_ban_state": "DISABLE", "waba_ban_date": "2024-01-01" }
+  } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `phone_number` | The number the event concerns |
+| `event` | e.g. `DISABLED_UPDATE`, `VERIFIED_ACCOUNT`, `ACCOUNT_RESTRICTION` |
+| `ban_info` | `AccountUpdate::BanInfo` or `nil` |
+
+### `BanInfo`
+
+| Accessor | Meaning |
+| --- | --- |
+| `waba_ban_state` | e.g. `DISABLE`, `WARN`, `REINSTATE` |
+| `waba_ban_date` | When it takes effect |
+
+## Handling it
+
+```ruby
+when "account_update"
+  update = change.value
+
+  if update.ban_info
+    Ops.page!(
+      "WABA #{entry.id} ban state #{update.ban_info.waba_ban_state} " \
+      "effective #{update.ban_info.waba_ban_date}"
+    )
+  end
+```
+
+> **Best-effort schema.** Meta publishes no JSON example for this field. Validate
+> against a real payload before depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/docs/webhooks/automatic_events.md

@@ -0,0 +1,47 @@
+# `automatic_events`
+
+Conversion and engagement events Meta attributes to a message — a purchase, a signup —
+used for ad measurement.
+
+`Whatsapp::Webhook::AutomaticEvents` · confidence: **low**
+
+## Payload
+
+```json
+{ "field": "automatic_events",
+  "value": { "event_type": "purchase",
+             "message_id": "wamid.HBg...",
+             "event_data": { "value": 19.99, "currency": "USD" } } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `event_type` | e.g. `purchase` |
+| `message_id` | The WAMID the event is attributed to |
+| `event_data` | **Raw Hash**, defaults to `{}` |
+
+`event_data` is deliberately left as a raw hash: its keys vary by `event_type` and Meta
+publishes no schema, so typing it would be guesswork.
+
+## Handling it
+
+```ruby
+when "automatic_events"
+  event = change.value
+
+  Conversion.create!(
+    kind: event.event_type,
+    wamid: event.message_id,
+    amount: event.event_data["value"],
+    currency: event.event_data["currency"]
+  )
+```
+
+> **Best-effort schema, low confidence.** Validate against a real payload before
+> depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/docs/webhooks/business_capability_update.md

@@ -0,0 +1,40 @@
+# `business_capability_update`
+
+Your account's capability limits changed — how many conversations each number may
+start per day, and how many numbers the business may hold. A limit increase usually
+follows sustained good quality; a decrease follows the opposite.
+
+`Whatsapp::Webhook::BusinessCapabilityUpdate` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "business_capability_update",
+  "value": { "max_daily_conversation_per_phone": 100000,
+             "max_phone_numbers_per_business": 20 } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `max_daily_conversation_per_phone` | Business-initiated conversations per number per day |
+| `max_phone_numbers_per_business` | Numbers this business may register |
+
+## Handling it
+
+```ruby
+when "business_capability_update"
+  caps = change.value
+  Throttle.update!(daily_cap: caps.max_daily_conversation_per_phone)
+```
+
+Useful for pacing an outbound campaign against the real ceiling rather than a
+hard-coded guess.
+
+> **Best-effort schema.** Meta publishes no JSON example for this field. Validate
+> against a real payload before depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/docs/webhooks/business_username_updates.md

@@ -0,0 +1,55 @@
+# `business_username_updates`
+
+A business phone number's username status changed — approved, reserved, or deleted.
+Subscribe to this field to stay in sync whenever a username you claimed moves through
+review, or is removed via the WhatsApp Business app.
+
+`Whatsapp::Webhook::BusinessUsernameUpdates` · confidence: **confirmed** — Meta
+publishes a real JSON example
+
+## Payload
+
+```json
+{ "field": "business_username_updates",
+  "value": {
+    "display_phone_number": "15550783881",
+    "username": "jaspersmarket",
+    "status": "approved"
+  } }
+```
+
+`username` is omitted when `status` is `"deleted"`.
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `display_phone_number` | The business phone number's display number |
+| `username` | The username the status concerns; `nil` when `status` is `"deleted"` |
+| `status` | `"approved"`, `"reserved"`, or `"deleted"` |
+
+## Handling it
+
+```ruby
+when "business_username_updates"
+  update = change.value
+  digits = update.display_phone_number.to_s.gsub(/\D/, "")
+  number = PhoneNumber.find_by(display_phone_number_digits: digits)
+
+  if number
+    number.update!(username: update.username, username_status: update.status)
+  else
+    Rails.logger.error("[whatsapp] no PhoneNumber matching #{update.display_phone_number.inspect}")
+  end
+```
+
+This field carries no `phone_number_id`, so `display_phone_number` is the only join key
+you get — and Meta formats it for display, inconsistently (`"15550783881"` in one payload,
+`"+1 555-078-3881"` in another). Match on digits, and report a miss instead of letting
+`&.update!` swallow it: a silent no-op means you never learn the username moved. Log or
+alert; do not `raise`, or a permanent formatting mismatch puts Meta into a retry loop
+against a request that can never succeed. `update.raw` carries the untouched payload.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#business_username_updates-webhook>

data/docs/webhooks/history.md

@@ -0,0 +1,107 @@
+# `history`
+
+Conversation history synced from the WhatsApp Business app when a number moves onto
+Cloud API. It arrives in chunks, so `phase`, `chunk_order`, and `progress` are how you
+track completeness.
+
+`Whatsapp::Webhook::History` · confidence: **confirmed**
+
+## Payload
+
+```json
+{ "field": "history",
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "history": [
+      { "metadata": { "phase": 2, "chunk_order": 1, "progress": 50 },
+        "threads": [
+          { "id": "16505551234",
+            "context": { "wa_id": "16505551234",
+                         "user_id": "US.13491208655302741918",
+                         "username": "pablomorales" },
+            "messages": [
+              { "from": "16505551234",
+                "from_user_id": "US.13491208655302741918",
+                "id": "wamid.HBg",
+                "timestamp": "1749416383",
+                "type": "text",
+                "text": { "body": "Does it come in another color?" },
+                "history_context": { "status": "DELIVERED" } }
+            ] }
+        ] }
+    ] } }
+```
+
+Two `metadata` objects, and they are different things: the value-level one is the
+ordinary business-phone-number `Metadata`, while each `history[]` entry has its own
+carrying the sync counters.
+
+## Value accessors
+
+| Accessor | Type |
+| --- | --- |
+| `messaging_product` | `String` |
+| `metadata` | `Metadata` — the business phone number, **not** the sync counters |
+| `chunks` | `Array<History::Chunk>` |
+| `phase` / `chunk_order` / `progress` | Read through to `chunks.first`, since a delivery normally carries one chunk |
+| `contacts` | `Array<Contact>` — populated only by the media-asset variant |
+| `messages` | `Array<Message::*>` — populated only by the media-asset variant |
+| `raw` | The untouched `value` hash |
+
+## Chunk accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `phase` | Sync phase |
+| `chunk_order` | This chunk's position within its phase |
+| `progress` | Percent complete, 0–100 |
+| `threads` | `Array<History::Thread>` |
+
+## Thread accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `id` | The thread identifier — the user's phone number, omitted for a username adopter |
+| `context` | A `Contact` — `wa_id`, `user_id`, `parent_user_id`, `username` |
+| `messages` | `Array<Message::*>`, dispatched by `type` like any inbound message |
+| `raw` | The untouched thread hash |
+
+`context` reuses the same [`Contact`](messages.md#value-accessors) as every other contact
+entry: its `username` read already falls back to a flat key, which is where Meta puts it
+here, and `profile_name` is simply `nil` since a thread context carries no profile.
+
+Each synced message also has a `history_context.status` — its delivery state at sync
+time. That is deliberately **not** modelled: it would put a history-only field on
+`Message::Base`, the envelope shared by every inbound message type, where it could never
+appear. Read it off `thread.raw`:
+
+```ruby
+thread.raw.dig("messages", 0, "history_context", "status")  # => "DELIVERED"
+```
+
+## Handling it
+
+```ruby
+when "history"
+  sync = change.value
+
+  sync.chunks.each do |chunk|
+    chunk.threads.each do |thread|
+      # A username adopter has no phone number here — the BSUID is the join key
+      customer = Customer.find_or_create_by!(bsuid: thread.context&.user_id)
+      customer.import_history!(thread.messages)
+    end
+
+    Importer.finish! if chunk.progress == 100
+  end
+```
+
+> **Changed in 0.6.0.** `phase`/`chunk_order`/`progress` used to be read from
+> `value["metadata"]` and threads from `value["threads"]` — one level too high, so every
+> accessor was permanently empty. `threads` has moved onto `Chunk`, and the three
+> counters now work.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

data/docs/webhooks/message_template_components_update.md

@@ -0,0 +1,46 @@
+# `message_template_components_update`
+
+A template's components changed — usually because Meta edited it, or because an edit
+you submitted was applied.
+
+`Whatsapp::Webhook::MessageTemplateComponentsUpdate` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "message_template_components_update",
+  "value": {
+    "message_template_id": "123",
+    "message_template_name": "order_confirmation",
+    "message_template_language": "en_US",
+    "message_template_element": "BODY"
+  } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `message_template_id` | The template's ID |
+| `message_template_name` | Its name |
+| `message_template_language` | Its locale |
+| `message_template_element` | Which component changed |
+
+## Handling it
+
+The notification says *that* something changed, not what it changed to. Re-read the
+template to get the new shape:
+
+```ruby
+when "message_template_components_update"
+  node = Whatsapp::MessageTemplates.new.find(template_id: change.value.message_template_id)
+  MessageTemplate.find_by(meta_id: node.id)&.update!(components: node.components)
+```
+
+> **Best-effort schema.** Meta describes this field in one line and publishes no JSON
+> example. Validate against a real payload (App Dashboard → "send test payload")
+> before depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview