ruby-whatsapp 0.4.0 → 0.4.2

data/docs/messages/mark_message_as_read.md

@@ -0,0 +1,84 @@
+# Mark Message As Read
+
+Closes the read-receipt loop — this is what turns on the blue "seen" checkmarks on the
+customer's side. Marking one message read also marks **every earlier message in that
+conversation** as read.
+
+```ruby
+Whatsapp::Messages.mark_message_as_read!(
+  message_id: "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBJDQjZCMzlEQUE4OTJBMTE4RTUA"
+)
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `message_id` | yes | The WAMID of an inbound message |
+| `client` | no | Defaults to a new `Whatsapp::Client` |
+
+`message_id` is checked for presence only — there is no WAMID format check, so an
+invalid ID surfaces server-side as error `131009`.
+
+> **30-day window.** Meta requires the call within 30 days of receiving the message.
+> Past that, the request fails.
+
+## Why it isn't a `send_<kind>!` method
+
+Every other kind shares the `to` / `recipient_type` / `type` envelope from
+`Messages::Base`. This endpoint's payload is flat — no recipient, no type — so
+`MarkMessageAsRead` doesn't inherit `Base` at all and isn't registered in
+`Messages::KINDS`. Rather than carve an exception into the loop that generates
+`send_<kind>!` methods, it gets its own hand-written class method.
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::MarkMessageAsRead.new(message_id: "wamid.HBg...").serialize
+# => { messaging_product: "whatsapp", status: "read", message_id: "wamid.HBg..." }
+```
+
+## The response
+
+This endpoint replies `{"success": true}` rather than the usual
+`{messaging_product, contacts, messages}`, so the shared `Messages::Response` carries
+it on `#success`:
+
+```ruby
+result = Whatsapp::Messages.mark_message_as_read!(message_id: "wamid.HBg...")
+
+result.success   # => true
+result.messages  # => []  — nothing to report for this endpoint
+result.contacts  # => []
+```
+
+## Errors
+
+```ruby
+Whatsapp::Messages::MarkMessageAsRead.new(message_id: "")
+# => ActiveModel::ValidationError: Message can't be blank
+```
+
+A non-2xx response raises `Whatsapp::RequestError: Failed to mark message as read: ...`.
+
+## Typical use
+
+Call it from your webhook handler as soon as an inbound message is deserialized:
+
+```ruby
+notification.entry.each do |entry|
+  entry.changes.each do |change|
+    next unless change.field == "messages"
+
+    change.value.messages.each do |message|
+      Whatsapp::Messages.mark_message_as_read!(message_id: message.id)
+    end
+  end
+end
+```
+
+See [../webhooks/messages.md](../webhooks/messages.md) for the inbound side.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/mark-message-as-read>

data/docs/messages/reaction.md

