ruby-whatsapp 0.4.0 → 0.4.2

data/docs/webhooks/messages.md

@@ -0,0 +1,385 @@
+# `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.
+
+`Whatsapp::Webhook::Messages`
+
+## A full notification
+
+```json
+{
+  "object": "whatsapp_business_account",
+  "entry": [{
+    "id": "102290129340398",
+    "changes": [{
+      "field": "messages",
+      "value": {
+        "messaging_product": "whatsapp",
+        "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
+        "contacts": [{ "profile": { "name": "Sheena Nelson" }, "wa_id": "16505551234" }],
+        "messages": [{
+          "from": "16505551234",
+          "id": "wamid.HBg...",
+          "timestamp": "1749416383",
+          "type": "text",
+          "text": { "body": "Does it come in another color?" }
+        }]
+      }
+    }]
+  }]
+}
+```
+
+```ruby
+value = notification.entry.first.changes.first.value
+
+value.messaging_product           # => "whatsapp"
+value.metadata.phone_number_id    # => "106540352242922"
+value.metadata.display_phone_number # => "15550783881"
+value.contacts.first.profile_name # => "Sheena Nelson"
+value.contacts.first.wa_id        # => "16505551234"
+value.messages.first.body         # => "Does it come in another color?"
+value.statuses                    # => []
+```
+
+## Value accessors
+
+| Accessor | Type |
+| --- | --- |
+| `messaging_product` | `"whatsapp"` |
+| `metadata` | `Metadata` — `display_phone_number`, `phone_number_id` |
+| `contacts` | `Array<Contact>` — `profile_name`, `wa_id` |
+| `messages` | `Array<Message::*>` |
+| `statuses` | `Array<Status>` |
+
+A given notification carries **either** `messages` **or** `statuses`, never both — but
+both accessors always return an array, so you can iterate either without a nil check.
+
+> `contacts` here is the value-level sender identity (who wrote to you). It is a
+> different thing from [`Message::Contacts`](#contacts) below, which is a contact
+> *card* someone shared with you.
+
+---
+
+## Message types
+
+Every entry in `messages` is dispatched by its `type` through the frozen
+`Message::MESSAGE_TYPES` registry. An unrecognized type falls back to
+[`Unknown`](#unknown), never an exception.
+
+All message classes share this envelope from `Message::Base`:
+
+| Accessor | Meaning |
+| --- | --- |
+| `from` | The customer's WhatsApp ID |
+| `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"`, … |
+| `context` | [`Context`](#context) or `nil` — set when replying or forwarding |
+| `referral` | [`Referral`](#referral) or `nil` — set when the chat started from an ad |
+
+### Text
+
+```json
+{ "type": "text", "text": { "body": "Does it come in another color?" } }
+```
+
+```ruby
+message.body   # => "Does it come in another color?"
+```
+
+### Media — image, video, audio, document, sticker
+
+All five share a `Media` superclass:
+
+| Accessor | Meaning |
+| --- | --- |
+| `media_id` | Pass to [`Media#get_url`](../media/README.md) to download it |
+| `mime_type` | `"image/jpeg"`, `"application/pdf"`, … |
+| `sha256` | Content hash |
+| `caption` | Present on image, video, document |
+
+Plus one extra each on three of them:
+
+| Type | Extra |
+| --- | --- |
+| `audio` | `voice` — `true` for a recorded voice note, `false` for an audio file |
+| `document` | `filename` |
+| `sticker` | `animated` |
+
+```json
+{ "type": "document",
+  "document": { "id": "med.4", "mime_type": "application/pdf",
+                "sha256": "abc", "caption": "Invoice", "filename": "invoice.pdf" } }
+```
+
+```ruby
+message.media_id  # => "med.4"
+message.mime_type # => "application/pdf"
+message.filename  # => "invoice.pdf"
+
+# fetch the bytes
+info = Whatsapp::Media.new.get_url(media_id: message.media_id)
+Whatsapp::Media.new.download(url: info["url"], save_to: message.filename)
+```
+
+```json
+{ "type": "audio", "audio": { "id": "med.3", "mime_type": "audio/ogg", "sha256": "abc", "voice": true } }
+```
+
+```ruby
+message.voice     # => true
+```
+
+### Location
+
+```json
+{ "type": "location",
+  "location": { "latitude": 37.4847, "longitude": -122.1477,
+                "name": "Meta HQ", "address": "1 Hacker Way" } }
+```
+
+```ruby
+message.latitude   # => 37.4847
+message.longitude  # => -122.1477
+message.name       # => "Meta HQ"
+message.address    # => "1 Hacker Way"
+```
+
+This is what comes back from a
+[location request](../messages/location_request.md).
+
+### Contacts
+
+A contact *card* the customer shared with you.
+
+```json
+{ "type": "contacts",
+  "contacts": [{ "name": { "formatted_name": "Jane Doe" },
+                 "phones": [{ "phone": "+1", "type": "WORK" }] }] }
+```
+
+```ruby
+card = message.contacts.first
+card.name.formatted_name  # => "Jane Doe"
+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`.
+
+### Interactive
+
+A tap on [reply buttons or a list](../messages/interactive.md).
+
+```json
+{ "type": "interactive",
+  "interactive": { "type": "button_reply",
+                   "button_reply": { "id": "confirm", "title": "Confirm" } } }
+```
+
+```ruby
+message.interactive_type  # => "button_reply"  (or "list_reply")
+message.reply_id          # => "confirm"       — the id you set when sending
+message.title             # => "Confirm"
+message.description       # => nil             — list_reply only
+```
+
+```json
+{ "type": "interactive",
+  "interactive": { "type": "list_reply",
+                   "list_reply": { "id": "espresso", "title": "Espresso",
+                                   "description": "Strong & short" } } }
+```
+
+```ruby
+message.interactive_type  # => "list_reply"
+message.reply_id          # => "espresso"
+message.description       # => "Strong & short"
+```
+
+### Button
+
+A tap on a **template** quick-reply button — distinct from `interactive` above, which
+covers interactive messages.
+
+```json
+{ "type": "button", "button": { "text": "Confirm", "payload": "CONFIRM_PAYLOAD" } }
+```
+
+```ruby
+message.text     # => "Confirm"
+message.payload  # => "CONFIRM_PAYLOAD"
+```
+
+### Order
+
+A cart submitted from your Meta catalog.
+
+```json
+{ "type": "order",
+  "order": { "catalog_id": "cat.1", "text": "Here's my order",
+             "product_items": [{ "product_retailer_id": "sku.1", "quantity": 2,
+                                 "item_price": 9.99, "currency": "USD" }] } }
+```
+
+```ruby
+message.catalog_id                       # => "cat.1"
+message.text                             # => "Here's my order"
+item = message.product_items.first
+item.product_retailer_id                 # => "sku.1"
+item.quantity                            # => 2
+item.item_price                          # => 9.99
+item.currency                            # => "USD"
+```
+
+### System
+
+A change to the customer's account — a new phone number, an identity change.
+
+```json
+{ "type": "system",
+  "system": { "body": "Jane changed to a new phone", "identity": "ABCD1234",
+              "wa_id": "16505551234", "type": "customer_changed_number" } }
+```
+
+```ruby
+message.body         # => "Jane changed to a new phone"
+message.identity     # => "ABCD1234"
+message.wa_id        # => "16505551234"
+message.change_type  # => "customer_changed_number"
+```
+
+Note `change_type`, not `type` — `type` is taken by the message envelope.
+
+### Reaction
+
+```json
+{ "type": "reaction", "reaction": { "message_id": "wamid.OLD", "emoji": "👍" } }
+```
+
+```ruby
+message.message_id  # => "wamid.OLD"  — the message being reacted to
+message.emoji       # => "👍"          — empty String when a reaction is removed
+```
+
+### Unknown
+
+The fallback for a type this gem doesn't model — including anything Meta flags as
+unsupported. It carries the errors and the whole raw hash, so nothing is lost.
+
+```json
+{ "from": "16505551234", "type": "unsupported_future_type",
+  "errors": [{ "code": 131051, "title": "Unsupported message type", "message": "m" }] }
+```
+
+```ruby
+message.type              # => "unsupported_future_type"
+message.errors.first.code # => 131051
+message.errors.first.title # => "Unsupported message type"
+message.raw               # => the complete hash
+```
+
+---
+
+## Context
+
+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&.forwarded             # => true | false
+message.context&.frequently_forwarded  # => true | false
+```
+
+`context` is `nil` — not an all-nil object — when the key is absent, so `&.` is the
+right idiom.
+
+## Referral
+
+Present when the conversation started from a click-to-WhatsApp ad or post.
+
+| Accessor | Meaning |
+| --- | --- |
+| `source_url` | The ad or post URL |
+| `source_type` | `"ad"` or `"post"` |
+| `source_id` | The ad or post ID |
+| `headline` | Ad headline |
+| `body` | Ad body |
+| `media_type` | `"image"` or `"video"` |
+| `image_url` `video_url` `thumbnail_url` | Creative assets |
+
+```ruby
+message.referral&.source_type  # => "ad"
+message.referral&.headline     # => "Big sale"
+```
+
+---
+
+## Statuses
+
+Delivery receipts for messages **you** sent. They arrive on the same `messages` field.
+
+```json
+{ "id": "wamid.HBg", "status": "delivered", "timestamp": "1750263773",
+  "recipient_id": "16505551234",
+  "conversation": { "id": "6ceb9d9", "origin": { "type": "service" } },
+  "pricing": { "billable": true, "pricing_model": "CBP", "category": "service" },
+  "errors": [{ "code": 131026, "title": "Message undeliverable", "message": "m" }] }
+```
+
+```ruby
+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"
+```
+
+| Accessor | Type |
+| --- | --- |
+| `conversation` | `Status::Conversation` — `id`, `origin_type`, `expiration_timestamp` |
+| `pricing` | `Status::Pricing` — `billable`, `pricing_model`, `category` |
+| `errors` | `Array<Webhook::Error>` — populated on `"failed"` |
+
+```ruby
+status.conversation.id                    # => "6ceb9d9"
+status.conversation.origin_type           # => "service"  | marketing | utility | authentication
+status.conversation.expiration_timestamp  # => when the 24-hour window closes
+
+status.pricing.billable       # => true
+status.pricing.pricing_model  # => "CBP"
+status.pricing.category       # => "service"
+```
+
+Correlating a status back to your own record:
+
+```ruby
+response = Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi")
+OutboundMessage.create!(wamid: response.messages.first.id)
+
+# ... later, in the webhook handler
+value.statuses.each do |status|
+  OutboundMessage.find_by(wamid: status.id)&.update!(state: status.status)
+end
+```
+
+## Errors
+
+`Whatsapp::Webhook::Error` is a **value object**, not an exception — it models Meta's
+error payloads on `Status#errors` and `Message::Unknown#errors`.
+
+```ruby
+error = status.errors.first
+error.code     # => 131026
+error.title    # => "Message undeliverable"
+error.message  # => "m"
+error.details  # => dug from error_data.details
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview>

data/docs/webhooks/partner_solutions.md

@@ -0,0 +1,35 @@
+# `partner_solutions`
+
+Lifecycle events for a Tech Provider "solution" — the packaged onboarding a partner
+offers to its own customers.
+
+`Whatsapp::Webhook::PartnerSolutions` · confidence: **low**
+
+## Payload
+
+```json
+{ "field": "partner_solutions", "value": { "solution_id": "sol.1", "event": "DISCONNECTED" } }
+```
+
+## Accessors
+
+| Accessor | Meaning |
+| --- | --- |
+| `solution_id` | The solution's ID |
+| `event` | e.g. `CONNECTED`, `DISCONNECTED` |
+
+## Handling it
+
+```ruby
+when "partner_solutions"
+  Solution.find_by(meta_id: change.value.solution_id)&.update!(state: change.value.event)
+```
+
+Relevant only if you operate as a Tech Provider. Most integrations never see it.
+
+> **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/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,53 @@
+# `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: **low-moderate**
+
+## Payload
+
+```json
+{ "field": "smb_app_state_sync",
+  "value": { "state_sync": [{ "type": "contact",
+                              "action": "add",
+                              "contact": { "full_name": "Jane Doe", "phone_number": "+1" } }] } }
+```
+
+## Accessors
+
+| Accessor | Type |
+| --- | --- |
+| `state_sync` | `Array<SmbAppStateSync::StateSync>` |
+
+### `StateSync`
+
+| Accessor | Meaning |
+| --- | --- |
+| `type` | e.g. `contact` |
+| `action` | e.g. `add`, `update`, `remove` |
+| `contact` | **Raw Hash** — the shape is undocumented |
+
+## 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(sync.contact)
+    when "remove"
+      Contact.find_by(phone: sync.contact["phone_number"])&.destroy
+    end
+  end
+```
+
+> **Best-effort schema, low-moderate confidence.** `contact` is left as a raw hash
+> precisely because its keys are unverified. 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_message_echoes.md

@@ -0,0 +1,54 @@
+# `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.
+
+`Whatsapp::Webhook::SmbMessageEchoes` · confidence: **moderate**
+
+## Payload
+
+```json
+{ "field": "smb_message_echoes",
+  "value": { "messaging_product": "whatsapp",
+             "metadata": { "display_phone_number": "15550783881",
+                           "phone_number_id": "106540352242922" },
+             "message_echoes": [{ "from": "15550783881",
+                                  "type": "text",
+                                  "text": { "body": "Thanks for shopping with us!" } }] } }
+```
+
+## Accessors
+
+| Accessor | Type |
+| --- | --- |
+| `messaging_product` | `"whatsapp"` |
+| `metadata` | `Metadata` — `display_phone_number`, `phone_number_id` |
+| `message_echoes` | `Array<Message::*>` |
+
+`message_echoes` reuses the same `Message.deserialize` dispatcher as
+[`messages`](messages.md), so every echoed message is a fully typed `Message::Text`,
+`Message::Image`, and so on — with the same accessors.
+
+## Handling it
+
+```ruby
+when "smb_message_echoes"
+  change.value.message_echoes.each do |echo|
+    Conversation.for(echo.from).messages.create!(
+      wamid: echo.id, direction: :outbound, source: :business_app, body: echo.try(:body)
+    )
+  end
+```
+
+Note `from` is *your* business number here, not the customer's — these are messages
+you sent.
+
+> **Moderate confidence on structure, low on the key name.** Meta states these mirror
+> the standard message shape, which is why `Message.deserialize` is reused, but the
+> exact `message_echoes` key is unverified. Validate against a real payload before
+> depending on it in production.
+
+---
+
+**Meta docs:** https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview