ruby-whatsapp 0.4.0 → 0.4.2

data/docs/message_templates/limited_time_offer.md

@@ -0,0 +1,94 @@
+# Limited-Time Offer Templates
+
+Adds a live countdown and a copyable coupon code to a marketing message. The countdown
+is rendered by WhatsApp itself, so the urgency stays accurate no matter when the
+recipient opens the thread.
+
+> **MARKETING only**, and the presence of a `LIMITED_TIME_OFFER` component tightens
+> four other rules at once. See [The knock-on rules](#the-knock-on-rules).
+
+```ruby
+Whatsapp::MessageTemplates.new.create(
+  name: "spring_offer", language: "en_US", category: "MARKETING",
+  components: [
+    { type: :header, format: "IMAGE", header_handle: "4::aW..." },
+    { type: :limited_time_offer, text: "Expiring offer!", has_expiration: true },
+    { type: :body, text: "Good news, {{1}}! Use code {{2}} for 25% off.",
+      example: ["Pablo", "SPRING25"] },
+    { type: :buttons, buttons: [
+      { type: :copy_code, example: "SPRING25" },
+      { type: :url, text: "Book now!", url: "https://example.com/o?c={{1}}", example: "n3mtql" },
+    ] },
+  ]
+)
+```
+
+## The component
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `text` | yes | Max **16** characters — the offer label |
+| `has_expiration` | no | `true` shows the countdown |
+
+It serializes nested, unlike every other component:
+
+```ruby
+{ type: "LIMITED_TIME_OFFER", limited_time_offer: { text: "Expiring offer!", has_expiration: true } }
+```
+
+## The knock-on rules
+
+Adding a limited-time offer changes what the rest of the template may contain. These
+are enforced by `ComponentSet`, which is the only object that can see all the
+components at once:
+
+| Rule | Error if violated |
+| --- | --- |
+| **No `FOOTER`** at all | `a FOOTER is not allowed in a LIMITED_TIME_OFFER template` |
+| `BODY` drops to **600** chars (from 1024) | `the BODY of a LIMITED_TIME_OFFER template is limited to 600 characters` |
+| Header must be **`IMAGE` or `VIDEO`** | `the header must be IMAGE or VIDEO in a LIMITED_TIME_OFFER template, got TEXT` |
+| Copy-code button must be **first** | `the copy-code button must be first in a LIMITED_TIME_OFFER template` |
+| Copy-code `example` ≤ **15** chars (from 20) | `the copy-code example is limited to 15 characters in a LIMITED_TIME_OFFER template` |
+
+## Serialized payload
+
+```ruby
+Whatsapp::MessageTemplates::Template.new(
+  name: "limited_time_offer_caribbean_pkg_2023", language: "en_US", category: "marketing",
+  components: [
+    { type: :header, format: "image", header_handle: "4::aW" },
+    { type: :limited_time_offer, text: "Expiring offer!", has_expiration: true },
+    { type: :body, text: "Good news, {{1}}! Use code {{2}} to get 25% off!",
+      example: ["Pablo", "CARIBE25"] },
+    { type: :buttons, buttons: [
+      { type: :copy_code, example: "CARIBE25" },
+      { type: :url, text: "Book now!", url: "https://x.test/offers?code={{1}}", example: "n3mtql" },
+    ] },
+  ]
+).serialize
+# => {
+#   name: "limited_time_offer_caribbean_pkg_2023", language: "en_US", category: "MARKETING",
+#   parameter_format: "POSITIONAL",
+#   components: [
+#     { type: "HEADER", format: "IMAGE", example: { header_handle: ["4::aW"] } },
+#     { type: "LIMITED_TIME_OFFER",
+#       limited_time_offer: { text: "Expiring offer!", has_expiration: true } },
+#     { type: "BODY", text: "Good news, {{1}}! Use code {{2}} to get 25% off!",
+#       example: { body_text: [["Pablo", "CARIBE25"]] } },
+#     { type: "BUTTONS", buttons: [
+#       { type: "COPY_CODE", example: "CARIBE25" },
+#       { type: "URL", text: "Book now!", url: "https://x.test/offers?code={{1}}",
+#         example: ["n3mtql"] }] },
+#   ]
+# }
+```
+
+## Media handles
+
+`header_handle` comes from Meta's Resumable Upload API, not
+[`Media#upload`](../media/README.md) — see
+[README.md § Not wrapped](README.md#not-wrapped).
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/limited-time-offer-templates>

data/docs/message_templates/responses.md

@@ -0,0 +1,173 @@
+# Template Responses
+
+Four endpoints, four response shapes — so four classes rather than one that is mostly
+`nil`.
+
+| Method | Returns |
+| --- | --- |
+| `create`, `create_from_library`, `upsert` | [`Response::Created`](#created) |
+| `find` | [`Response::Node`](#node) |
+| `list` | [`Response::Collection`](#collection) |
+| `update`, `delete` | plain `Boolean` |
+
+## Created
+
+`{id, status, category}` — what you get back from a submission.
+
+```ruby
+created = templates.create(name: "order_confirmation", language: "en_US",
+                           category: "UTILITY", components: [...])
+
+created.id        # => "1259544702043867"
+created.status    # => "PENDING"
+created.category  # => "UTILITY"
+
+created.pending?  # => true
+created.approved? # => false
+created.rejected? # => false
+```
+
+A [library template](library.md) usually comes back `APPROVED` immediately; everything
+else starts `PENDING` and is reviewed asynchronously.
+
+## Node
+
+The full template object, from `find`.
+
+```ruby
+template = templates.find(template_id: "564750795574598")
+```
+
+| Accessor | Example |
+| --- | --- |
+| `id` | `"564750795574598"` |
+| `name` | `"order_confirmation"` |
+| `status` | `"APPROVED"` |
+| `category` | `"UTILITY"` |
+| `language` | `"en_US"` |
+| `components` | **raw hashes** — see below |
+| `parameter_format` | `"POSITIONAL"` |
+| `sub_category` | `"ORDER_DETAILS"` |
+| `rejected_reason` | `"NONE"` |
+| `quality_score` | `#<QualityScore score="GREEN" date=1700000000 reasons=[]>` |
+| `previous_category` | `"MARKETING"` |
+| `correct_category` | `"UTILITY"` |
+| `message_send_ttl_seconds` | `3600` |
+| `cta_url_link_tracking_opted_out` | `false` |
+| `library_template_name` | `"delivery_update_1"` |
+
+Predicates: `#approved?`, `#rejected?`, `#paused?`, and `#editable?` (true for
+`APPROVED`, `REJECTED`, and `PAUSED`).
+
+```ruby
+template.status     # => "APPROVED"
+template.editable?  # => true
+```
+
+> **`#components` stays raw hashes on purpose.** It is not rebuilt into the
+> `Component` classes. Those validate a payload being *written*; this is Meta's echo of
+> one, carrying fields the write side does not model. Running write-side rules over
+> data we did not author would raise on perfectly valid responses. Read it as data;
+> build a new `Template` when you want to change something.
+
+```ruby
+template.components
+# => [{ "type" => "BODY", "text" => "Thank you, {{1}}!",
+#       "example" => { "body_text" => [["Pablo"]] } }]
+```
+
+## Collection
+
+`{data, paging, summary}` from `list`. It is `Enumerable`, so it behaves like the array
+of `Node`s it wraps.
+
+```ruby
+page = templates.list(status: %w[APPROVED], limit: 25)
+
+page.map(&:name)                    # => ["order_confirmation", ...]
+page.select(&:approved?)            # Enumerable
+page.next_cursor                    # => "AFTER" — nil on the last page
+page.remaining                      # => 249
+```
+
+| Accessor | Holds |
+| --- | --- |
+| `data` | `Array<Response::Node>` |
+| `paging` | `Response::Paging` — `before`, `after` (flattened from `paging.cursors`) |
+| `summary` | `Response::Summary` |
+
+`#next_cursor` is `paging&.after`; `#remaining` is `summary&.remaining`.
+
+### Summary
+
+| Accessor | Meaning |
+| --- | --- |
+| `total_count` | Templates matching the filter |
+| `message_template_count` | Templates on the account |
+| `message_template_limit` | The account's cap |
+| `are_translations_complete` | Boolean |
+| `remaining` | `limit - count`, or `nil` when either is missing |
+
+```ruby
+page.summary.message_template_count  # => 12
+page.summary.message_template_limit  # => 250
+page.remaining                       # => 238
+```
+
+### Paging
+
+Manual — there is no auto-pagination:
+
+```ruby
+page = templates.list(limit: 25)
+all  = page.to_a
+
+while (cursor = page.next_cursor)
+  page = templates.list(limit: 25, after: cursor)
+  all.concat(page.to_a)
+end
+```
+
+### QualityScore
+
+```ruby
+template.quality_score.score    # => "GREEN"  — GREEN | YELLOW | RED | UNKNOWN
+template.quality_score.date     # => 1_700_000_000
+template.quality_score.reasons  # => []
+```
+
+Best-effort schema on `reasons` — Meta publishes no sub-fields for it.
+
+## Booleans
+
+`update` and `delete` return a plain `true`/`false` derived from `{"success": true}`:
+
+```ruby
+templates.update(template_id: "564750795574598", category: "MARKETING")  # => true
+templates.delete(name: "order_confirmation")                             # => true
+```
+
+A non-2xx response raises `Whatsapp::MessageTemplates::TemplateError` instead of
+returning `false`, so `false` genuinely means "Meta said no", not "the request failed".
+
+## Statuses
+
+| Status | Meaning |
+| --- | --- |
+| `PENDING` | Under review |
+| `APPROVED` | Sendable |
+| `REJECTED` | Refused — see `rejected_reason` |
+| `PAUSED` | Temporarily halted for quality |
+| `DISABLED` | Permanently disabled; cannot be deleted |
+| `IN_APPEAL` | Rejection under appeal |
+| `PENDING_DELETION` | Deletion queued |
+| `DELETED` | Gone |
+| `LIMIT_EXCEEDED` | Account template cap hit |
+| `ARCHIVED` | Archived |
+
+`rejected_reason` is one of `NONE`, `ABUSIVE_CONTENT`, `INVALID_FORMAT`,
+`PROMOTIONAL`, `TAG_CONTENT_MISMATCH`, `SCAM`.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/docs/graph-api/reference/whats-app-business-hsm/>

data/docs/message_templates/standard.md

@@ -0,0 +1,138 @@
+# Standard Templates
+
+Utility and marketing templates built from text components — the ordinary case. An
+order confirmation, a shipping update, a password-reset notice.
+
+Every standard template needs **exactly one `BODY`**; everything else is optional.
+
+```ruby
+templates = Whatsapp::MessageTemplates.new
+
+created = templates.create(
+  name: "order_confirmation",           # lowercase alphanumerics and underscores only
+  language: "en_US",
+  category: "UTILITY",                  # UTILITY | MARKETING | AUTHENTICATION
+  components: [
+    { type: :header, format: "TEXT", text: "Order {{1}} confirmed", example: ["#1234"] },
+    { type: :body,
+      text: "Thank you, {{1}}! Your order number is {{2}}.",
+      example: ["Pablo", "860198-230332"] },
+    { type: :footer, text: "Thanks for shopping with us" },
+    { type: :buttons, buttons: [
+      { type: :phone_number, text: "Call", phone_number: "15550051310" },
+      { type: :url, text: "Track order", url: "https://example.com/orders/{{1}}", example: "1234" },
+    ] },
+  ]
+)
+
+created.id       # => "1259544702043867"
+created.status   # => "PENDING" — Meta reviews asynchronously, up to 24 hours
+created.pending? # => true
+```
+
+## Placeholders and examples
+
+A placeholder is `{{1}}` (positional) or `{{first_name}}` (named). Meta requires a
+sample value for every one of them, so a human reviewer can see what the template
+actually says. The gem checks the count matches **before** the request:
+
+```ruby
+templates.create(
+  name: "x", language: "en_US", category: "UTILITY",
+  components: [{ type: :body, text: "Hi {{1}} and {{2}}", example: ["Pablo"] }]
+)
+# => ActiveModel::ValidationError: Example does not match the body text:
+#    2 placeholders but 1 example
+```
+
+Positional placeholders must **start at `{{1}}` and increment without gaps**, and you
+cannot mix the two styles in one template.
+
+> **Ruby gotcha.** Meta's own examples include text like `Your order #{{2}}`. In a
+> double-quoted Ruby string, `#{` starts interpolation — use single quotes or escape
+> it:
+>
+> ```ruby
+> text: 'Your order #{{2}} has shipped'   # single quotes
+> text: "Your order \#{{2}} has shipped"  # or escape
+> ```
+
+### Named parameters
+
+Named parameters read better than positional ones for anything non-trivial. Set
+`parameter_format: "NAMED"` and pass a Hash of name ⇒ example:
+
+```ruby
+templates.create(
+  name: "order_confirmation", language: "en_US", category: "UTILITY",
+  parameter_format: "NAMED",
+  components: [
+    { type: :body,
+      text: "Thank you, {{first_name}}! Your order number is {{order_number}}.",
+      example: { first_name: "Pablo", order_number: "860198-230332" } },
+  ]
+)
+```
+
+### The `example` key trap
+
+The `example` key **name** changes with both the component and the format. This is the
+single most rejection-prone detail in the API, so the gem builds it for you — you pass
+the values, it picks the key:
+
+| Role | `POSITIONAL` | `NAMED` |
+| --- | --- | --- |
+| header | `header_text: ["Sale"]` (flat) | `header_text_named_params: [{param_name:, example:}]` |
+| body | `body_text: [["a","b"]]` (**nested**) | `body_text_named_params: [{param_name:, example:}]` |
+
+Pass whichever input shape suits you — an `Array` (positional), a `Hash` of
+name ⇒ example (named), Meta's own `[{param_name:, example:}]`, or a fully-built
+payload hash copied straight out of the docs.
+
+## Serialized payload
+
+```ruby
+Whatsapp::MessageTemplates::Template.new(
+  name: "order_confirmation", language: "en_US", category: "utility",
+  components: [
+    { type: :header, format: "DOCUMENT", header_handle: "4::YX" },
+    { type: :body,
+      text: "Thank you for your order, {{1}}! Your order number is {{2}}.",
+      example: ["Pablo", "860198-230332"] },
+    { type: :buttons, buttons: [
+      { type: :phone_number, text: "Call", phone_number: "15550051310" },
+      { type: :url, text: "Contact Support", url: "https://www.luckyshrub.com/support" },
+    ] },
+  ]
+).serialize
+# => {
+#   name: "order_confirmation", language: "en_US", category: "UTILITY",
+#   parameter_format: "POSITIONAL",
+#   components: [
+#     { type: "HEADER", format: "DOCUMENT", example: { header_handle: ["4::YX"] } },
+#     { type: "BODY", text: "Thank you for your order, {{1}}! Your order number is {{2}}.",
+#       example: { body_text: [["Pablo", "860198-230332"]] } },
+#     { type: "BUTTONS", buttons: [
+#       { type: "PHONE_NUMBER", text: "Call", phone_number: "15550051310" },
+#       { type: "URL", text: "Contact Support", url: "https://www.luckyshrub.com/support" }] },
+#   ]
+# }
+```
+
+Note the lowercase `category: "utility"` on input and `"UTILITY"` on the wire — every
+enum accepts either casing and emits uppercase.
+
+## Rules worth remembering
+
+| Component | Limit |
+| --- | --- |
+| `header` (TEXT) | ≤ **60** chars, **at most one** placeholder, no Markdown (`*` `_` `~` `` ` ``) |
+| `body` | ≤ **1024** chars, any number of placeholders, matching example required |
+| `footer` | ≤ **60** chars and **no placeholders** |
+| `buttons` | 1–**10** buttons; quick-replies must be **contiguous** |
+
+Full reference in [components.md](components.md).
+
+---
+
+**Meta docs:** <https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/components/>

data/docs/messages/README.md

@@ -0,0 +1,135 @@
+# Sending Messages
+
+Everything in this directory builds an *outbound* payload for
+`POST /{PHONE_ID}/messages`. Each WhatsApp message kind is its own
+`ActiveModel`-validated Ruby class, so a payload Meta would reject comes back as a
+local `ActiveModel::ValidationError` instead of a round trip and an opaque
+`#131009`.
+
+Addresses **`phone_id`**, not `waba_id`, and needs the
+`whatsapp_business_messaging` permission.
+
+## The two ways to send
+
+Every kind registered in `Whatsapp::Messages::KINDS` gets a generated
+`Whatsapp::Messages.send_<kind>!` class method — pass the recipient and the
+kind-specific fields as keyword arguments:
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hello!")
+# => #<Whatsapp::Messages::Response messaging_product="whatsapp" ...>
+```
+
+If the kind is only known at runtime, drop down to the factory those methods are
+built on:
+
+```ruby
+Whatsapp::Messages.new(
+  kind: :text,                                    # or a variable; String or Symbol
+  payload: { to: "+15551234567", body: "Hello!" },
+  client: Whatsapp::Client.new                    # optional
+).send!
+```
+
+Both forms accept an optional `client:` (defaults to a new `Whatsapp::Client`
+built from `Whatsapp.configuration`) and return a
+[`Whatsapp::Messages::Response`](#the-response).
+
+## The kinds
+
+| Kind | Method | Sends |
+| --- | --- | --- |
+| `:text` | [`send_text!`](text.md) | Plain text with an optional link preview |
+| `:image` | [`send_image!`](image.md) | An image with an optional caption |
+| `:video` | [`send_video!`](video.md) | A video with an optional caption |
+| `:audio` | [`send_audio!`](audio.md) | A voice note or audio clip |
+| `:document` | [`send_document!`](document.md) | A file with an optional caption and filename |
+| `:sticker` | [`send_sticker!`](sticker.md) | A sticker |
+| `:contacts` | [`send_contacts!`](contacts.md) | A rich, vCard-like contact card |
+| `:reaction` | [`send_reaction!`](reaction.md) | An emoji reaction to a previous message |
+| `:location` | [`send_location!`](location.md) | A latitude/longitude pin |
+| `:address` | [`send_address!`](address.md) | A delivery-address form (India & Singapore only) |
+| `:location_request` | [`send_location_request!`](location_request.md) | A prompt asking the user to share their location |
+| `:template` | [`send_template!`](template.md) | A pre-approved marketing/utility/authentication template |
+| `:interactive` | [`send_interactive!`](interactive.md) | Reply buttons, lists, CTA URLs, or carousels |
+
+Plus one endpoint that isn't a message kind at all:
+
+| | Method | Does |
+| --- | --- | --- |
+| — | [`mark_message_as_read!`](mark_message_as_read.md) | Closes the read-receipt loop on an inbound message |
+
+## The shared envelope
+
+Every kind except `mark_message_as_read` inherits `Messages::Base`, which supplies
+`to` (the only universally required field, validated for presence) and wraps the
+kind-specific hash in a common envelope:
+
+```ruby
+{
+  messaging_product: "whatsapp",
+  recipient_type: "individual",
+  to: "+15551234567",
+  type: "<kind>",
+  "<kind>": { ... }        # the kind-specific payload
+}
+```
+
+Three kinds break the `type == kind` symmetry because Meta transports them as
+interactive messages: [`address`](address.md), [`location_request`](location_request.md),
+and of course [`interactive`](interactive.md) all serialize with `type: "interactive"`.
+
+## The response
+
+A successful `send!` returns a `Whatsapp::Messages::Response`, deserialized from a
+body shaped like:
+
+```json
+{
+  "messaging_product": "whatsapp",
+  "contacts": [{ "input": "+15551234567", "wa_id": "15551234567" }],
+  "messages": [{ "id": "wamid.HBgLMTU1NTU1NTU1NTUV..." }]
+}
+```
+
+```ruby
+response = Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi")
+
+response.messaging_product     # => "whatsapp"
+response.messages.first.id     # => "wamid.HBgLMTU1NTU1NTU1NTUV..."
+response.contacts.first.input  # => "+15551234567"
+response.contacts.first.wa_id  # => "15551234567"
+response.success               # => nil for a normal send
+```
+
+`#success` is `nil` for a normal message send and `true`/`false` only for the
+status-update endpoints that reply `{"success": true}` — today just
+[`mark_message_as_read!`](mark_message_as_read.md).
+
+## Errors
+
+| Raised | When |
+| --- | --- |
+| `ArgumentError` | `to:` (or another required keyword) is missing |
+| `ActiveModel::ValidationError` | A field fails a local validation |
+| `Whatsapp::Messages::PayloadError` | `kind:` is unrecognized — only reachable through the `Messages.new(kind:, payload:)` form |
+| `Whatsapp::RequestError` | The API answered with a non-2xx status |
+
+Because every kind runs `validate!` at the end of its own `initialize`, an invalid
+field raises at *construction* time, before a client is ever touched:
+
+```ruby
+Whatsapp::Messages.send_image!(to: "+15551234567")
+# => ActiveModel::ValidationError: Either id or link must be present
+
+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
+```
+
+See [../errors.md](../errors.md) for the full hierarchy.
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/text-messages>

data/docs/messages/address.md

@@ -0,0 +1,86 @@
+# Address Messages
+
+Collects or confirms a structured delivery address through a native WhatsApp form,
+instead of parsing a free-text reply.
+
+> **India and Singapore only.** This is a Meta feature-availability restriction on the
+> WhatsApp Business Account itself, not merely a payload field. A WABA outside those
+> two markets gets `(#131009) Unsupported Interactive Message type` — that is expected,
+> not a bug in this class.
+
+```ruby
+Whatsapp::Messages.send_address!(
+  to: "+15551234567",
+  body: "Please share your delivery address",
+  country: "IN"
+)
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `body` | yes | The prompt shown above the form |
+| `country` | yes | `"IN"` or `"SG"` only |
+| `footer` | no | Small print under the form |
+| `values` | no | Hash pre-filling form fields |
+| `saved_addresses` | no | Array of previously saved addresses to offer. Defaults to `[]` |
+
+`values` pre-fills the form so the customer edits rather than types. `saved_addresses`
+offers a pick list of addresses you already hold for them:
+
+```ruby
+Whatsapp::Messages.send_address!(
+  to: "+15551234567",
+  body: "Please share your delivery address",
+  country: "IN",
+  footer: "Thanks for shopping with us",
+  values: { name: "Jane Doe", phone_number: "+15550001111", city: "Bangalore" },
+  saved_addresses: [
+    { id: "addr_1", name: "Jane Doe", pin_code: "560001",
+      address: "12 MG Road", city: "Bangalore", state: "KA" },
+  ]
+)
+```
+
+## Serialized payload
+
+Like [Location Request](location_request.md), this travels as an interactive message:
+
+```ruby
+Whatsapp::Messages::Address.new(
+  to: "+15551234567",
+  body: "Please share your delivery address",
+  country: "IN",
+  footer: "Thanks for shopping with us",
+  values: { name: "Jane Doe", city: "Bangalore" }
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567",
+#   type: "interactive",
+#   interactive: {
+#     type: "address_message",
+#     body: { text: "Please share your delivery address" },
+#     action: {
+#       name: "address_message",
+#       parameters: { country: "IN", values: { name: "Jane Doe", city: "Bangalore" } }
+#     },
+#     footer: { text: "Thanks for shopping with us" }
+#   }
+# }
+```
+
+`values` is included only when given; `saved_addresses` only when non-empty; `footer`
+only when truthy.
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_address!(to: "+15551234567", body: "Address?", country: "US")
+# => ActiveModel::ValidationError: Country is not included in the list
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/address-messages>

data/docs/messages/audio.md

@@ -0,0 +1,43 @@
+# Audio Messages
+
+Sends a voice note or audio clip.
+
+```ruby
+Whatsapp::Messages.send_audio!(to: "+15551234567", link: "https://example.com/clip.mp3")
+```
+
+## 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.**
+
+> **No caption.** Unlike [image](image.md), [video](video.md), and
+> [document](document.md), the Cloud API has no caption field for audio, so the class
+> does not accept one. Send a separate [text message](text.md) if you need
+> accompanying copy.
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Audio.new(to: "+15551234567", link: "https://example.com/clip.mp3").serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "audio",
+#   audio: { link: "https://example.com/clip.mp3" }
+# }
+```
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_audio!(to: "+15551234567")
+# => ActiveModel::ValidationError: Either id or link must be present
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/audio-messages>