ruby-whatsapp 0.4.2 → 0.6.1

data/docs/schedule/README.md

@@ -0,0 +1,183 @@
+# Scheduling Campaigns
+
+A **campaign schedule** sends an approved [template](../message_templates/README.md) to an
+audience at a time you choose. `Whatsapp::Schedule` wraps the `schedules` edge, which
+lists an account's schedules and creates new ones.
+
+> **Schedules send templates; they don't create them.** The template behind `hsm_id`
+> must already exist and be approved. Create and manage it with
+> [`Whatsapp::MessageTemplates`](../message_templates/README.md).
+
+Addresses your **WhatsApp Business Account** (`waba_id`, not `phone_id`), the same as
+[template management](../message_templates/README.md) and
+[subscribed apps](../subscribed_app/README.md).
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key = ENV.fetch("WHATSAPP_API_KEY")
+  config.waba_id = ENV.fetch("WHATSAPP_WABA_ID")
+end
+
+Whatsapp::Schedule::Create.call(
+  hsm_id: "1234567890", audience_id: "2345678901", waba_cs_id: "3456789012",
+  name: "Black Friday", description: "Black Friday promo to VIP customers",
+  delivery_time: Time.now.to_i + 3600
+).id                                                # => "9876543210"
+
+Whatsapp::Schedule::List.call.map(&:name)           # => ["Black Friday"]
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `List.call(client:, fields:, limit:, after:, before:)` | `GET /{waba_id}/schedules` | `Response::Collection` |
+| `Create.call(hsm_id:, audience_id:, waba_cs_id:, name:, description:, delivery_time:, client:)` | `POST /{waba_id}/schedules` | `Response::Created` |
+
+## Creating
+
+Every field is required:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `hsm_id` | String | The approved template to send |
+| `audience_id` | String | The audience to send it to |
+| `waba_cs_id` | String | Meta: "WABA customer status ID (phone number)" |
+| `name` | String | The schedule's name |
+| `description` | String | The schedule's description |
+| `delivery_time` | Integer | When to send, as a Unix timestamp |
+
+The examples below share this hash:
+
+```ruby
+attrs = {
+  hsm_id: "1234567890", audience_id: "2345678901", waba_cs_id: "3456789012",
+  name: "Black Friday", description: "Black Friday promo to VIP customers",
+  delivery_time: 1_764_000_000,
+}
+```
+
+`delivery_time` must be an integer. For a `Time`, pass `time.to_i`:
+
+```ruby
+Whatsapp::Schedule::Create.call(**attrs, delivery_time: Time.utc(2026, 11, 27, 9).to_i)
+```
+
+All six are checked before the request, so a missing one costs nothing:
+
+```ruby
+Whatsapp::Schedule::Create.call(**attrs, name: "")
+# => ActiveModel::ValidationError: Validation failed: Name can't be blank
+
+Whatsapp::Schedule::Create.call(**attrs, delivery_time: 1_764_000_000.5)
+# => ActiveModel::ValidationError: Validation failed: Delivery time must be an integer
+```
+
+Nothing beyond that is checked. Meta publishes no length limits and no rule that
+`delivery_time` must be in the future; anything it rejects comes back as a
+`Whatsapp::Schedule::Error`.
+
+> `waba_cs_id` is passed through exactly as given. Meta's description doesn't say
+> whether it means a phone number ID or the number itself.
+
+To inspect the payload without sending it, build the object yourself:
+
+```ruby
+Whatsapp::Schedule::Create.new(**attrs).serialize
+# => { hsm_id: "1234567890", audience_id: "2345678901", waba_cs_id: "3456789012",
+#      name: "Black Friday", description: "Black Friday promo to VIP customers",
+#      delivery_time: 1764000000 }
+```
+
+## Listing
+
+```ruby
+schedules = Whatsapp::Schedule::List.call
+
+schedules.map(&:name)              # Collection is Enumerable
+schedules.first.delivery_time      # => 1764000000
+schedules.first.status             # => "SCHEDULED"
+schedules.first.id                 # => nil (see below)
+```
+
+### Ask for `id` explicitly
+
+**Meta's default fields leave out `id`.** The defaults are `name`, `description`,
+`delivery_time`, and `status`. Request `id` with `fields:`, either as an Array or a
+comma-joined String:
+
+```ruby
+Whatsapp::Schedule::List.call(fields: Whatsapp::Schedule::List::Fields::ALL)
+Whatsapp::Schedule::List.call(fields: %w[id name status])
+Whatsapp::Schedule::List.call(fields: "id,name,status")
+```
+
+`List::Fields::ALL` is a convenience, not a whitelist. A field Meta adds later works
+without a gem release.
+
+### Paging
+
+`limit:` sets the page size (Meta accepts 1–100). `after:` and `before:` take cursors.
+Paging is exposed rather than followed automatically, so fetching every page is your
+choice:
+
+```ruby
+page = Whatsapp::Schedule::List.call(limit: 50)
+
+while page.next_cursor
+  page = Whatsapp::Schedule::List.call(limit: 50, after: page.next_cursor)
+end
+```
+
+`Collection#paging` exposes both cursors (`paging.before`, `paging.after`). It is the
+same Graph API paging object [template listing](../message_templates/README.md) returns.
+
+### Statuses
+
+| Status | Predicate |
+| --- | --- |
+| `SCHEDULED` | `scheduled?` |
+| `SENDING` | `sending?` |
+| `COMPLETED` | `completed?` |
+| `FAILED` | `failed?` |
+
+```ruby
+Whatsapp::Schedule::List.call.select(&:failed?).map(&:name)
+schedule.status == Whatsapp::Schedule::Statuses::SCHEDULED
+```
+
+`status` is the raw string Meta sent and is never validated, so a status Meta adds later
+still comes through. Every predicate just answers `false` for it.
+
+## Response shapes
+
+| Class | Holds | From |
+| --- | --- | --- |
+| `Response::Collection` | `data: [Node]`, `paging`, `next_cursor`, `Enumerable` | `List` |
+| `Response::Node` | `id`, `name`, `description`, `delivery_time`, `status` | each element of `List` |
+| `Response::Created` | `id` | `Create` |
+
+Every attribute tolerates being absent, since Meta returns only the fields you asked for.
+
+## Errors
+
+```ruby
+Whatsapp::Schedule::List.call
+# => Whatsapp::Schedule::Error: waba_id is required for schedules;
+#    set it via Whatsapp.configure or Client.new(waba_id:)
+
+# non-2xx response
+# => Whatsapp::Schedule::Error: Failed to create schedule: 403 Forbidden - {...}
+```
+
+Every API failure raises `Whatsapp::Schedule::Error`, never the generic
+`Whatsapp::RequestError`. Local validation raises `ActiveModel::ValidationError` before
+any request. See [../errors.md](../errors.md).
+
+## Targeting a different account
+
+```ruby
+Whatsapp::Schedule::List.call(client: Whatsapp::Client.new(waba_id: "OTHER_WABA_ID"))
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/schedules-api>

data/docs/webhooks/README.md

@@ -1,9 +1,14 @@
 # Webhooks
 
-Meta pushes inbound messages, delivery statuses, and ~18 other account and template
+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.
@@ -128,7 +133,7 @@ change.field                             # => "messages"
 change.value                             # => #<Whatsapp::Webhook::Messages ...>
 ```
 
