ruby-whatsapp 0.4.0 → 0.4.2

data/docs/webhooks/README.md

@@ -0,0 +1,209 @@
+# Webhooks
+
+Meta pushes inbound messages, delivery statuses, and ~18 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).
+
+> **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 19 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 19 fields
+
+| Field | Page | Confidence |
+| --- | --- | --- |
+| `messages` | [messages.md](messages.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 |
+| `history` | [history.md](history.md) | Low |
+| `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) | Low-moderate |
+| `smb_message_echoes` | [smb_message_echoes.md](smb_message_echoes.md) | Moderate |
+| `template_category_update` | [template_category_update.md](template_category_update.md) | Moderate-high |
+| `user_preferences` | [user_preferences.md](user_preferences.md) | Moderate |
+
+> **On confidence.** Only `messages` has a Meta-published JSON example. The other 18
+> 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/history.md

@@ -0,0 +1,44 @@
+# `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: **low**
+
+## Payload
+
+```json
+{ "field": "history",
+  "value": { "metadata": { "phase": 1, "chunk_order": 1, "progress": 50 },
+             "threads": [{ "id": "thread.1" }] } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `phase` | Sync phase (dug from `value.metadata`) |
+| `chunk_order` | This chunk's position (dug from `value.metadata`) |
+| `progress` | Percent complete, 0–100 (dug from `value.metadata`) |
+| `threads` | **Raw Array** of thread hashes |
+
+Note the three scalars are flattened up from the nested `metadata` object, while
+`threads` is left raw — its element shape is undocumented.
+
+## Handling it
+
+```ruby
+when "history"
+  sync = change.value
+
+  HistoryChunk.create!(phase: sync.phase, order: sync.chunk_order, threads: sync.threads)
+  Importer.finish! if sync.progress == 100
+```
+
+> **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/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

data/docs/webhooks/message_template_quality_update.md

@@ -0,0 +1,49 @@
+# `message_template_quality_update`
+
+A template's quality score changed. Quality is computed from how recipients react —
+blocks, reports, and "not useful" feedback push it down. A template that reaches `RED`
+gets paused, then eventually disabled, so a `GREEN → YELLOW` transition is your early
+warning.
+
+`Whatsapp::Webhook::MessageTemplateQualityUpdate` · confidence: **moderate-high**
+
+## Payload
+
+```json
+{ "field": "message_template_quality_update",
+  "value": {
+    "message_template_id": "123",
+    "message_template_name": "order_confirmation",
+    "message_template_language": "en_US",
+    "previous_quality_score": "GREEN",
+    "new_quality_score": "YELLOW"
+  } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `message_template_id` | The template's ID |
+| `message_template_name` | Its name |
+| `message_template_language` | Its locale |
+| `previous_quality_score` | `GREEN` \| `YELLOW` \| `RED` \| `UNKNOWN` |
+| `new_quality_score` | Same set |
+
+## Handling it
+
+```ruby
+when "message_template_quality_update"
+  update = change.value
+
+  if update.new_quality_score == "RED"
+    Ops.alert("Template #{update.message_template_name} dropped to RED — pause the campaign")
+  end
+```
+
+The same score is readable on demand via
+[`Response::Node#quality_score`](../message_templates/responses.md#qualityscore).
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview

data/docs/webhooks/message_template_status_update.md

@@ -0,0 +1,55 @@
+# `message_template_status_update`
+
+The review verdict on a template you submitted. This is **the** notification to handle
+if you create templates from code — Meta reviews asynchronously and can take up to 24
+hours, so this is how you learn the outcome without polling.
+
+`Whatsapp::Webhook::MessageTemplateStatusUpdate` · confidence: **high**
+
+## Payload
+
+```json
+{ "field": "message_template_status_update",
+  "value": {
+    "message_template_id": "123",
+    "message_template_name": "order_confirmation",
+    "message_template_language": "en_US",
+    "event": "REJECTED",
+    "reason": "INVALID_FORMAT"
+  } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `message_template_id` | The template's ID, as returned by `create` |
+| `message_template_name` | Its name |
+| `message_template_language` | Its locale — a template is one per `(name, language)` pair |
+| `event` | `APPROVED` \| `REJECTED` \| `PAUSED` \| `PENDING_DELETION` \| … |
+| `reason` | Why it was rejected: `NONE` `ABUSIVE_CONTENT` `INVALID_FORMAT` `PROMOTIONAL` `TAG_CONTENT_MISMATCH` `SCAM` |
+
+## Handling it
+
+```ruby
+when "message_template_status_update"
+  update = change.value
+
+  MessageTemplate
+    .find_by(meta_id: update.message_template_id)
+    &.update!(status: update.event, rejected_reason: update.reason)
+
+  if update.event == "REJECTED"
+    Rails.logger.warn(
+      "Template #{update.message_template_name} (#{update.message_template_language}) " \
+      "rejected: #{update.reason}"
+    )
+  end
+```
+
+See [../message_templates/README.md](../message_templates/README.md) for the creation
+side.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview