ruby-whatsapp 0.4.0 → 0.6.1

data/docs/errors.md

@@ -0,0 +1,219 @@
+# Errors
+
+Every exception this gem raises descends from `Whatsapp::Error`, so one rescue catches
+the lot:
+
+```ruby
+begin
+  Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi")
+rescue Whatsapp::Error => e
+  Rails.logger.error("WhatsApp call failed: #{e.message}")
+end
+```
+
+## The hierarchy
+
+```
+StandardError
+└── Whatsapp::Error
+    ├── Whatsapp::RequestError                              a message send failed
+    ├── Whatsapp::Messages::PayloadError                    unknown message kind
+    ├── Whatsapp::Messages::Interactive::Header::HeaderError  malformed interactive header
+    ├── Whatsapp::Media::MediaError                         any Media failure
+    ├── Whatsapp::MessageTemplates::TemplateError           any template-management failure
+    ├── Whatsapp::SubscribedApp::Error                      any subscribed-apps failure
+    ├── Whatsapp::Schedule::Error                           any campaign-schedule failure
+    └── Whatsapp::BusinessPhoneNumber::Error                any phone-number-onboarding or account failure
+```
+
+Each module raises **its own** error class rather than the generic
+`Whatsapp::RequestError`, so you can rescue narrowly:
+
+```ruby
+rescue Whatsapp::MessageTemplates::TemplateError => e
+  # a template problem specifically — retry, or surface to the operator
+end
+```
+
+> **`Whatsapp::Webhook::Error` is not an exception.** Despite the name, it is a value
+> object modelling Meta's error payloads on `Status#errors` and
+> `Message::Unknown#errors`. See
+> [webhooks/messages.md](webhooks/messages.md#errors).
+
+## Validation errors are different
+
+Local validation failures raise **`ActiveModel::ValidationError`**, not a gem class.
+That is deliberate: a validation failure means *you* built something wrong, before any
+network call happened, and ActiveModel's error object carries the per-attribute
+detail.
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "x" * 5000)
+# => ActiveModel::ValidationError: Validation failed:
+#    Body is too long (maximum is 4096 characters)
+```
+
+Reach the structured detail through the exception's model:
+
+```ruby
+begin
+  Whatsapp::Messages.send_image!(to: "+15551234567", caption: "x" * 2000)
+rescue ActiveModel::ValidationError => e
+  e.model.errors.full_messages
+  # => ["Either id or link must be present", "Caption is too long (maximum is 1024 characters)"]
+  e.model.errors[:caption]
+  # => ["is too long (maximum is 1024 characters)"]
+end
+```
+
+Because every class runs `validate!` at the end of `initialize`, this raises at
+**construction** time — the client is never touched.
+
+Rescuing both kinds:
+
+```ruby
+begin
+  Whatsapp::Messages.send_template!(to:, name:, language: { code: })
+rescue ActiveModel::ValidationError => e
+  # our payload is wrong — a bug, or bad user input
+rescue Whatsapp::Error => e
+  # Meta said no, or the network did
+end
+```
+
+## Missing keywords
+
+A required Ruby keyword that isn't supplied raises `ArgumentError`, not a validation
+error — it never reaches the validator:
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567")
+# => ArgumentError: missing keyword: :body
+```
+
+The recipient is the exception. Since a message can be addressed by phone number
+(`to:`) *or* by [BSUID](messages/README.md#addressing-to-recipient-or-both)
+(`recipient:`), neither keyword is individually required, so omitting both is a
+validation failure rather than an arity one:
+
+```ruby
+Whatsapp::Messages.send_text!(body: "Hi")
+# => ActiveModel::ValidationError: at least one of to or recipient must be provided
+```
+
+## API failures
+
+Any non-2xx response raises the owning module's error class with a consistent message
+shape:
+
+```
+Failed to <action>: <status> - <body>
+```
+
+```ruby
+# => Whatsapp::RequestError: Failed to send message: 400 Bad Request -
+#    {"error":{"message":"(#131009) Parameter value is not valid","code":131009}}
+
+# => Whatsapp::Media::MediaError: Failed to upload media: 401 Unauthorized - {...}
+
+# => Whatsapp::MessageTemplates::TemplateError: Failed to create template:
+#    400 Bad Request - {"error":{"message":"Invalid parameter","code":100}}
+```
+
+The response body is truncated at **500** characters, with `… (truncated)` appended —
+Meta's error bodies can be long, and a full one in an exception message tends to end up
+somewhere it shouldn't.
+
+Actions used in these messages: `send message`, `mark message as read`,
+`upload media`, `get media URL`, `download media`, `delete media`,
+`list subscribed apps`, `subscribe app`, `unsubscribe app`,
+`request verification code`, `verify code`, `register business phone number`,
+`deregister business phone number`, plus the template CRUD verbs.
+
+## Missing configuration
+
+The `waba_id` and `phone_id` modules check for their ID **before** building a request,
+and say exactly how to supply it:
+
+```ruby
+Whatsapp::MessageTemplates.new.list
+# => Whatsapp::MessageTemplates::TemplateError: waba_id is required for template
+#    management; set it via Whatsapp.configure or Client.new(waba_id:)
+
+Whatsapp::SubscribedApp::List.call
+# => Whatsapp::SubscribedApp::Error: waba_id is required for subscribed apps;
+#    set it via Whatsapp.configure or Client.new(waba_id:)
+
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")
+# => Whatsapp::BusinessPhoneNumber::Error: phone_id is required for the register edge;
+#    set it via Whatsapp.configure or Client.new(phone_id:)
+
+Whatsapp::BusinessPhoneNumber::Account::Get.call
+# => Whatsapp::BusinessPhoneNumber::Error: waba_id is required for business account
+#    details; set it via Whatsapp.configure or Client.new(waba_id:)
+```
+
+Note the last two: `BusinessPhoneNumber` spans both IDs. Its onboarding actions need
+`phone_id`; its [`Account`](business_phone_number/account.md) actions need `waba_id`.
+
+See [configuration.md](configuration.md#which-id-addresses-what).
+
+## Argument errors from a module
+
+Some misuse is caught before validation and raises the module's own error rather than
+`ActiveModel::ValidationError` — these are wrong *calls*, not wrong *data*:
+
+```ruby
+templates.upsert(name: "x", language: "en_US", ...)
+# => TemplateError: #upsert requires `languages:` (an array of locale codes);
+#    use #create for a single one
+
+templates.update(template_id: "123")
+# => TemplateError: nothing to update: pass category, components or message_send_ttl_seconds
+
+templates.delete(hsm_ids: %w[1 2], name: "x")
+# => TemplateError: hsm_ids cannot be combined with name or hsm_id
+
+Whatsapp::Messages.new(kind: :telepathy, payload: { to: "+1" })
+# => Whatsapp::Messages::PayloadError: Unknown message kind: :telepathy.
+#    Known kinds: text, image, audio, video, document, sticker, contacts, reaction,
+#    location, address, location_request, template, interactive
+```
+
+## Interactive header errors
+
+`Interactive::Header` raises `HeaderError` rather than adding a validation error,
+because a header missing its content cannot be serialized at all:
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567", type: :reply_buttons, body: "Pick one",
+  header: { type: "image" },
+  action: { buttons: [{ id: "a", title: "A" }] }
+)
+# => Whatsapp::Messages::Interactive::Header::HeaderError:
+#    Image link is required for image header
+```
+
+## Retrying
+
+Meta's transient failures are ordinary HTTP: 429 for rate limiting, 5xx for outages.
+The gem does not retry — that policy belongs to your job queue:
+
+```ruby
+class SendWhatsappJob < ApplicationJob
+  retry_on Whatsapp::RequestError, wait: :polynomially_longer, attempts: 5
+  discard_on ActiveModel::ValidationError   # our payload is wrong; retrying won't fix it
+
+  def perform(to:, body:)
+    Whatsapp::Messages.send_text!(to:, body:)
+  end
+end
+```
+
+Discarding on `ActiveModel::ValidationError` is the important half: a locally invalid
+payload will fail identically on every attempt.
+
+> **Rate limits worth knowing.** Template edits are capped at 10 per 30 days and 1 per
+> 24 hours; `Register`/`Deregister` at 10 per number per 72-hour window (error
+> `133016`). None is observable client-side — they arrive as API errors.

data/docs/media/README.md

@@ -0,0 +1,161 @@
+# Media
+
+Upload, locate, download, and delete media assets on the Cloud API. An uploaded asset
+gets a **media ID** you can pass to [image](../messages/image.md),
+[video](../messages/video.md), [audio](../messages/audio.md),
+[document](../messages/document.md), and [sticker](../messages/sticker.md) messages
+instead of a public URL.
+
+Addresses your **phone number** (`phone_id`), like
+[messages](../messages/README.md).
+
+```ruby
+media = Whatsapp::Media.new    # or .new(client: my_client)
+
+media_id = media.upload(file_path: "photo.jpg", type: "image/jpeg")
+info     = media.get_url(media_id: media_id)
+media.download(url: info["url"], save_to: "photo.jpg")
+media.delete(media_id: media_id)
+```
+
+| Method | Request | Returns |
+| --- | --- | --- |
+| `upload(file_path:, type:)` | `POST /{phone_id}/media` (multipart) | `String` media ID |
+| `get_url(media_id:)` | `GET /{media_id}?phone_number_id=` | `Hash` |
+| `download(url:, save_to:)` | `GET <url>` with the bearer token | `String` — the path written |
+| `delete(media_id:)` | `DELETE /{media_id}?phone_number_id=` | `Boolean` |
+
+## Uploading
+
+```ruby
+media_id = Whatsapp::Media.new.upload(file_path: "photo.jpg", type: "image/jpeg")
+# => "1234567890123456"
+```
+
+The file must exist — checked **before** the request, so a typo costs nothing:
+
+```ruby
+Whatsapp::Media.new.upload(file_path: "nope.jpg", type: "image/jpeg")
+# => Whatsapp::Media::MediaError: File not found: nope.jpg
+```
+
+### Why prefer an ID over a link
+
+Sending by `link:` makes Meta re-download the file on **every send**. Uploading once
+and reusing the ID is faster, cheaper, and avoids your CDN being hammered:
+
+```ruby
+media_id = media.upload(file_path: "catalogue.pdf", type: "application/pdf")
+
+recipients.each do |to|
+  Whatsapp::Messages.send_document!(to: to, id: media_id, filename: "catalogue.pdf")
+end
+```
+
+> **Not for template headers.** A media header on a *template* takes a
+> `header_handle` from Meta's Resumable Upload API, which this gem does not wrap.
+> These media IDs are for **sending**, not template creation — see
+> [../message_templates/README.md](../message_templates/README.md#not-wrapped).
+
+## Getting a download URL
+
+```ruby
+info = Whatsapp::Media.new.get_url(media_id: "1234567890123456")
+# => { "url" => "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=...",
+#      "mime_type" => "image/jpeg", "sha256" => "...", "file_size" => 12345,
+#      "id" => "1234567890123456" }
+```
+
+The URL is short-lived and requires the bearer token — you cannot hand it to a browser.
+Fetch it with `#download`.
+
+This is the step after receiving an inbound media message:
+
+```ruby
+message.media_id      # from a webhook Message::Image / Video / Audio / Document / Sticker
+info = media.get_url(media_id: message.media_id)
+```
+
+## Downloading
+
+```ruby
+Whatsapp::Media.new.download(url: info["url"], save_to: "photo.jpg")
+# => "photo.jpg"
+```
+
+The response body is streamed to disk chunk by chunk rather than buffered, so a large
+video doesn't have to fit in memory.
+
+### The token never leaves the allowlist
+
+`#download` attaches your API token to the request, which makes the destination URL
+security-relevant. Two guards run before anything is sent:
+
+1. **HTTPS only.** A plain-HTTP URL is refused outright.
+2. **Allowlisted hosts only.** The host must be on
+   `Configuration#media_host_allowlist`, which defaults to
+   `lookaside.fbsbx.com`, `mmg.whatsapp.net`, and `graph.facebook.com`.
+
+```ruby
+media.download(url: "http://lookaside.fbsbx.com/x", save_to: "f")
+# => Whatsapp::Media::MediaError: Refusing to download from non-HTTPS URL: http://...
+
+media.download(url: "https://evil.example.com/x", save_to: "f")
+# => Whatsapp::Media::MediaError: Refusing to send credentials to non-allowlisted host:
+#    evil.example.com
+```
+
+Matching is exact host or a dotted subdomain, so `evil-fbsbx.com` and
+`fbsbx.com.attacker.com` are both rejected — a substring check would have let both
+through.
+
+Override the list if Meta serves you from a different host:
+
+```ruby
+Whatsapp.configure do |config|
+  config.media_host_allowlist = %w[lookaside.fbsbx.com mmg.whatsapp.net my-proxy.internal]
+end
+```
+
+## Deleting
+
+```ruby
+Whatsapp::Media.new.delete(media_id: "1234567890123456")   # => true
+```
+
+Returns a strict boolean from Meta's `{"success": true}`. A non-2xx response raises
+instead of returning `false`, so `false` genuinely means Meta declined.
+
+## Errors
+
+Every failure raises `Whatsapp::Media::MediaError`:
+
+| Message | Cause |
+| --- | --- |
+| `File not found: <path>` | `upload` — checked locally before any request |
+| `Invalid media URL: <detail>` | `download` — the URL didn't parse |
+| `Refusing to download from non-HTTPS URL: <url>` | `download` — HTTP scheme |
+| `Refusing to send credentials to non-allowlisted host: <host>` | `download` — host not on the allowlist |
+| `Failed to upload media: 400 ...` | Non-2xx from the API |
+| `Failed to get media URL: ...` / `Failed to download media: ...` / `Failed to delete media: ...` | Non-2xx from the API |
+
+Error bodies are truncated at 500 characters. See [../errors.md](../errors.md).
+
+## Round trip: receive, download, reply
+
+```ruby
+media = Whatsapp::Media.new
+
+change.value.messages.each do |message|
+  next unless message.respond_to?(:media_id)
+
+  info = media.get_url(media_id: message.media_id)
+  path = media.download(url: info["url"], save_to: Rails.root.join("tmp", message.id))
+
+  Whatsapp::Messages.send_text!(to: message.from, body: "Got your #{message.mime_type}, thanks!")
+end
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/business-phone-numbers/media>

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`. 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>