ruby-whatsapp 0.4.0 → 0.4.2

data/docs/message_templates/README.md

@@ -0,0 +1,206 @@
+# Managing Message Templates
+
+[Sending a template](../messages/template.md) requires one that already exists and has
+been approved by Meta. `Whatsapp::MessageTemplates` creates and manages those
+templates, so they can live in your codebase and ship from CI instead of being clicked
+together in WhatsApp Manager.
+
+Addresses your **WhatsApp Business Account** (`waba_id`, not `phone_id`) and needs the
+`whatsapp_business_management` permission.
+
+```ruby
+Whatsapp.configure do |config|
+  config.api_key = ENV.fetch("WHATSAPP_API_KEY")
+  config.waba_id = ENV.fetch("WHATSAPP_WABA_ID")
+end
+
+templates = Whatsapp::MessageTemplates.new    # or .new(client: my_client)
+```
+
+Omitting `waba_id` raises `TemplateError` before any request is made.
+
+## The one thing to internalise
+
+"Template" means two unrelated payload schemas depending on direction:
+
+| | **Management** (this directory) | **Sending** ([`../messages/template.md`](../messages/template.md)) |
+| --- | --- | --- |
+| Endpoint | `POST /{WABA_ID}/message_templates` | `POST /{PHONE_ID}/messages` |
+| ID | `client.waba_id` | `client.phone_id` |
+| Permission | `whatsapp_business_management` | `whatsapp_business_messaging` |
+| Defines | the template *shape*, with placeholders | the *values* for those placeholders |
+| Component key | `text` + `example` | `parameters` |
+| Component types | `HEADER` `BODY` `FOOTER` `BUTTONS` (uppercase) | `header` `body` `button` (lowercase) |
+| Buttons | one `BUTTONS` component holding N buttons | N `button` components with `sub_type` + `index` |
+
+The same template, both sides:
+
+```jsonc
+// MANAGEMENT: define the placeholder and give Meta a sample value for review
+{ "type": "BODY",
+  "text": "Thank you, {{1}}! Your order number is {{2}}.",
+  "example": { "body_text": [["Pablo", "860198-230332"]] } }
+
+// SENDING: supply real values. No text. No example.
+{ "type": "body",
+  "parameters": [{ "type": "text", "text": "Pablo" },
+                 { "type": "text", "text": "860198-230332" }] }
+```
+
+## API
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `create(**attrs)` | `POST /{waba_id}/message_templates` | [`Response::Created`](responses.md#created) |
+| `create_from_library(**attrs)` | same edge, [library payload](library.md) | [`Response::Created`](responses.md#created) |
+| `upsert(**attrs)` | `POST /{waba_id}/upsert_message_templates` | [`Response::Created`](responses.md#created) |
+| `list(**filters)` | `GET /{waba_id}/message_templates` | [`Response::Collection`](responses.md#collection) |
+| `find(template_id:, fields:)` | `GET /{template_id}` | [`Response::Node`](responses.md#node) |
+| `update(template_id:, **attrs)` | `POST /{template_id}` | `Boolean` |
+| `delete(name:/hsm_id:/hsm_ids:)` | `DELETE /{waba_id}/message_templates` | `Boolean` |
+
+`update` is a **POST to the template's own ID** — `PUT`/`PATCH` are unsupported on
+this edge.
+
+## Template kinds
+
+| Kind | Page |
+| --- | --- |
+| Standard utility / marketing | [standard.md](standard.md) |
+| Authentication (OTP) | [authentication.md](authentication.md) |
+| Marketing carousel | [carousel.md](carousel.md) |
+| Limited-time offer | [limited_time_offer.md](limited_time_offer.md) |
+| Library (pre-written by Meta) | [library.md](library.md) |
+
+See [components.md](components.md) for the full component and button reference, and
+[responses.md](responses.md) for what comes back.
+
+## Template anatomy
+
+| Field | Rules |
+| --- | --- |
+| `name` | `/\A[a-z0-9_]+\z/`, max **512**. Not unique — one per `(name, language)` pair |
+| `language` **XOR** `languages` | Singular for `create`, the array for `upsert` |
+| `category` | `AUTHENTICATION` \| `MARKETING` \| `UTILITY` |
+| `parameter_format` | `POSITIONAL` (default) \| `NAMED` |
+| `sub_category` | `ORDER_DETAILS` \| `ORDER_STATUS` \| `RICH_ORDER_STATUS` |
+| `message_send_ttl_seconds` | Integer |
+| `allow_category_change` | A no-op since 2025-04-09 |
+| `cta_url_link_tracking_opted_out` | Boolean |
+
+Enum values accept either casing and are emitted uppercase — `category: "utility"`
+and `category: "UTILITY"` both work.
+
+## Reading and paging
+
+```ruby
+page = templates.list(status: %w[APPROVED], fields: %w[name category status], limit: 25)
+
+page.select(&:approved?).map(&:name)   # Collection is Enumerable
+page.remaining                         # headroom against your account's template cap
+templates.list(after: page.next_cursor) if page.next_cursor
+```
+
+Documented filters: `name`, `name_or_content`, `content`, `language`, `category`,
+`status`, `quality_score`, `since`, `until`, `fields`, `limit`, `after`, `before`.
+Array values are JSON-encoded (`status: %w[APPROVED PAUSED]` → `status=["APPROVED","PAUSED"]`)
+**except** `fields`, which is comma-joined.
+
+```ruby
+template = templates.find(template_id: "1259544702043867")
+
+template.status      # => "APPROVED"
+template.editable?   # => true
+template.components  # => raw hashes — Meta's echo, deliberately not re-validated
+```
+
+## Editing
+
+Components are a **full replacement** — there is no partial component edit.
+
+```ruby
+templates.update(template_id: "564750795574598", category: "MARKETING")   # => true
+templates.update(template_id: "564750795574598", components: [
+  { type: :header, format: "TEXT", text: "Our {{1}} is on!", example: ["Spring Sale"] },
+  { type: :body,   text: "Shop now through {{1}}.",          example: ["the end of April"] },
+])                                                                        # => true
+```
+
+Only `APPROVED`, `REJECTED`, and `PAUSED` templates are editable (`Node#editable?`).
+Editing an approved template re-submits it for review, but it keeps working meanwhile.
+
+> **Edit rate limits.** Approved templates allow 10 edits per 30 days and 1 per 24
+> hours. Neither is checkable locally — they surface as API errors.
+
+## Deleting
+
+Three mutually exclusive modes:
+
+```ruby
+templates.delete(name: "order_confirmation")                       # ALL language variants
+templates.delete(hsm_id: "1407680676729941", name: "order_confirmation")
+templates.delete(hsm_ids: %w[1387372356726668 1304694804498707])   # up to 100
+```
+
+> Deleting an approved template blocks reuse of its name for **30 days**. `DISABLED`
+> templates cannot be deleted at all.
+
+## Lifecycle
+
+Only `APPROVED` templates can be sent. Review is asynchronous and can take 24 hours.
+The outcome arrives by **webhook**, not by polling — `#find` is the fallback, not the
+intended path:
+
+| Webhook field | Page |
+| --- | --- |
+| `message_template_status_update` | [../webhooks/message_template_status_update.md](../webhooks/message_template_status_update.md) |
+| `message_template_quality_update` | [../webhooks/message_template_quality_update.md](../webhooks/message_template_quality_update.md) |
+| `message_template_components_update` | [../webhooks/message_template_components_update.md](../webhooks/message_template_components_update.md) |
+| `template_category_update` | [../webhooks/template_category_update.md](../webhooks/template_category_update.md) |
+
+Statuses: `APPROVED` `PENDING` `REJECTED` `PAUSED` `DISABLED` `IN_APPEAL`
+`PENDING_DELETION` `DELETED` `LIMIT_EXCEEDED` `ARCHIVED`.
+
+## Errors
+
+Every failure raises `Whatsapp::MessageTemplates::TemplateError`, except local
+validation failures, which raise `ActiveModel::ValidationError`.
+
+```ruby
+templates.create(name: "Order Confirmation", ...)
+# => ActiveModel::ValidationError: Name must contain only lowercase alphanumeric
+#    characters and underscores
+
+templates.create(..., components: [{ type: :body, text: "Hi {{1}} and {{2}}", example: ["Pablo"] }])
+# => ActiveModel::ValidationError: Example does not match the body text:
+#    2 placeholders but 1 example
+
+templates.upsert(name: "x", language: "en_US", ...)
+# => Whatsapp::MessageTemplates::TemplateError: #upsert requires `languages:`
+#    (an array of locale codes); use #create for a single one
+
+templates.delete(hsm_ids: [], name: "x")
+# => Whatsapp::MessageTemplates::TemplateError: hsm_ids cannot be combined with name or hsm_id
+```
+
+## Not wrapped
+
+- **Media upload for template headers.** A media header takes a `header_handle` you
+  already hold. Producing one needs Meta's **Resumable Upload API**, which this gem
+  does not wrap — and it is a *different flow* from
+  [`Media#upload`](../media/README.md), whose media IDs are for *sending*, not
+  template creation.
+- **Undocumented button types:** `FLOW`, `MPM`, `CATALOG`, `VOICE_CALL`, `VIDEO_CALL`,
+  `POSTBACK`, `BOOKING_STATUS`, `PAYMENT_REQUEST`, `REQUEST_CONTACT_INFO`. Named in
+  Meta's Graph enum with no published field reference.
+  [`LibraryTemplate`](library.md) does accept most of them, because Meta documents them
+  by name in *that* context.
+- **Undocumented component types:** `GREETING`, `ALBUM`, `CALL_PERMISSION_REQUEST`,
+  `TAP_TARGET_CONFIGURATION`, `ATTACHMENT`.
+- The `compare` edge, `message_template_previews`, library browsing,
+  archive/unarchive, auto-pagination on `#list`, and the Marketing Messages API fields
+  (`bid_spec`, `optimization_spec`, `degrees_of_freedom_spec`, `product_set_id`).
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview>

data/docs/message_templates/authentication.md

@@ -0,0 +1,107 @@
+# Authentication Templates
+
+One-time-password templates invert the usual shape: **Meta supplies and localises the
+wording**, so you pass flags rather than text. That's also why they're normally created
+for every language at once with `upsert` instead of `create`.
+
+```ruby
+templates = Whatsapp::MessageTemplates.new
+
+templates.upsert(
+  name: "authentication_code", languages: %w[en_US es_ES fr], category: "AUTHENTICATION",
+  components: [
+    { type: :body, add_security_recommendation: true },
+    { type: :footer, code_expiration_minutes: 15 },
+    { type: :buttons, buttons: [{ type: :otp, otp_type: "COPY_CODE" }] },
+  ]
+)
+```
+
+`upsert` requires `languages:` (an array). Passing `language:` raises:
+
+```ruby
+templates.upsert(name: "x", language: "en_US", category: "AUTHENTICATION", components: [...])
+# => Whatsapp::MessageTemplates::TemplateError: #upsert requires `languages:`
+#    (an array of locale codes); use #create for a single one
+```
+
+## The flag-based components
+
+| Component | Field | Meaning |
+| --- | --- | --- |
+| `body` | `add_security_recommendation: true` | Appends Meta's "don't share this code" line |
+| `footer` | `code_expiration_minutes: 1..90` | Renders "This code expires in N minutes" |
+| `buttons` | one `otp` button | How the user gets the code out of the message |
+
+Body and footer are **XOR** with their text forms — an authentication `body` takes
+`add_security_recommendation` *or* `text`, never both:
+
+```ruby
+{ type: :body, text: "Your code is {{1}}", add_security_recommendation: true }
+# => ActiveModel::ValidationError: Text cannot be combined with add_security_recommendation
+```
+
+## OTP button types
+
+| `otp_type` | Behaviour | Extra requirements |
+| --- | --- | --- |
+| `COPY_CODE` | Shows a "copy code" button | — |
+| `ONE_TAP` | Autofills your app on tap | `supported_apps` required |
+| `ZERO_TAP` | Autofills with no tap at all | `supported_apps` **and** `zero_tap_terms_accepted: true` |
+| `NO_BUTTONS` | Plain text, user copies manually | — |
+
+```ruby
+templates.upsert(
+  name: "authentication_code_autofill_button", languages: %w[en_US es_ES fr],
+  category: "AUTHENTICATION",
+  components: [
+    { type: :body, add_security_recommendation: true },
+    { type: :footer, code_expiration_minutes: 15 },
+    { type: :buttons, buttons: [
+      { type: :otp, otp_type: "ONE_TAP",
+        supported_apps: [{ package_name: "com.example.luckyshrub",
+                           signature_hash: "K8a/AINcGX7" }] },
+    ] },
+  ]
+)
+# components => [{ type: "BODY", add_security_recommendation: true },
+#                { type: "FOOTER", code_expiration_minutes: 15 },
+#                { type: "BUTTONS", buttons: [{ type: "OTP", otp_type: "ONE_TAP",
+#                  supported_apps: [{ package_name: "...", signature_hash: "..." }] }] }]
+```
+
+> **`text` and `autofill_text` are rejected** on an OTP button — Meta localises those
+> labels itself:
+>
+> ```ruby
+> { type: :otp, otp_type: "COPY_CODE", text: "Copy it" }
+> # => ActiveModel::ValidationError: Text cannot be set on an OTP button;
+> #    Meta localises the label
+> ```
+
+## Validation errors
+
+```ruby
+{ type: :otp, otp_type: "ONE_TAP" }
+# => ActiveModel::ValidationError: Supported apps can't be blank for the ONE_TAP OTP type
+
+{ type: :otp, otp_type: "ZERO_TAP", supported_apps: [...] }
+# => ActiveModel::ValidationError: Zero tap terms accepted must be accepted
+#    for the ZERO_TAP OTP type
+
+{ type: :footer, code_expiration_minutes: 120 }
+# => ActiveModel::ValidationError: Code expiration minutes must be in 1..90
+```
+
+Note that unlike other categories, `OTP` buttons are **not** capped per type — Meta
+publishes no limit, so the gem invents none.
+
+## Sending one
+
+Once approved, an authentication template is sent like any other — see
+[../messages/template.md](../messages/template.md). The code itself goes in the body
+parameter, and (for `COPY_CODE`/`ONE_TAP`) also as the button's `payload`.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/authentication-templates/authentication-templates>

data/docs/message_templates/carousel.md

@@ -0,0 +1,103 @@
+# Carousel Templates
+
+Two to ten swipeable cards under a shared body message — a product row, a set of
+listings, a group of offers.
+
+> **MARKETING only.** A carousel on a `UTILITY` or `AUTHENTICATION` template is
+> rejected locally:
+>
+> ```ruby
+> # => ActiveModel::ValidationError: Components CAROUSEL is only supported on
+> #    MARKETING templates, not UTILITY
+> ```
+
+```ruby
+card = {
+  header: { format: "IMAGE", header_handle: "4::aW..." },
+  body: { text: "Rare {{1}} in stock!", example: ["Tulips"] },
+  buttons: [{ type: :quick_reply, text: "More like this" }],
+}
+
+Whatsapp::MessageTemplates.new.create(
+  name: "summer_carousel", language: "en_US", category: "MARKETING",
+  components: [
+    { type: :body, text: "Summer is here, {{1}}!", example: ["Pablo"] },
+    { type: :carousel, cards: [card, card] },
+  ]
+)
+```
+
+The template still needs its own top-level `BODY` — the carousel sits *below* it.
+
+## Card structure
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `header` | yes | `format` must be `IMAGE` or `VIDEO` |
+| `body` | no | Same rules as a normal body |
+| `buttons` | no | **0–2** buttons per card |
+
+> **All cards must be structurally identical.** Same header format, same button types
+> in the same order, and body text on either every card or none. The gem computes a
+> signature per card and compares them:
+>
+> ```ruby
+> # => ActiveModel::ValidationError: Cards must all have an identical structure:
+> #    same header format, same button types, and body text on either every card or none
+> ```
+
+Meta says "up to 2" buttons and never states a minimum, so **zero buttons is valid**.
+
+## Serialized payload
+
+Each card serializes to a bare `{components: [...]}` — note there is **no
+`card_index`** here. That is send-side only:
+
+```ruby
+Whatsapp::MessageTemplates::Template.new(
+  name: "summer_carousel", language: "en_US", category: "marketing",
+  components: [
+    { type: :body, text: "Summer is here, {{1}}!", example: ["Pablo"] },
+    { type: :carousel, cards: [card, card] },
+  ]
+).serialize
+# => {
+#   name: "summer_carousel", language: "en_US", category: "MARKETING",
+#   parameter_format: "POSITIONAL",
+#   components: [
+#     { type: "BODY", text: "Summer is here, {{1}}!", example: { body_text: [["Pablo"]] } },
+#     { type: "CAROUSEL", cards: [
+#       { components: [
+#         { type: "HEADER", format: "IMAGE", example: { header_handle: ["4::aW..."] } },
+#         { type: "BODY", text: "Rare {{1}} in stock!", example: { body_text: [["Tulips"]] } },
+#         { type: "BUTTONS", buttons: [{ type: "QUICK_REPLY", text: "More like this" }] },
+#       ] },
+#       { components: [...] },
+#     ] },
+#   ]
+# }
+```
+
+## Media handles
+
+`header_handle` is **not** a media ID from [`Media#upload`](../media/README.md). It
+comes from Meta's Resumable Upload API, which this gem does not wrap — see
+[README.md § Not wrapped](README.md#not-wrapped).
+
+## Validation errors
+
+```ruby
+{ type: :carousel, cards: [card] }
+# => ActiveModel::ValidationError: Cards is too short (minimum is 2 characters)
+
+{ type: :carousel, cards: [card_with_image_header, card_with_video_header] }
+# => ActiveModel::ValidationError: Cards must all have an identical structure: ...
+
+{ header: { format: "TEXT", text: "Hi" }, body: ..., buttons: [...] }
+# => ActiveModel::ValidationError: Header format must be IMAGE or VIDEO
+#    for a carousel card, got TEXT
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/carousel-templates>

data/docs/message_templates/components.md

@@ -0,0 +1,179 @@
+# Components and Buttons Reference
+
+The complete registry of what a template can be built from. A component validates
+itself; `ComponentSet` validates how components relate to each other.
+
+## Component types
+
+Resolved through the frozen `Component::TYPES` registry — never `const_get` on caller
+input.
+
+| `type:` | Wire type | Purpose |
+| --- | --- | --- |
+| `:header` | `HEADER` | Text, media, or location above the body |
+| `:body` | `BODY` | **Required, exactly one** |
+| `:footer` | `FOOTER` | Small print below the body |
+| `:buttons` | `BUTTONS` | One component holding 1–10 buttons |
+| `:carousel` | `CAROUSEL` | [2–10 identical cards](carousel.md) |
+| `:limited_time_offer` | `LIMITED_TIME_OFFER` | [Countdown + coupon](limited_time_offer.md) |
+
+An unknown type raises before any request:
+
+```ruby
+# => Whatsapp::MessageTemplates::TemplateError: Unknown component type: :greeting.
+#    Known types: header, body, footer, buttons, carousel, limited_time_offer
+```
+
+### Header
+
+| `format` | Fields | Rules |
+| --- | --- | --- |
+| `TEXT` | `text`, `example` | ≤ **60** chars, **at most one** placeholder, no Markdown, no `header_handle` |
+| `IMAGE` `VIDEO` `DOCUMENT` `GIF` | `header_handle` | No `text` |
+| `LOCATION` | — | Nothing else; coordinates are supplied when sending |
+
+Max **one** header per template.
+
+The Markdown check rejects `*` `_` `~` `` ` `` in the literal text but **ignores
+placeholder contents** — named placeholders are lowercase-and-underscores by
+definition, so scanning raw text would reject `{{sale_start_date}}` for its underscore
+and make named parameters unusable in a text header.
+
+```ruby
+{ type: :header, format: "TEXT", text: "Order {{1}} confirmed", example: ["#1234"] }
+{ type: :header, format: "IMAGE", header_handle: "4::aW..." }
+{ type: :header, format: "LOCATION" }
+```
+
+A `LOCATION` header requires the category to be `UTILITY` or `MARKETING`.
+
+### Body
+
+**Required, exactly one per template.** Two mutually exclusive shapes:
+
+| Shape | Fields | Rules |
+| --- | --- | --- |
+| Text | `text`, `example` | ≤ **1024** chars, any number of placeholders, example count must match |
+| Authentication | `add_security_recommendation` | See [authentication.md](authentication.md) |
+
+```ruby
+{ type: :body, text: "Thank you, {{1}}!", example: ["Pablo"] }
+{ type: :body, add_security_recommendation: true }
+```
+
+Example count is checked against the **unique** placeholder count, so a repeated
+`{{1}}` needs one example, not two.
+
+### Footer
+
+Max **one**. Two mutually exclusive shapes:
+
+| Shape | Fields | Rules |
+| --- | --- | --- |
+| Text | `text` | ≤ **60** chars, **no placeholders at all** |
+| Authentication | `code_expiration_minutes` | Integer in **1..90** |
+
+```ruby
+{ type: :footer, text: "Thanks for shopping with us" }
+{ type: :footer, code_expiration_minutes: 15 }
+```
+
+Forbidden entirely alongside a [limited-time offer](limited_time_offer.md).
+
+### Buttons
+
+Max **one** `BUTTONS` component, holding **1–10** buttons.
+
+| Button type | Cap per template |
+| --- | --- |
+| `QUICK_REPLY` | 10 |
+| `URL` | 2 |
+| `PHONE_NUMBER` | 1 |
+| `COPY_CODE` | 1 |
+| `OTP` | uncapped — Meta publishes no limit |
+
+> **Quick replies must be contiguous.** They may sit at the start or the end, but not
+> with another type between them. `[QR, QR, URL]` and `[URL, QR, QR]` are fine;
+> `[QR, URL, QR]` raises `quick reply buttons must be grouped together, without other
+> types between them`.
+
+## Button types
+
+Resolved through the frozen `Button::TYPES` registry.
+
+| `type:` | Wire type | Fields |
+| --- | --- | --- |
+| `:quick_reply` | `QUICK_REPLY` | `text` ≤ **25** |
+| `:url` | `URL` | `text` ≤ 25, `url` ≤ **2000**, `example` |
+| `:phone_number` | `PHONE_NUMBER` | `text` ≤ 25, `phone_number` ≤ **20** |
+| `:copy_code` | `COPY_CODE` | `example` ≤ **20** (a bare String), **no `text`** |
+| `:otp` | `OTP` | `otp_type`, `supported_apps`, `zero_tap_terms_accepted` |
+
+```ruby
+{ type: :quick_reply,  text: "More like this" }
+{ type: :url,          text: "Track order", url: "https://example.com/o/{{1}}", example: "1234" }
+{ type: :phone_number, text: "Call", phone_number: "15550051310" }
+{ type: :copy_code,    example: "SPRING25" }
+{ type: :otp,          otp_type: "COPY_CODE" }
+```
+
+### The URL button's single trailing variable
+
+A URL button may contain **at most one variable, and it must be at the end**:
+
+```ruby
+{ type: :url, text: "Track", url: "https://example.com/{{1}}/details" }
+# => ActiveModel::ValidationError: Url variable must be at the end of the URL
+```
+
+> The URL variable is counted by **occurrence**, not by unique name, so
+> `.../{{1}}/details/{{1}}` is rejected: it ends in a placeholder and names one
+> parameter, but the leading one still sits mid-URL. Everywhere else — body examples
+> above all — the unique count is the correct one, since Meta treats a repeated
+> `{{1}}` as a single parameter needing a single example.
+
+Its `example` is a **flat array on the button**, unlike header and body examples,
+which are nested under an `example` key. A bare String is wrapped for you.
+
+### Buttons Meta supplies the label for
+
+`COPY_CODE` and `OTP` reject `text` (and `autofill_text`) — Meta writes and localises
+those labels:
+
+```ruby
+{ type: :copy_code, example: "SPRING25", text: "Copy" }
+# => ActiveModel::ValidationError: Text cannot be set on a copy-code button;
+#    Meta supplies the label
+```
+
+## Cross-component rules
+
+Owned by `ComponentSet`, because it is the only object that can see the siblings:
+
+- **Exactly one** `BODY`.
+- **At most one** each of `HEADER`, `FOOTER`, `BUTTONS`, `CAROUSEL`,
+  `LIMITED_TIME_OFFER`.
+- `CAROUSEL` or `LIMITED_TIME_OFFER` → category must be `MARKETING`.
+- A `LOCATION` header → category must be `UTILITY` or `MARKETING`.
+- `LIMITED_TIME_OFFER` present → `FOOTER` forbidden, `BODY` ≤ **600**, header
+  `IMAGE`/`VIDEO` only, copy-code `example` ≤ **15** and that button must be **first**.
+
+The category-dependent rules are **skipped when `category` is nil** — which is exactly
+what `#update` needs, since editing replaces components without re-supplying a
+category.
+
+## Not registered
+
+Only types with a published Meta field reference get a class. Named in Meta's Graph
+enum but deliberately absent:
+
+- **Components:** `GREETING`, `ALBUM`, `CALL_PERMISSION_REQUEST`,
+  `TAP_TARGET_CONFIGURATION`, `ATTACHMENT`.
+- **Buttons:** `FLOW`, `MPM`, `CATALOG`, `VOICE_CALL`, `VIDEO_CALL`, `POSTBACK`,
+  `BOOKING_STATUS`, `PAYMENT_REQUEST`, `REQUEST_CONTACT_INFO`. Most of these *are*
+  accepted by [`LibraryTemplate`](library.md), because Meta documents them by name in
+  that context.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/>

data/docs/message_templates/library.md

@@ -0,0 +1,98 @@
+# Library Templates
+
+Meta maintains a library of pre-written, pre-approved templates for common cases —
+delivery updates, appointment reminders, payment confirmations. Cloning one usually
+comes back **`APPROVED` immediately**, skipping the 24-hour review entirely.
+
+```ruby
+Whatsapp::MessageTemplates.new.create_from_library(
+  name: "my_delivery_update", language: "en_US", category: "UTILITY",
+  library_template_name: "delivery_update_1",
+  library_template_button_inputs: [
+    { type: "URL", url: { base_url: "https://example.com/{{1}}",
+                          url_suffix_example: "https://example.com/order_update" } },
+  ]
+)
+# => #<Response::Created id="1" status="APPROVED" category="UTILITY">
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `name` | yes | Your name for the clone. `/\A[a-z0-9_]+\z/`, max 512 |
+| `language` | yes | Validated against the supported list |
+| `category` | yes | `UTILITY` \| `MARKETING` \| `AUTHENTICATION` |
+| `library_template_name` | yes | Meta's name for the source template |
+| `library_template_body_inputs` | no | Body toggles — see below |
+| `library_template_button_inputs` | no | Button configuration — see below |
+
+> **No `components:` at all.** The wording is Meta's; you only supply the identity and
+> the few configurable inputs. That is the whole point of the library.
+
+## Body inputs
+
+| Field | Type |
+| --- | --- |
+| `add_contact_number` | Boolean |
+| `add_learn_more_link` | Boolean |
+| `add_security_recommendation` | Boolean |
+| `add_track_package_link` | Boolean |
+| `code_expiration_minutes` | Integer, **1–90** |
+
+```ruby
+library_template_body_inputs: {
+  add_contact_number: true,
+  add_track_package_link: true,
+}
+```
+
+## Button inputs
+
+`type` is one of `QUICK_REPLY` `URL` `PHONE_NUMBER` `OTP` `MPM` `CATALOG` `FLOW`
+`VOICE_CALL` `APP` — deliberately a **wider set** than the button types available to
+hand-built templates, because Meta documents these by name in the library context.
+
+| `type` | Required extra |
+| --- | --- |
+| `URL` | `url: { base_url:, url_suffix_example: }` |
+| `PHONE_NUMBER` | `phone_number:` |
+| `APP` | `supported_apps:` |
+| `OTP` | `otp_type:`, plus `zero_tap_terms_accepted:` for zero-tap |
+
+```ruby
+library_template_button_inputs: [
+  { type: "URL", url: { base_url: "https://example.com/{{1}}",
+                        url_suffix_example: "https://example.com/order_update" } },
+  { type: "PHONE_NUMBER", phone_number: "15550051310" },
+]
+```
+
+## Validation errors
+
+```ruby
+{ type: "URL", url: {} }
+# => ActiveModel::ValidationError: Url requires a base_url for a URL button input
+
+{ type: "PHONE_NUMBER" }
+# => ActiveModel::ValidationError: Phone number can't be blank for a PHONE_NUMBER button input
+
+{ type: "APP" }
+# => ActiveModel::ValidationError: Supported apps can't be blank for an APP button input
+```
+
+## Unverified detail
+
+`library_template_button_inputs` is emitted as a **real JSON array**. Meta's guide
+shows a JSON-*stringified* array while the Graph reference types it
+`array<JSON object>`. This has not been settled against a live WABA — if Meta rejects
+the array form, it is a one-line change in `LibraryTemplate#serialize`.
+
+## Not wrapped
+
+Browsing the library itself (`message_template_library`) is not wrapped — find the
+`library_template_name` you want in WhatsApp Manager or Meta's docs.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/template-library>