ruby-whatsapp 0.4.0 → 0.6.1

data/docs/webhooks/payment_configuration_update.md

@@ -0,0 +1,40 @@
+# `payment_configuration_update`
+
+A payment provider configuration changed — the plumbing behind in-chat payments,
+currently a regional feature (India, Brazil, Singapore).
+
+`Whatsapp::Webhook::PaymentConfigurationUpdate` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "payment_configuration_update",
+  "value": { "configuration_name": "default",
+             "provider_name": "razorpay",
+             "provider_mid": "mid.1",
+             "status": "ACTIVE" } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `configuration_name` | Your name for the configuration |
+| `provider_name` | e.g. `razorpay`, `payu` |
+| `provider_mid` | The provider's merchant ID |
+| `status` | e.g. `ACTIVE`, `INACTIVE` |
+
+## Handling it
+
+```ruby
+when "payment_configuration_update"
+  config = change.value
+  PaymentConfig.find_by(name: config.configuration_name)&.update!(status: config.status)
+```
+
+> **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/phone_number_name_update.md

@@ -0,0 +1,44 @@
+# `phone_number_name_update`
+
+The verdict on a display-name change you requested for a phone number. The display
+name is what customers see as the sender, and Meta reviews every change.
+
+`Whatsapp::Webhook::PhoneNumberNameUpdate` · confidence: **moderate-high**
+
+## Payload
+
+```json
+{ "field": "phone_number_name_update",
+  "value": { "phone_number": "15550783881",
+             "decision": "REJECTED",
+             "requested_verified_name": "Acme Corp",
+             "rejection_reason": "INCLUDES_UNSUPPORTED_CHARACTERS" } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `phone_number` | The number affected |
+| `decision` | `APPROVED` or `REJECTED` |
+| `requested_verified_name` | The name you asked for |
+| `rejection_reason` | Why it was refused, when it was |
+
+## Handling it
+
+```ruby
+when "phone_number_name_update"
+  update = change.value
+
+  if update.decision == "REJECTED"
+    Ops.notify("Display name #{update.requested_verified_name.inspect} rejected: " \
+               "#{update.rejection_reason}")
+  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/phone_number_quality_update.md

@@ -0,0 +1,40 @@
+# `phone_number_quality_update`
+
+A phone number's quality rating or messaging tier changed. A downgrade cuts how many
+conversations that number may start per day, so this is worth alerting on.
+
+`Whatsapp::Webhook::PhoneNumberQualityUpdate` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "phone_number_quality_update",
+  "value": { "display_phone_number": "15550783881",
+             "event": "DOWNGRADE",
+             "current_limit": "TIER_50" } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `display_phone_number` | The number affected |
+| `event` | e.g. `UPGRADE`, `DOWNGRADE`, `FLAGGED`, `UNFLAGGED` |
+| `current_limit` | e.g. `TIER_50`, `TIER_250`, `TIER_1K`, `TIER_UNLIMITED` |
+
+## Handling it
+
+```ruby
+when "phone_number_quality_update"
+  quality = change.value
+
+  Ops.alert("#{quality.display_phone_number} downgraded to #{quality.current_limit}") \
+    if quality.event == "DOWNGRADE"
+```
+
+> **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/security.md