-`change.field` is one of Meta's 19 documented field names; `change.value` is that
+`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.
 
@@ -142,17 +147,20 @@ change.value["some_key"]    # reach into the raw hash
 change.value.to_h           # the whole thing
 ```
 
-## The 19 fields
+## 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 |
-| `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 |
@@ -161,16 +169,16 @@ change.value.to_h           # the whole thing
 | `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 |
+| `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 |
-| `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.
+> **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
 

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

@@ -4,27 +4,81 @@ Conversation history synced from the WhatsApp Business app when a number moves o
 Cloud API. It arrives in chunks, so `phase`, `chunk_order`, and `progress` are how you
 track completeness.
 
-`Whatsapp::Webhook::History` · confidence: **low**
+`Whatsapp::Webhook::History` · confidence: **confirmed**
 
 ## Payload
 
 ```json
 { "field": "history",
-  "value": { "metadata": { "phase": 1, "chunk_order": 1, "progress": 50 },
-             "threads": [{ "id": "thread.1" }] } }
+  "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" } }
+            ] }
+        ] }
+    ] } }
 ```
 
-## Accessors
+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 (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 |
+| `phase` | Sync phase |
+| `chunk_order` | This chunk's position within its phase |
+| `progress` | Percent complete, 0–100 |
+| `threads` | `Array<History::Thread>` |
 
-Note the three scalars are flattened up from the nested `metadata` object, while
-`threads` is left raw — its element shape is undocumented.
+## 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
 
@@ -32,13 +86,22 @@ Note the three scalars are flattened up from the nested `metadata` object, while
 when "history"
   sync = change.value
 
-  HistoryChunk.create!(phase: sync.phase, order: sync.chunk_order, threads: sync.threads)
-  Importer.finish! if sync.progress == 100
+  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
 ```
 
-> **Best-effort schema, low confidence.** Validate against a real payload before
-> depending on it in production.
+> **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/webhooks/overview
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids

data/docs/webhooks/messages.md

@@ -1,9 +1,12 @@
 # `messages`
 
 Inbound customer messages and outbound delivery statuses — the field you will spend
-almost all your time on, and the only one with a Meta-published JSON schema.
+almost all your time on, and one of only five fields with a Meta-published JSON
+schema (alongside [`user_id_update`](user_id_update.md) and
+[`business_username_updates`](business_username_updates.md)).
 
-`Whatsapp::Webhook::Messages`
+`Whatsapp::Webhook::Messages` · confidence: **confirmed** — Meta publishes a real JSON
+example
 
 ## A full notification
 
@@ -49,7 +52,7 @@ value.statuses                    # => []
 | --- | --- |
 | `messaging_product` | `"whatsapp"` |
 | `metadata` | `Metadata` — `display_phone_number`, `phone_number_id` |
-| `contacts` | `Array<Contact>` — `profile_name`, `wa_id` |
+| `contacts` | `Array<Contact>` — `profile_name`, `username`, `wa_id`, `user_id`, `parent_user_id` |
 | `messages` | `Array<Message::*>` |
 | `statuses` | `Array<Status>` |
 
@@ -60,6 +63,32 @@ both accessors always return an array, so you can iterate either without a nil c
 > different thing from [`Message::Contacts`](#contacts) below, which is a contact
 > *card* someone shared with you.
 
+### Business-scoped user IDs (BSUID)
+
+Once a WhatsApp user adopts a username, their phone number may stop appearing in
+webhooks — `wa_id`/`from`/`recipient_id` are omitted, and the only stable identifier
+left is their **business-scoped user ID** (BSUID), a country-code-prefixed string like
+`"US.13491208655302741918"` assigned to `user_id`/`from_user_id`/`recipient_user_id`.
+Meta sends `user_id`/`from_user_id` with every contact entry and inbound message in its
+published examples, whether or not a username has been adopted, and sends
+`recipient_user_id` on every delivery status regardless of how you addressed the
+message — see [what arrives with which status](#what-arrives-with-which-status) for the
+one exception. All of
+them deserialize to `nil` rather than raising when absent, so read them as optional. A
+`parent_user_id`/`from_parent_user_id`/`recipient_parent_user_id` variant additionally
+appears if you have enrolled in [parent BSUIDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#parent-business-scoped-user-ids)
+(shared across business portfolios). See
+[Business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids)
+for the full rollout details.
+
+```ruby
+contact = value.contacts.first
+contact.wa_id           # => "16315551181"  or nil once phone number sharing stops
+contact.user_id         # => "US.13491208655302741918" — sent with every contact entry
+contact.username        # => "@testusername" or nil — set only once adopted
+contact.parent_user_id  # => set only when parent BSUIDs are enabled
+```
+
 ---
 
 ## Message types
@@ -72,7 +101,10 @@ All message classes share this envelope from `Message::Base`:
 
 | Accessor | Meaning |
 | --- | --- |
-| `from` | The customer's WhatsApp ID |
+| `from` | The customer's WhatsApp ID, or `nil` once they adopt a username (see [BSUID](#business-scoped-user-ids-bsuid)) |
+| `from_user_id` | The customer's BSUID — sent on every inbound message; `nil` if absent |
+| `from_parent_user_id` | The customer's parent BSUID, present only if enabled |
+| `group_id` | Set only if the message was sent in a group chat; `nil` otherwise |
 | `id` | The WAMID — pass it to [`mark_message_as_read!`](../messages/mark_message_as_read.md) |
 | `timestamp` | Unix seconds, as a String |
 | `type` | `"text"`, `"image"`, … |
@@ -169,6 +201,15 @@ card.phones.first.phone   # => "+1"
 Nested objects mirror the outbound [contacts message](../messages/contacts.md)
 field-for-field: `Name`, `Phone`, `Email`, `Address`, `Org`, `Url`, plus `birthday`.
 
+When the card arrives from a [`REQUEST_CONTACT_INFO`
+button](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#requesting-phone-numbers-from-users)
+or a direct in-chat share, two more fields are present:
+
+```ruby
+card.origin  # => "contact_request" (button tap) or "other" (shared from the chat)
+card.vcard   # => the raw vCard string when origin is "other"; nil for "contact_request"
+```
+
 ### Interactive
 
 A tap on [reply buttons or a list](../messages/interactive.md).
@@ -253,6 +294,14 @@ message.change_type  # => "customer_changed_number"
 
 Note `change_type`, not `type` — `type` is taken by the message envelope.
 
+When a user's BSUID itself changes (`change_type == "user_changed_user_id"`), the new
+identifiers are also present:
+
+```ruby
+message.user_id         # => the customer's new BSUID
+message.parent_user_id  # => the customer's new parent BSUID, if enabled
+```
+
 ### Reaction
 
 ```json
@@ -264,6 +313,52 @@ message.message_id  # => "wamid.OLD"  — the message being reacted to
 message.emoji       # => "👍"          — empty String when a reaction is removed
 ```
 
+### Revoke
+
+The customer deleted a message they had sent you. A *control* message rather than a
+content one: it names a message you already have instead of carrying a body.
+
+```json
+{ "from": "16505551234", "id": "wamid.HBg", "timestamp": "1749416383",
+  "type": "revoke", "revoke": { "original_message_id": "wamid.ORIGINAL" } }
+```
+
+```ruby
+message.original_message_id  # => "wamid.ORIGINAL" — the message to delete on your side
+message.id                   # => "wamid.HBg" — the revoke notification's own wamid
+```
+
+Also arrives through [`smb_message_echoes`](smb_message_echoes.md) when the *business*
+revokes a message from the WhatsApp Business app.
+
+### Edit
+
+The customer edited a message they had sent you. Names the message being replaced and
+carries the replacement content.
+
+```json
+{ "from": "16505551234", "id": "wamid.HBg", "timestamp": "1749416383",
+  "type": "edit",
+  "edit": { "original_message_id": "wamid.ORIGINAL",
+            "message": { "context": { "id": "wamid.CONTEXT" },
+                         "type": "image",
+                         "image": { "caption": "Now in blue", "id": "media.1" } } } }
+```
+
+```ruby
+message.original_message_id  # => "wamid.ORIGINAL"
+message.message              # => #<Whatsapp::Webhook::Message::Image ...>
+message.message.caption      # => "Now in blue"
+```
+
+`message` is a full nested `Message::*`, dispatched by its own `type` — so an edited
+image behaves exactly like an inbound one. It carries **content only**: the nested
+payload has no `from`/`id`/`timestamp` of its own, so those read `nil`. Use the outer
+`message.id` and `message.from`.
+
+Also arrives through [`smb_message_echoes`](smb_message_echoes.md) when the *business*
+edits a message from the WhatsApp Business app.
+
 ### Unknown
 
 The fallback for a type this gem doesn't model — including anything Meta flags as
@@ -289,7 +384,10 @@ Present when the customer replied to, or forwarded, a message.
 
 ```ruby
 message.context&.id                    # => "wamid.HBg..."  — the message replied to
-message.context&.from                  # => the sender of that message
+message.context&.from                  # => the sender of that message, or nil once
+                                       #    they adopt a username
+message.context&.from_user_id          # => that sender's BSUID
+message.context&.from_parent_user_id   # => their parent BSUID, if enrolled
 message.context&.forwarded             # => true | false
 message.context&.frequently_forwarded  # => true | false
 ```
@@ -297,6 +395,12 @@ message.context&.frequently_forwarded  # => true | false
 `context` is `nil` — not an all-nil object — when the key is absent, so `&.` is the
 right idiom.
 
+`from_user_id`/`from_parent_user_id` carry the quoted sender's identity when their phone
+number is gone, the same way [`from_user_id` does on the message itself](#business-scoped-user-ids-bsuid).
+**Their key names are inferred** by symmetry with `Message::Base` — Meta has not published
+a `context` example carrying them, so validate against a real payload before depending on
+them.
+
 ## Referral
 
 Present when the conversation started from a click-to-WhatsApp ad or post.
@@ -336,15 +440,46 @@ status = value.statuses.first
 status.id            # => "wamid.HBg"      — matches what send! returned
 status.status        # => "delivered"      — sent | delivered | read | failed
 status.timestamp     # => "1750263773"
-status.recipient_id  # => "16505551234"
+status.recipient_id  # => "16505551234", or nil once sent to a BSUID (see below)
 ```
 
 | Accessor | Type |
 | --- | --- |
+| `recipient_user_id` | The recipient's BSUID — sent on every status; see the table below for the `failed` exception |
+| `recipient_parent_user_id` | The recipient's parent BSUID, present only if enabled |
 | `conversation` | `Status::Conversation` — `id`, `origin_type`, `expiration_timestamp` |
 | `pricing` | `Status::Pricing` — `billable`, `pricing_model`, `category` |
 | `errors` | `Array<Webhook::Error>` — populated on `"failed"` |
 
+`recipient_id` is present when you sent the message to a phone number (or when the
+recipient's phone number is otherwise available). `recipient_user_id` is **not** the
+mirror image of that: Meta sends it on every status whatever you addressed, so the two
+routinely arrive together.
+
+### What arrives with which status
+
+| | `sent` | `delivered` | `read` | `failed` |
+| --- | :---: | :---: | :---: | :---: |
+| `recipient_user_id` | always | always | always | only if addressed to a BSUID |
+| `contacts[]` | yes | yes | yes | **omitted entirely** |
+| `contacts[].profile.username` | omitted | if adopted | if adopted | — |
+| `errors` | — | — | — | populated |
+
+Two traps in that table. A `failed` status is the only one that arrives with no
+`contacts` array at all, so code that reads `value.contacts.first` while handling
+failures must tolerate `nil` — `contacts` is always an Array, but an empty one. And a
+`failed` status for a message you addressed to a phone number carries **neither**
+identifier beyond `recipient_id`, so a BSUID-keyed lookup has to fall back to the phone
+number on that path.
+
+```ruby
+# Correlating a failure back to a customer, whichever identifier arrived
+status = value.statuses.first
+customer =
+  Customer.find_by(bsuid: status.recipient_user_id) ||
+  Customer.find_by(wa_id: status.recipient_id)
+```
+
 ```ruby
 status.conversation.id                    # => "6ceb9d9"
 status.conversation.origin_type           # => "service"  | marketing | utility | authentication