ruby-whatsapp 0.4.0 → 0.6.1

data/docs/messages/image.md

@@ -0,0 +1,59 @@
+# Image Messages
+
+Shares a photo or graphic — a product shot, a receipt, a screenshot.
+
+```ruby
+Whatsapp::Messages.send_image!(
+  to: "+15551234567",
+  link: "https://example.com/photo.jpg",
+  caption: "Our new product"
+)
+```
+
+## 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** — never both are mandatory, but at least one
+must be present. Prefer `id` when you'll send the same asset more than once: Meta
+caches an uploaded asset, whereas a `link` is re-fetched on every send.
+
+```ruby
+media    = Whatsapp::Media.new
+media_id = media.upload(file_path: "photo.jpg", type: "image/jpeg")
+
+Whatsapp::Messages.send_image!(to: "+15551234567", id: media_id, caption: "Our new product")
+```
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Image.new(
+  to: "+15551234567", link: "https://example.com/photo.jpg", caption: "Our new product"
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "image",
+#   image: { link: "https://example.com/photo.jpg", caption: "Our new product" }
+# }
+```
+
+The `image` hash is compacted, so absent optional keys never reach the wire.
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_image!(to: "+15551234567")
+# => ActiveModel::ValidationError: Either id or link must be present
+
+Whatsapp::Messages.send_image!(to: "+15551234567", link: "https://example.com/p.jpg", caption: "x" * 1025)
+# => ActiveModel::ValidationError: Caption is too long (maximum is 1024 characters)
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/image-messages>

data/docs/messages/interactive.md

@@ -0,0 +1,342 @@
+# Interactive Messages
+
+Gives the user tappable UI — buttons, a list, a carousel — instead of asking them to
+type a free-text reply. Tapping "Confirm" is one action; typing "yes", "Yes", "yeah",
+or "ya" is four things you have to parse.
+
+Unlike every other kind, `Interactive` is a **single class** that dispatches on
+`type:` through a frozen registry:
+
+| `type:` | Wire `interactive.type` | Shape |
+| --- | --- | --- |
+| `:reply_buttons` | `"button"` | [Up to 3 quick-reply buttons](#reply-buttons) |
+| `:list_buttons` | `"list"` | [A button expanding into sections of rows](#list) |
+| `:url_button` | `"cta_url"` | [A link rendered as a button](#cta-url-button) |
+| `:media_carousel` | `"carousel"` | [2–10 swipeable media cards](#media-carousel) |
+| `:product_carousel` | `"product_list"` | [2–10 catalog product cards](#product-carousel) |
+| `:request_contact_info` | `"request_contact_info"` | [A one-tap "share my number" button](#request-contact-info) |
+
+## Shared fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `type` | yes | One of the six keys above (Symbol or String) |
+| `body` | yes | Body text, max **1024** characters |
+| `action` | usually | Shape depends on `type` — see each section. Omit it only for `:request_contact_info`, the one kind with nothing to supply |
+| `header` | no | `{ type: "text"\|"image"\|"video"\|"document", ... }` |
+| `footer` | no | `{ text: "..." }`, max **60** characters |
+
+### Header
+
+A text header is capped at **60** characters. Media headers take a **`link:` only** —
+there is no media-`id` path on interactive headers, unlike [image](image.md) and
+friends:
+
+```ruby
+header: { type: "text",  text: "Order #1234" }
+header: { type: "image", link: "https://example.com/photo.jpg" }
+header: { type: "video", link: "https://example.com/clip.mp4" }
+header: { type: "document", link: "https://example.com/invoice.pdf" }
+```
+
+A header missing its content raises `Whatsapp::Messages::Interactive::Header::HeaderError`
+(not a validation error):
+
+```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
+```
+
+---
+
+## Reply buttons
+
+Up to **3** quick-reply buttons. The user's tap comes back as a webhook
+`Message::Interactive` with `interactive_type == "button_reply"`.
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567",
+  type: :reply_buttons,
+  body: "Would you like to confirm your order?",
+  action: { buttons: [{ id: "confirm", title: "Confirm" },
+                      { id: "cancel",  title: "Cancel" }] }
+)
+```
+
+| Field | Rules |
+| --- | --- |
+| `buttons` | 1–**3** entries |
+| `buttons[].id` | Required, max **256** characters — echoed back on tap |
+| `buttons[].title` | Required, max **20** characters — the visible label |
+
+```ruby
+Whatsapp::Messages::Interactive.new(
+  to: "+15551234567", type: :reply_buttons, body: "Would you like to confirm your order?",
+  action: { buttons: [{ id: "confirm", title: "Confirm" }, { id: "cancel", title: "Cancel" }] }
+).serialize
+# => { messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567",
+#      type: "interactive",
+#      interactive: { type: "button",
+#        body: { text: "Would you like to confirm your order?" },
+#        action: { buttons: [{ type: "reply", reply: { id: "confirm", title: "Confirm" } },
+#                            { type: "reply", reply: { id: "cancel",  title: "Cancel" } }] } } }
+```
+
+---
+
+## List
+
+One button that expands into up to **10 sections** of up to **10 rows** each. Use it
+when three buttons aren't enough — a menu, a time-slot picker, a product list.
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567",
+  type: :list_buttons,
+  body: "Choose a drink",
+  action: {
+    button: "Menu",
+    sections: [
+      { title: "Coffee", rows: [
+        { id: "espresso", title: "Espresso", description: "Strong & short" },
+        { id: "latte",    title: "Latte",    description: "Milky & mild" },
+      ] },
+    ],
+  }
+)
+```
+
+| Field | Rules |
+| --- | --- |
+| `button` | Required, max **20** characters — the label that opens the list |
+| `sections` | **1–10** sections |
+| `sections[].title` | Required, max **24** characters |
+| `sections[].rows` | **1–10** rows |
+| `rows[].id` | Required, max **200** characters |
+| `rows[].title` | Required, max **24** characters |
+| `rows[].description` | Optional, max **72** characters |
+
+```ruby
+Whatsapp::Messages::Interactive.new(
+  to: "+15551234567", type: :list_buttons, body: "Choose a drink",
+  action: { button: "Menu", sections: [
+    { title: "Coffee", rows: [{ id: "espresso", title: "Espresso", description: "Strong & short" }] },
+  ] }
+).serialize
+# => { ..., interactive: { type: "list", body: { text: "Choose a drink" },
+#      action: { button: "Menu",
+#                sections: [{ title: "Coffee",
+#                             rows: [{ id: "espresso", title: "Espresso",
+#                                      description: "Strong & short" }] }] } } }
+```
+
+A tap arrives back as a webhook `Message::Interactive` with
+`interactive_type == "list_reply"`.
+
+---
+
+## CTA URL button
+
+Surfaces a link as a tappable button instead of raw text in the body — clearer, and it
+sidesteps the link preview.
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567",
+  type: :url_button,
+  body: "Check out our new arrivals",
+  action: { name: "cta_url", display_text: "Shop now", url: "https://example.com/new" }
+)
+```
+
+| Field | Rules |
+| --- | --- |
+| `name` | Required, max **20** characters — always `"cta_url"` |
+| `display_text` | Required, max **20** characters — the button label |
+| `url` | The destination. **Not validated**, not even for presence |
+
+```ruby
+Whatsapp::Messages::Interactive.new(
+  to: "+15551234567", type: :url_button, body: "Check out our new arrivals",
+  action: { name: "cta_url", display_text: "Shop now", url: "https://example.com/new" }
+).serialize
+# => { ..., interactive: { type: "cta_url", body: { text: "Check out our new arrivals" },
+#      action: { name: "cta_url",
+#                parameters: { display_text: "Shop now", url: "https://example.com/new" } } } }
+```
+
+---
+
+## Media carousel
+
+**2–10** swipeable cards, each with its own header, body, CTA URL, and quick-reply
+buttons. `card_index` is assigned automatically from array position — do not pass it.
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567",
+  type: :media_carousel,
+  body: "Today's picks",
+  action: {
+    cards: [
+      {
+        header: { type: "image", link: "https://example.com/1.jpg" },
+        body: "Item one",
+        action: { name: "cta_url", display_text: "Buy", url: "https://example.com/1" },
+        buttons: [{ quick_reply: { id: "q1", title: "Details" } }],
+      },
+      {
+        header: { type: "image", link: "https://example.com/2.jpg" },
+        body: "Item two",
+        action: { name: "cta_url", display_text: "Buy", url: "https://example.com/2" },
+        buttons: [{ quick_reply: { id: "q2", title: "Details" } }],
+      },
+    ],
+  }
+)
+```
+
+| Field | Rules |
+| --- | --- |
+| `cards` | **2–10** cards |
+| `cards[].header` | Required — same shape as the message header (`link:` only for media) |
+| `cards[].body` | Required |
+| `cards[].action` | Required — a CTA URL action |
+| `cards[].buttons` | Required — array of `{ quick_reply: { id:, title: } }` |
+
+All five card keys are required Ruby keywords; omitting one raises `ArgumentError`,
+not a validation error.
+
+> **Two caveats.** The wire value `"carousel"` is flagged in the source as worth
+> re-checking against Meta's docs for your API version before relying on it in
+> production. And `MediaCarousel::Card::Button::QuickReply` declares `id`/`title`
+> length validations but never runs `validate!`, so an over-long or blank
+> `id`/`title` serializes silently and is rejected by Meta instead of locally.
+
+---
+
+## Product carousel
+
+**2–10** cards referencing products in your Meta catalog. Like the media carousel,
+`card_index` is assigned from array position.
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567",
+  type: :product_carousel,
+  body: "Recommended for you",
+  action: {
+    cards: [
+      { catalog_id: "123456789", product_retailer_id: "SKU-1" },
+      { catalog_id: "123456789", product_retailer_id: "SKU-2" },
+    ],
+  }
+)
+```
+
+| Field | Rules |
+| --- | --- |
+| `cards` | **2–10** cards |
+| `cards[].catalog_id` | Required (Ruby keyword) |
+| `cards[].product_retailer_id` | Required (Ruby keyword) |
+
+Card contents carry **no validations at all** — a wrong catalog or SKU surfaces
+server-side.
+
+> The wire value `"product_list"` carries the same "verify against your API version"
+> caveat as the media carousel.
+
+---
+
+## Request contact info
+
+Asks the recipient to share their phone number, which they hand over with one tap. The
+one action kind that takes no `action:` — there is nothing to configure:
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  recipient: "US.13491208655302741918",
+  type: :request_contact_info,
+  body: "Mind sharing your number so we can text you the confirmation?"
+)
+```
+
+```json
+{
+  "messaging_product": "whatsapp",
+  "recipient_type": "individual",
+  "recipient": "US.13491208655302741918",
+  "type": "interactive",
+  "interactive": {
+    "type": "request_contact_info",
+    "body": { "text": "Mind sharing your number so we can text you the confirmation?" },
+    "action": { "name": "request_contact_info" }
+  }
+}
+```
+
+Note `interactive.type` and `action.name` are the same literal — this is the only kind
+where the registry key and the wire value coincide.
+
+Use this inside the 24-hour service window; to *open* a conversation with the same ask,
+use the [`REQUEST_CONTACT_INFO` template button](../message_templates/components.md#the-request-contact-info-button)
+instead.
+
+Why you would: once a WhatsApp user adopts a username, their phone number can stop
+appearing in your webhooks, leaving only their
+[BSUID](README.md#business-scoped-user-ids-bsuid) — which is enough to keep messaging
+them, but not enough for a one-tap, zero-tap, or copy-code
+[authentication template](../message_templates/authentication.md). This is how you ask
+for the number back.
+
+A tap arrives as an inbound [`contacts` message](../webhooks/messages.md#contacts) whose
+`origin` is `"contact_request"`:
+
+```ruby
+when "messages"
+  change.value.messages.each do |message|
+    next unless message.type == "contacts"
+
+    shared = message.contacts.first
+    next unless shared.origin == "contact_request"
+
+    Customer.find_by(bsuid: message.from_user_id)
+      &.update!(wa_id: shared.phones.first&.wa_id)
+  end
+```
+
+Meta's published example shows no `header` or `footer`; both are accepted here and
+omitted from the payload when absent, as with every other kind.
+
+## Validation errors
+
+`Interactive` itself validates `type`, `body`, and `action` presence at construction.
+The **nested** action rules — button counts, title lengths, section limits — run when
+the payload is serialized, which for `send_interactive!` is still before any HTTP
+request:
+
+```ruby
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567", type: :telepathy, body: "Pick",
+  action: { buttons: [{ id: "a", title: "A" }] }
+)
+# => ActiveModel::ValidationError: Type is not included in the list
+
+Whatsapp::Messages.send_interactive!(
+  to: "+15551234567", type: :reply_buttons, body: "Pick",
+  action: { buttons: [{ id: "a", title: "A really quite long button label" }] }
+)
+# => ActiveModel::ValidationError: Title is too long (maximum is 20 characters)
+```
+
+---
+
+**Meta docs:**
+[CTA URL](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-cta-url-messages)
+· [lists](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-list-messages)

data/docs/messages/location.md

@@ -0,0 +1,51 @@
+# Location Messages
+
+Shares a fixed latitude/longitude pin — a shop, a pickup point, a venue. The inverse
+direction (asking the *user* where they are) is
+[Location Request](location_request.md).
+
+```ruby
+Whatsapp::Messages.send_location!(
+  to: "+15551234567",
+  latitude: 37.4847,
+  longitude: -122.1477,
+  name: "Meta HQ"
+)
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `latitude` | yes | Numeric |
+| `longitude` | yes | Numeric |
+| `name` | no | Label shown above the pin |
+| `address` | no | Street address shown under the name |
+
+Both coordinates are validated with `numericality`, so a string that doesn't parse as
+a number is rejected locally. `name` and `address` are free text — WhatsApp renders
+them as the pin's caption; without them the recipient sees bare coordinates.
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Location.new(
+  to: "+15551234567", latitude: 37.4847, longitude: -122.1477, name: "Meta HQ"
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "location",
+#   location: { latitude: 37.4847, longitude: -122.1477, name: "Meta HQ" }
+# }
+```
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_location!(to: "+15551234567", latitude: "here", longitude: -122.1477)
+# => ActiveModel::ValidationError: Latitude is not a number
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/location-messages>

data/docs/messages/location_request.md

@@ -0,0 +1,59 @@
+# Location Request Messages
+
+Asks the user to **share their current location back to the business** — the inverse
+of [Location](location.md). Useful for coordinating a delivery or a pickup without
+making the customer type an address.
+
+```ruby
+Whatsapp::Messages.send_location_request!(
+  to: "+15551234567",
+  body: "Can you share your delivery location?"
+)
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `body` | yes | The prompt text, max **1024** characters |
+
+## Serialized payload
+
+Despite being its own Ruby class, this travels as an interactive message on the wire
+(`type: "interactive"`, `interactive.type: "location_request_message"`):
+
+```ruby
+Whatsapp::Messages::LocationRequest.new(
+  to: "+15551234567", body: "Can you share your delivery location?"
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567",
+#   type: "interactive",
+#   interactive: {
+#     type: "location_request_message",
+#     body: "Can you share your delivery location?",
+#     action: { name: "send_location" }
+#   }
+# }
+```
+
+> **Known bug — confirmed broken against the live API.** `body` is serialized as a
+> bare String, but Meta's JSON schema requires `interactive.body` to be an object
+> (`{ text: ... }`) or null. [`Address`](address.md) and
+> [`Interactive`](interactive.md) both wrap body text correctly; this class does not,
+> and live testing returns a schema rejection. Not yet fixed — track it before
+> relying on this kind in production.
+
+## The reply
+
+The user's shared location arrives as an inbound webhook notification, deserialized
+into `Whatsapp::Webhook::Message::Location` with `latitude`, `longitude`, `name`, and
+`address`. See [../webhooks/messages.md](../webhooks/messages.md).
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_location_request!(to: "+15551234567", body: "")
+# => ActiveModel::ValidationError: Body can't be blank
+```

data/docs/messages/mark_message_as_read.md

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

data/docs/messages/reaction.md

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

data/docs/messages/sticker.md

@@ -0,0 +1,40 @@
+# Sticker Messages
+
+Sends a WhatsApp sticker asset (a WebP image, animated or static).
+
+```ruby
+Whatsapp::Messages.send_sticker!(to: "+15551234567", id: "STICKER_MEDIA_ID")
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` / `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 |
+
+**Either `id` or `link` is required** — prefer `id`. Stickers are almost always
+reused across many conversations, so uploading once and holding the ID avoids
+re-fetching the same asset on every send.
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Sticker.new(to: "+15551234567", id: "STICKER_MEDIA_ID").serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "sticker",
+#   sticker: { id: "STICKER_MEDIA_ID" }
+# }
+```
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_sticker!(to: "+15551234567")
+# => ActiveModel::ValidationError: Either id or link must be present
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/sticker-messages>