ruby-whatsapp 0.4.0 → 0.6.1

data/docs/messages/template.md

@@ -0,0 +1,193 @@
+# 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` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `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
+```
+
+### Authentication templates cannot go to a BSUID
+
+One-tap, zero-tap, and copy-code
+[authentication templates](../message_templates/authentication.md) require the
+recipient's **phone number**. Address one to a
+[BSUID](README.md#business-scoped-user-ids-bsuid) via `recipient:` and Meta answers
+with error `131062`:
+
+```
+Business-scoped User ID (BSUID) recipients are not supported for this message.
+```
+
+The gem cannot catch this locally, and deliberately does not try. A template is
+addressed at send time by `name` and `language` only — `Messages::Template` never
+learns its own category, and the OTP configuration lives in the WABA. Guessing from
+`components` would be worse than not guessing: a `copy_code` sub-type appears both on
+copy-code authentication templates *and* on limited-time-offer marketing templates,
+which have no such restriction, so any local rule would reject valid sends.
+
+If you need to reach a username-only user with an authentication template, ask for
+their phone number first — see the `REQUEST_CONTACT_INFO` button in
+[components.md](../message_templates/components.md).
+
+> Meta names one-tap, zero-tap, and copy-code specifically. Whether a plain
+> `NO_BUTTONS` authentication template is also refused is **not documented** — treat it
+> as untested rather than assuming either way.
+
+## 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` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `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` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `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/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/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>