@@ -0,0 +1,59 @@
+# Reaction Messages
+
+Acknowledges a previous message with an emoji, mirroring WhatsApp's native
+tap-and-hold reaction, without cluttering the thread with a new text message.
+
+```ruby
+Whatsapp::Messages.send_reaction!(to: "+15551234567", message_id: "wamid.HBg...", emoji: "👍")
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `message_id` | yes | The WAMID of the message being reacted to |
+| `emoji` | yes | A single emoji, or `""` to remove |
+
+`emoji` is checked against Ruby's `\p{Emoji}` property, so a plain word is rejected
+locally rather than by Meta. `nil` is invalid; the empty string is not.
+
+## Removing a reaction
+
+Sending an empty `emoji` removes a reaction you previously sent to that message:
+
+```ruby
+Whatsapp::Messages.send_reaction!(to: "+15551234567", message_id: "wamid.HBg...", emoji: "")
+```
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Reaction.new(
+  to: "+15551234567", message_id: "wamid.HBg...", emoji: "\u{1F44D}"
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "reaction",
+#   reaction: { message_id: "wamid.HBg...", emoji: "👍" }
+# }
+```
+
+The `reaction` hash is not compacted — both keys always ship, which is what makes the
+empty-string removal work.
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_reaction!(to: "+15551234567", message_id: "wamid.HBg...", emoji: "nope")
+# => ActiveModel::ValidationError: Emoji must be a valid emoji character
+
+Whatsapp::Messages.send_reaction!(to: "+15551234567", message_id: "wamid.HBg...", emoji: nil)
+# => ActiveModel::ValidationError: Emoji can't be nil
+```
+
+`message_id` is checked for presence only — an existent-looking but wrong WAMID
+surfaces server-side as error `131009`.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/reaction-messages>

data/docs/messages/sticker.md

@@ -0,0 +1,40 @@
+# Sticker Messages
+
+Sends a WhatsApp sticker asset (a WebP image, animated or static).
+
+```ruby
+Whatsapp::Messages.send_sticker!(to: "+15551234567", id: "STICKER_MEDIA_ID")
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `id` | one of | A media ID from [`Media#upload`](../media/README.md) |
+| `link` | one of | A publicly reachable HTTPS URL |
+
+**Either `id` or `link` is required** — prefer `id`. Stickers are almost always
+reused across many conversations, so uploading once and holding the ID avoids
+re-fetching the same asset on every send.
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Sticker.new(to: "+15551234567", id: "STICKER_MEDIA_ID").serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "sticker",
+#   sticker: { id: "STICKER_MEDIA_ID" }
+# }
+```
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_sticker!(to: "+15551234567")
+# => ActiveModel::ValidationError: Either id or link must be present
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/sticker-messages>

data/docs/messages/template.md

@@ -0,0 +1,166 @@
+# Template Messages
+
+The **only** way to message a user outside the 24-hour customer-service window.
+Marketing, utility, and authentication templates must be created and approved by Meta
+before they can be sent.
+
+> **Two different APIs.** This page covers *sending* an already-approved template
+> (`POST /{PHONE_ID}/messages`). Creating, editing, and deleting the templates
+> themselves is a separate API addressing `waba_id` — see
+> [../message_templates/](../message_templates/README.md). The component schemas are
+> **not** interchangeable: management uses `text` + `example` with uppercase
+> `HEADER`/`BODY`/`FOOTER`, sending uses `parameters` with lowercase singular types.
+
+```ruby
+Whatsapp::Messages.send_template!(
+  to: "+15551234567",
+  name: "order_confirmation",
+  language: { code: "en_US" }
+)
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `name` | yes | The approved template's name |
+| `language` | yes | `{ code: "en_US" }` — validated against the supported list |
+| `components` | no | Array of components supplying placeholder values. Defaults to `[]` |
+
+`language.code` is checked against `Whatsapp::Utils::LanguageCodes` (71 codes), so a
+typo raises locally instead of coming back as a Meta error:
+
+```ruby
+Whatsapp::Utils::LanguageCodes.valid?("en_US")  # => true
+Whatsapp::Utils::LanguageCodes.all.size         # => 71
+```
+
+## Components
+
+A component supplies the *values* for the placeholders the template defines. It has a
+`type`, and for buttons a `sub_type` and `index`.
+
+| `type` | Purpose |
+| --- | --- |
+| `"header"` | Values for the header's placeholder |
+| `"body"` | Values for the body's placeholders |
+| `"button"` | Values for a dynamic button — also needs `sub_type` and `index` |
+
+Each component holds `parameters`, and each parameter has a `type` selecting exactly
+one value key:
+
+| Parameter `type` | Value key | Shape |
+| --- | --- | --- |
+| `"text"` | `text` | String |
+| `"currency"` | `currency` | `{ fallback_value:, code:, amount_1000: }` |
+| `"date_time"` | `date_time` | `{ fallback_value: }` |
+| `"image"` | `image` | `{ link: }` or `{ id: }` |
+| `"document"` | `document` | `{ link: }` or `{ id: }` |
+| `"video"` | `video` | `{ link: }` or `{ id: }` |
+| `"location"` | `location` | `{ latitude:, longitude:, name:, address: }` |
+| `"payload"` | `payload` | String — a quick-reply button's payload |
+
+> Only `type` is validated. There is no cross-field check that the matching value key
+> is populated, so `{ type: "text" }` with no `text` serializes to a bare
+> `{ type: "text" }` and is rejected by Meta rather than locally.
+
+## Examples
+
+**Body placeholders:**
+
+```ruby
+Whatsapp::Messages.send_template!(
+  to: "+15551234567",
+  name: "order_confirmation",
+  language: { code: "en_US" },
+  components: [
+    { type: "body", parameters: [{ type: "text", text: "Jane" },
+                                 { type: "text", text: "860198-230332" }] },
+  ]
+)
+```
+
+**Media header plus body:**
+
+```ruby
+Whatsapp::Messages.send_template!(
+  to: "+15551234567",
+  name: "shipping_update",
+  language: { code: "en_US" },
+  components: [
+    { type: "header", parameters: [{ type: "image", image: { link: "https://example.com/box.jpg" } }] },
+    { type: "body",   parameters: [{ type: "text", text: "Jane" }] },
+  ]
+)
+```
+
+**A dynamic URL button** — `sub_type` and `index` identify which button in the
+template's button row is being filled:
+
+```ruby
+Whatsapp::Messages.send_template!(
+  to: "+15551234567",
+  name: "order_confirmation",
+  language: { code: "en_US" },
+  components: [
+    { type: "body",   parameters: [{ type: "text", text: "Jane" }] },
+    { type: "button", sub_type: "url", index: 0,
+      parameters: [{ type: "text", text: "1234" }] },
+  ]
+)
+```
+
+**A currency and a date:**
+
+```ruby
+components: [
+  { type: "body", parameters: [
+    { type: "currency", currency: { fallback_value: "$100.99", code: "USD", amount_1000: 100_990 } },
+    { type: "date_time", date_time: { fallback_value: "February 25, 1977" } },
+  ] },
+]
+```
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Template.new(
+  to: "+15551234567",
+  name: "order_confirmation",
+  language: { code: "en_US" },
+  components: [
+    { type: "body", parameters: [{ type: "text", text: "Jane" }, { type: "text", text: "#1234" }] },
+  ]
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "template",
+#   template: {
+#     name: "order_confirmation",
+#     language: { code: "en_US" },
+#     components: [{ type: "body", parameters: [{ type: "text", text: "Jane" },
+#                                               { type: "text", text: "#1234" }] }]
+#   }
+# }
+```
+
+With no components, the `components` key is dropped entirely rather than sent empty.
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_template!(to: "+15551234567", name: "x", language: { code: "klingon" })
+# => ActiveModel::ValidationError: Code is not a valid WhatsApp language code.
+#    Supported codes: af, sq, ar, az, bn, bg, ca, zh_CN, ...
+
+Whatsapp::Messages.send_template!(to: "+15551234567", name: "", language: { code: "en_US" })
+# => ActiveModel::ValidationError: Name can't be blank
+```
+
+`name` is checked for presence only — an unapproved or misspelled template name comes
+back from Meta, not from the validator.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/template-messages>
+· [supported languages](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/supported-languages)

data/docs/messages/text.md

@@ -0,0 +1,55 @@
+# Text Messages
+
+The default way to carry a conversational reply or notice. Most other kinds exist
+because they need to express something plain text can't — media, buttons, structured
+data.
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hello from ruby-whatsapp!")
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `body` | yes | Max **4096** characters |
+| `preview_url` | no | `true` or `false`. **Defaults to `true`** |
+
+`preview_url` controls whether WhatsApp renders a link preview card for the first URL
+in the body. Turn it off for transactional messages where a preview would be noise:
+
+```ruby
+Whatsapp::Messages.send_text!(
+  to: "+15551234567",
+  body: "Track your order: https://example.com/orders/1234",
+  preview_url: false
+)
+```
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Text.new(to: "+15551234567", body: "Hello from ruby-whatsapp!").serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "text",
+#   text: { body: "Hello from ruby-whatsapp!", preview_url: true }
+# }
+```
+
+The `text` hash is deliberately **not** compacted, so `preview_url` is always present
+on the wire even when it holds its default.
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "")
+# => ActiveModel::ValidationError: Body can't be blank
+
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "x" * 4097)
+# => ActiveModel::ValidationError: Body is too long (maximum is 4096 characters)
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/text-messages>

data/docs/messages/video.md

@@ -0,0 +1,41 @@
+# Video Messages
+
+Shares a video — an instructional clip, a product demo, an unboxing.
+
+```ruby
+Whatsapp::Messages.send_video!(to: "+15551234567", id: "1234567890", caption: "Demo video")
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `id` | one of | A media ID from [`Media#upload`](../media/README.md) |
+| `link` | one of | A publicly reachable HTTPS URL |
+| `caption` | no | Max **1024** characters |
+
+**Either `id` or `link` is required.** Videos are the kind where uploading once and
+reusing the `id` pays off most — a `link` makes Meta re-download the whole file on
+every single send.
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Video.new(to: "+15551234567", id: "1234567890", caption: "Demo video").serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "video",
+#   video: { id: "1234567890", caption: "Demo video" }
+# }
+```
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_video!(to: "+15551234567")
+# => ActiveModel::ValidationError: Either id or link must be present
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/video-messages>

data/docs/subscribed_app/README.md

@@ -0,0 +1,139 @@
+# Managing Subscribed Apps
+
+Before your app receives any [webhook](../webhooks/README.md) notifications for a
+WhatsApp Business Account, it has to be **subscribed** to it.
+`Whatsapp::SubscribedApp` wraps the `subscribed_apps` edge — the switch that turns
+webhook delivery on or off.
+
+> **Two halves of one thing.** This module makes Meta start sending;
+> [`Whatsapp::Webhook`](../webhooks/README.md) deserializes what arrives. Neither is
+> useful without the other.
+
+Addresses your **WhatsApp Business Account** (`waba_id`, not `phone_id`) and needs the
+`whatsapp_business_management` permission — same as
+[template management](../message_templates/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::SubscribedApp::Subscribe.call            # start webhook delivery
+Whatsapp::SubscribedApp::List.call.map(&:name)     # => ["My App"]
+Whatsapp::SubscribedApp::Unsubscribe.call          # stop it
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `List.call(client:, fields:)` | `GET /{waba_id}/subscribed_apps` | `Response::Collection` |
+| `Subscribe.call(client:, override_callback_uri:, verify_token:)` | `POST /{waba_id}/subscribed_apps` | `Response::Subscription` |
+| `Unsubscribe.call(client:)` | `DELETE /{waba_id}/subscribed_apps` | `Response::Unsubscription` |
+
+Three independent actions, so three classes rather than one class with three methods —
+unlike [templates](../message_templates/README.md), subscribing and listing share no
+identity or validation rules that would justify combining them.
+
+## Subscribing
+
+```ruby
+result = Whatsapp::SubscribedApp::Subscribe.call
+
+result.success       # => true
+result.map(&:name)   # => ["My App"] — every app now subscribed, Meta's own echo
+```
+
+`Response::Subscription` is `Enumerable` over the same `Response::App` objects `List`
+returns, so you can check the result without a second request.
+
+### Per-WABA callback overrides
+
+Tech Providers routing several WABAs' notifications to different callback URLs pass an
+override instead of relying on the single callback URL configured on the app itself:
+
+```ruby
+Whatsapp::SubscribedApp::Subscribe.call(
+  override_callback_uri: "https://example.com/webhooks/acme_corp",
+  verify_token: "a-per-account-secret"
+)
+```
+
+Both are optional and compacted out of the request body when absent. The
+`verify_token` you pass here is the one Meta will send in the
+[GET handshake](../webhooks/README.md#verification-the-get-handshake) for that WABA —
+pass the matching value to `Verification.call(verify_token:)`.
+
+> No client-side format check is applied to `override_callback_uri`. Meta enforces it
+> server-side, and this gem validates only what Meta documents as a client-side rule.
+
+## Listing
+
+```ruby
+apps = Whatsapp::SubscribedApp::List.call
+
+apps.map(&:name)   # Collection is Enumerable
+apps.first.id      # => "123456789"
+apps.first.link    # => "https://www.facebook.com/games/?app_id=..."
+apps.first.override_callback_uri  # => nil, or the per-WABA override
+```
+
+Restrict what comes back with `fields:` — an Array or a String, comma-joined for you:
+
+```ruby
+Whatsapp::SubscribedApp::List.call(fields: %w[id name])
+Whatsapp::SubscribedApp::List.call(fields: "id,name")
+```
+
+`Response::App` flattens Meta's `whatsapp_business_api_data` wrapper, so `id`, `name`,
+and `link` sit directly on the object rather than a nested hash.
+
+> No pagination — Meta documents none for this edge, and an account typically has very
+> few subscribed apps.
+
+## Unsubscribing
+
+```ruby
+Whatsapp::SubscribedApp::Unsubscribe.call.success   # => true
+```
+
+Stops **all** webhook deliveries for this WABA immediately.
+
+## Response shapes
+
+Three actions, three genuinely different shapes — hence three classes:
+
+| Class | Holds | From |
+| --- | --- | --- |
+| `Response::Collection` | `data: [App]`, `Enumerable` | `List` |
+| `Response::Subscription` | `success`, `data: [App]`, `Enumerable` | `Subscribe` |
+| `Response::Unsubscription` | `success` | `Unsubscribe` |
+
+`Response::App` — `id`, `name`, `link`, `override_callback_uri` — is composed by both
+`Collection` and `Subscription` rather than duplicated.
+
+`success` is a strict `response["success"] == true`, so it is never a truthy string
+you have to second-guess.
+
+## Errors
+
+```ruby
+Whatsapp::SubscribedApp::Subscribe.call
+# => Whatsapp::SubscribedApp::Error: waba_id is required for subscribed apps;
+#    set it via Whatsapp.configure or Client.new(waba_id:)
+
+# non-2xx response
+# => Whatsapp::SubscribedApp::Error: Failed to subscribe app: 400 Bad Request - {...}
+```
+
+Every action raises `Whatsapp::SubscribedApp::Error` — never the generic
+`Whatsapp::RequestError`. See [../errors.md](../errors.md).
+
+## Targeting a different account
+
+```ruby
+Whatsapp::SubscribedApp::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/subscribed-apps-api>