@@ -0,0 +1,43 @@
+# `security`
+
+Security events on a phone number — chiefly two-step verification being enabled or
+disabled.
+
+`Whatsapp::Webhook::Security` · confidence: **low**
+
+## Payload
+
+```json
+{ "field": "security",
+  "value": { "display_phone_number": "15550783881",
+             "event": "TWO_STEP_VERIFICATION_ENABLED",
+             "requester": "16505551234" } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `display_phone_number` | The number affected |
+| `event` | e.g. `TWO_STEP_VERIFICATION_ENABLED` / `..._DISABLED` |
+| `requester` | Who initiated the change |
+
+## Handling it
+
+```ruby
+when "security"
+  event = change.value
+  AuditLog.create!(kind: event.event, subject: event.display_phone_number,
+                   actor: event.requester)
+```
+
+The two-step verification PIN this concerns is the same one
+[`Register`](../business_phone_number/README.md#registering) consumes.
+
+> **Best-effort schema, low confidence.** Meta describes this field in one line and
+> publishes no JSON example. 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/smb_app_state_sync.md

@@ -0,0 +1,91 @@
+# `smb_app_state_sync`
+
+Contact-book and app-state changes synced from the WhatsApp Business app. Arrives
+alongside [`history`](history.md) when a number moves onto Cloud API.
+
+`Whatsapp::Webhook::SmbAppStateSync` · confidence: **high**
+
+## Payload
+
+```json
+{ "field": "smb_app_state_sync",
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "state_sync": [
+      { "type": "contact",
+        "contact": { "full_name": "Pablo Morales",
+                     "first_name": "Pablo",
+                     "phone_number": "16505551234",
+                     "user_id": "US.13491208655302741918",
+                     "username": "pablomorales" },
+        "action": "add",
+        "metadata": { "timestamp": "1750030073" } }
+    ] } }
+```
+
+## Accessors
+
+| Accessor | Type |
+| --- | --- |
+| `messaging_product` | `"whatsapp"` |
+| `metadata` | `Metadata` — the business phone number whose address book this is |
+| `state_sync` | `Array<SmbAppStateSync::StateSync>` |
+| `raw` | The untouched `value` hash |
+
+### `StateSync`
+
+| Accessor | Meaning |
+| --- | --- |
+| `type` | `"contact"` is the only documented kind |
+| `action` | e.g. `add`, `update`, `remove` |
+| `contact` | An `SmbAppStateSync::Contact`, or `nil` |
+| `timestamp` | Flattened up from the entry's own `metadata.timestamp` |
+
+The entry's `metadata` is **not** the value-level `Metadata` — it carries only a
+timestamp, so the wrapper is dropped rather than typed.
+
+### `Contact`
+
+| Accessor | Meaning |
+| --- | --- |
+| `full_name` | |
+| `first_name` | |
+| `phone_number` | Omitted once the contact adopts a username |
+| `user_id` | Their [BSUID](messages.md#business-scoped-user-ids-bsuid) |
+| `parent_user_id` | Their parent BSUID, present only if enrolled |
+| `username` | Set only if adopted. Read **flat** here, unlike `Contact#username` on `messages`, which Meta nests under `profile` |
+
+This is the gem's third `Contact`, and none are interchangeable:
+[`Webhook::Contact`](messages.md#value-accessors) is a notification's sender identity,
+[`Message::Contacts::Contact`](messages.md#contacts) is a shared contact *card*, and this
+is a device address-book row.
+
+## Handling it
+
+```ruby
+when "smb_app_state_sync"
+  change.value.state_sync.each do |sync|
+    next unless sync.type == "contact"
+
+    case sync.action
+    when "add", "update"
+      Contact.upsert_from_meta(bsuid: sync.contact.user_id, phone: sync.contact.phone_number,
+                               name: sync.contact.full_name, username: sync.contact.username)
+    when "remove"
+      Contact.find_by(bsuid: sync.contact.user_id)&.destroy
+    end
+  end
+```
+
+> **Changed in 0.6.0.** `StateSync#contact` used to be a raw Hash, because Meta had
+> published no shape for it. It is now a typed `Contact`, so `sync.contact["phone_number"]`
+> becomes `sync.contact.phone_number`, and an entry carrying no contact returns `nil`
+> rather than `{}`.
+
+> The `state_sync` key itself is still inferred from the field name rather than confirmed
+> by a published example — hence `raw`, so a drifted key leaves a trace.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

data/docs/webhooks/smb_message_echoes.md

@@ -0,0 +1,91 @@
+# `smb_message_echoes`
+
+Echoes of messages sent **from the WhatsApp Business app** rather than through the API.
+Without this, a number used by both your code and a human agent in the app would show
+you only half the conversation. Messages the business *revoked* or *edited* from the app
+arrive here too.
+
+`Whatsapp::Webhook::SmbMessageEchoes` · confidence: **high**
+
+## Payload
+
+```json
+{ "field": "smb_message_echoes",
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "contacts": [
+      { "profile": { "username": "pablomorales" },
+        "wa_id": "16505551234",
+        "user_id": "US.13491208655302741918" }
+    ],
+    "message_echoes": [
+      { "from": "15550783881",
+        "to": "16505551234",
+        "to_user_id": "US.13491208655302741918",
+        "id": "wamid.HBg",
+        "timestamp": "1750030073",
+        "type": "text",
+        "text": { "body": "Thanks for shopping with us!" } }
+    ] } }
+```
+
+## Accessors
+
+| Accessor | Type |
+| --- | --- |
+| `messaging_product` | `"whatsapp"` |
+| `metadata` | `Metadata` — `display_phone_number`, `phone_number_id` |
+| `contacts` | `Array<Contact>` — the customers these went to |
+| `message_echoes` | `Array<SmbMessageEchoes::Echo>` |
+| `raw` | The untouched `value` hash |
+
+### `Echo`
+
+| Accessor | Meaning |
+| --- | --- |
+| `to` | The customer's phone number, or `nil` once they adopt a username |
+| `to_user_id` | Their [BSUID](messages.md#business-scoped-user-ids-bsuid) |
+| `to_parent_user_id` | Their parent BSUID, present only if enrolled |
+| `message` | The echoed `Message::*`, dispatched by `type` |
+
+`Echo#message` goes through the same `Message.deserialize` dispatcher as
+[`messages`](messages.md), so an echo is a fully typed `Message::Text`, `Message::Image`,
+`Message::Revoke`, `Message::Edit`, and so on — with the same accessors.
+
+Why a wrapper rather than three more accessors on `Message::Base`? Because an *inbound*
+message can never carry a recipient. Putting `to`/`to_user_id`/`to_parent_user_id` on the
+envelope shared by every message type would hand fifteen classes three permanently-`nil`
+readers, and would turn the `NoMethodError` that currently tells you `message.to` is
+meaningless into a silent `nil`.
+
+## Handling it
+
+```ruby
+when "smb_message_echoes"
+  change.value.message_echoes.each do |echo|
+    # The customer may have no phone number; the BSUID always identifies them
+    conversation = Conversation.for(bsuid: echo.to_user_id, wa_id: echo.to)
+
+    conversation.messages.create!(
+      wamid: echo.message.id,
+      direction: :outbound,
+      source: :business_app,
+      body: echo.message.try(:body)
+    )
+  end
+```
+
+Note `echo.message.from` is *your* business number, not the customer's — these are
+messages you sent. The customer is on `echo.to*`.
+
+> **Changed in 0.6.0.** `message_echoes` used to be an `Array<Message::*>` directly;
+> each entry is now an `Echo` wrapping that message, so `echo.body` becomes
+> `echo.message.body`. The wrapper is what carries the new recipient identifiers.
+
+> The `message_echoes` key itself is still inferred from the field name rather than
+> confirmed by a published example — hence `raw`, so a drifted key leaves a trace.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

data/docs/webhooks/template_category_update.md

@@ -0,0 +1,52 @@
+# `template_category_update`
+
+Meta reclassified a template — most often moving something you filed as `UTILITY` into
+`MARKETING`. This matters because category determines **how you are billed** and
+whether the message is subject to marketing opt-outs.
+
+`Whatsapp::Webhook::TemplateCategoryUpdate` · confidence: **moderate-high**
+
+## Payload
+
+```json
+{ "field": "template_category_update",
+  "value": {
+    "message_template_id": "123",
+    "message_template_name": "order_confirmation",
+    "message_template_language": "en_US",
+    "previous_category": "MARKETING",
+    "new_category": "UTILITY",
+    "correct_category": "UTILITY"
+  } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `message_template_id` | The template's ID |
+| `message_template_name` | Its name |
+| `message_template_language` | Its locale |
+| `previous_category` | What it was |
+| `new_category` | What it is now |
+| `correct_category` | What Meta believes it should be |
+
+## Handling it
+
+```ruby
+when "template_category_update"
+  update = change.value
+
+  MessageTemplate
+    .find_by(meta_id: update.message_template_id)
+    &.update!(category: update.new_category)
+
+  Billing.recheck!(update.message_template_name) if update.new_category == "MARKETING"
+```
+
+> **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/user_id_update.md

@@ -0,0 +1,84 @@
+# `user_id_update`
+
+A WhatsApp user's business-scoped user ID (BSUID) changed — most commonly because they
+changed their phone number (see the [`system` message type's `user_changed_user_id`
+event](messages.md#system) for the same event surfaced on the `messages` field).
+
+`Whatsapp::Webhook::UserIdUpdate` · confidence: **confirmed** — Meta publishes a real
+JSON example
+
+## Payload
+
+```json
+{ "field": "user_id_update",
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "contacts": [{ "profile": { "name": "Jane Doe" }, "wa_id": "16505551234" }],
+    "user_id_update": [
+      {
+        "wa_id": "16505551234",
+        "detail": "User id for Jane Doe has been updated.",
+        "user_id": { "previous": "US.OLD", "current": "US.NEW" },
+        "parent_user_id": { "previous": "US.ENT.OLD", "current": "US.ENT.NEW" },
+        "timestamp": "1750030073"
+      }
+    ]
+  } }
+```
+
+`parent_user_id` is present only if you have enrolled in [parent
+BSUIDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#parent-business-scoped-user-ids).
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `messaging_product` | `"whatsapp"` |
+| `metadata` | `Metadata` — `display_phone_number`, `phone_number_id` |
+| `contacts` | `Array<Contact>` — the [same BSUID-aware `Contact`](messages.md#business-scoped-user-ids-bsuid) used by `messages` |
+| `updates` | `Array<UserIdUpdate::Entry>` |
+
+### `Entry`
+
+| Accessor | Meaning |
+| --- | --- |
+| `wa_id` | The user's phone number, if available |
+| `detail` | Human-readable description of the change |
+| `user_id` | `UserIdUpdate::IdChange` or `nil` — the user's previous and current BSUID |
+| `parent_user_id` | `UserIdUpdate::IdChange` or `nil` — previous and current parent BSUID |
+| `timestamp` | Unix seconds, as a String |
+
+### `IdChange`
+
+`Whatsapp::Webhook::UserIdUpdate::IdChange` — a sibling of `Entry`, not nested inside it.
+One class serves both `user_id` and `parent_user_id`, since they are the same shape, and
+each is `nil` rather than an all-nil object when its key is absent.
+
+| Accessor | Meaning |
+| --- | --- |
+| `previous` | The BSUID before the change |
+| `current` | The BSUID after the change |
+
+## Handling it
+
+```ruby
+when "user_id_update"
+  change.value.updates.each do |update|
+    next unless update.user_id  # nil when the entry carries only a parent BSUID change
+
+    user = User.find_by(bsuid: update.user_id.previous)
+    next Rails.logger.warn("[whatsapp] unknown BSUID #{update.user_id.previous}") unless user
+
+    user.update!(bsuid: update.user_id.current)
+  end
+```
+
+Report a miss rather than letting `&.update!` swallow it — a rotation you never applied
+leaves you writing to a dead BSUID with no diagnostics. Log or alert; do not `raise`, or
+Meta will retry a request that can never succeed. `change.value.raw` carries the untouched
+payload if you need to see what actually arrived.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#user_id_update-webhooks>

data/docs/webhooks/user_preferences.md

@@ -0,0 +1,87 @@
+# `user_preferences`
+
+A customer changed their marketing preferences — most importantly, opting **out**.
+Respecting this is not optional: continuing to send marketing to someone who stopped
+you damages your quality rating and breaches Meta's policy.
+
+`Whatsapp::Webhook::UserPreferences` · confidence: **confirmed**
+
+## Payload
+
+```json
+{ "field": "user_preferences",
+  "value": {
+    "messaging_product": "whatsapp",
+    "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+    "contacts": [
+      { "profile": { "name": "Pablo M.", "username": "pablomorales" },
+        "wa_id": "16505551234",
+        "user_id": "US.13491208655302741918" }
+    ],
+    "user_preferences": [
+      { "wa_id": "16505551234",
+        "user_id": "US.13491208655302741918",
+        "detail": "User requested to stop marketing messages",
+        "category": "marketing_messages",
+        "value": "stop",
+        "timestamp": 1750030073 }
+    ] } }
+```
+
+Note the nesting: the entries sit under a repeat of the field's own name, the same shape
+[`user_id_update`](user_id_update.md) uses.
+
+## Value accessors
+
+| Accessor | Type |
+| --- | --- |
+| `messaging_product` | `String` — always `"whatsapp"` |
+| `metadata` | `Metadata` — the business phone number this arrived on |
+| `contacts` | `Array<Contact>` — `profile_name`, `username`, `wa_id`, `user_id`, `parent_user_id` |
+| `preferences` | `Array<UserPreferences::Entry>` |
+| `raw` | The untouched `value` hash |
+
+## Entry accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `wa_id` | The customer's phone number, or `nil` once they adopt a username |
+| `user_id` | Their [BSUID](messages.md#business-scoped-user-ids-bsuid) — the identifier that is always there |
+| `parent_user_id` | Their parent BSUID, present only if enrolled |
+| `detail` | Human-readable description |
+| `category` | `"marketing_messages"` is the only documented value |
+| `value` | `"stop"` or `"resume"` |
+| `timestamp` | Unix seconds. Meta sends a **number** here, unlike the String timestamps on `messages` |
+
+> `Entry#value` sits inside the change's own `value` hash, so the full path reads
+> `change.value.preferences.first.value`. Meta's naming, not ours.
+
+## Handling it
+
+An opt-out from a username adopter may carry no phone number at all, so key off the
+BSUID and fall back to `wa_id` — not the other way round:
+
+```ruby
+when "user_preferences"
+  change.value.preferences.each do |preference|
+    customer =
+      Customer.find_by(bsuid: preference.user_id) ||
+      Customer.find_by(wa_id: preference.wa_id)
+
+    customer&.update!(
+      marketing_opt_in: preference.value != "stop",
+      marketing_opt_in_changed_at: Time.at(preference.timestamp.to_i)
+    )
+  end
+```
+
+Gate every `MARKETING`-category [template send](../messages/template.md) on this flag.
+`UTILITY` and `AUTHENTICATION` templates are unaffected.
+
+> **Changed in 0.6.0.** This field used to expose `wa_id`/`detail`/`value`/`timestamp`
+> directly on `change.value`. Meta nests them one level deeper than the gem assumed, so
+> those accessors could never return anything but `nil`; they are now on `Entry`.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids