ruby-whatsapp 0.4.0 → 0.4.2

data/docs/messages/contacts.md

@@ -0,0 +1,129 @@
+# Contact Messages
+
+Shares a structured, vCard-like contact card the recipient can tap once to save,
+instead of pasting a phone number into a text message and hoping they copy it
+correctly.
+
+```ruby
+Whatsapp::Messages.send_contacts!(
+  to: "+15551234567",
+  contacts: [{ name: { formatted_name: "Jane Doe", first_name: "Jane", last_name: "Doe" } }]
+)
+```
+
+## Fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `contacts` | yes | An array containing **exactly one** contact |
+
+> **Exactly one contact.** The Cloud API currently accepts a single contact per
+> message. An empty array raises `Contacts can't be blank`; two or more raises
+> `Contacts is too long`. To share several people, send several messages.
+
+Each entry in `contacts` is a hash (or a `Contacts::Contact`) composed of:
+
+| Key | Required | Type |
+| --- | --- | --- |
+| `name` | yes | `Name` |
+| `phones` | no | `Array<Phone>` |
+| `emails` | no | `Array<Email>` |
+| `addresses` | no | `Array<Address>` |
+| `urls` | no | `Array<Url>` |
+| `org` | no | `Org` |
+| `birthday` | no | `"YYYY-MM-DD"` string |
+
+### Sub-object fields
+
+| Object | Fields | Notes |
+| --- | --- | --- |
+| `Name` | `formatted_name` (**required**), `first_name`, `last_name`, `middle_name`, `prefix`, `suffix` | |
+| `Phone` | `phone` (**required**), `type`, `wa_id` | `type`: `CELL` `MAIN` `IPHONE` `HOME` `WORK` `OTHER` |
+| `Email` | `email` (**required**), `type` | `type`: `HOME` `WORK` `OTHER` |
+| `Address` | `street`, `city`, `state`, `zip`, `country`, `country_code`, `type` | all optional; `type`: `HOME` `WORK` `OTHER` |
+| `Url` | `url` (**required**), `type` | `type`: `WEBSITE` `HOMEPAGE` `WORK` `HOME` `OTHER` |
+| `Org` | `company`, `department`, `title` | all optional, no validation |
+
+## A full example
+
+```ruby
+Whatsapp::Messages.send_contacts!(
+  to: "+15551234567",
+  contacts: [
+    {
+      name: { formatted_name: "Jane Doe", first_name: "Jane", last_name: "Doe" },
+      phones: [{ phone: "+15550001111", type: "WORK" }],
+      emails: [{ email: "jane@example.com", type: "WORK" }],
+      addresses: [{ street: "1 Hacker Way", city: "Menlo Park", state: "CA",
+                    zip: "94025", country: "United States", country_code: "us", type: "WORK" }],
+      urls: [{ url: "https://example.com", type: "WEBSITE" }],
+      org: { company: "Acme Inc.", department: "Support", title: "Lead" },
+      birthday: "1990-05-12",
+    },
+  ]
+)
+```
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Contacts.new(
+  to: "+15551234567",
+  contacts: [
+    {
+      name: { formatted_name: "Jane Doe", first_name: "Jane", last_name: "Doe" },
+      phones: [{ phone: "+15550001111", type: "WORK" }],
+      emails: [{ email: "jane@example.com", type: "WORK" }],
+      org: { company: "Acme Inc." },
+      birthday: "1990-05-12",
+    },
+  ]
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "contacts",
+#   contacts: [{
+#     name: { formatted_name: "Jane Doe", first_name: "Jane", last_name: "Doe" },
+#     phones: [{ phone: "+15550001111", type: "WORK" }],
+#     emails: [{ email: "jane@example.com", type: "WORK" }],
+#     org: { company: "Acme Inc." },
+#     birthday: "1990-05-12"
+#   }]
+# }
+```
+
+Every sub-object compacts its own hash, and `Contact` omits `phones`/`emails`/
+`addresses`/`urls` entirely when they're empty — so a minimal card is just `name`.
+
+> **Known gap.** `Contacts::Name` validates only the presence of `formatted_name`, but
+> live testing returns `(#131009) ContactName should have atleast one optional value be
+> set along with formatted Name`. Meta requires at least one *additional* name field
+> (e.g. `first_name`) alongside `formatted_name`; this class doesn't yet enforce it, so
+> a name-only card passes local validation and is rejected server-side. Always set a
+> second name field.
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_contacts!(to: "+15551234567", contacts: [])
+# => ActiveModel::ValidationError: Contacts can't be blank
+
+Whatsapp::Messages.send_contacts!(to: "+15551234567", contacts: [contact_a, contact_b])
+# => ActiveModel::ValidationError: Contacts is too long (maximum is 1 character)
+
+Whatsapp::Messages.send_contacts!(to: "+15551234567", contacts: [{ name: { first_name: "Jane" } }])
+# => ArgumentError: missing keyword: :formatted_name
+
+Whatsapp::Messages.send_contacts!(to: "+15551234567", contacts: [{ name: { formatted_name: "" } }])
+# => ActiveModel::ValidationError: Formatted name can't be blank
+
+Whatsapp::Messages.send_contacts!(
+  to: "+15551234567",
+  contacts: [{ name: { formatted_name: "Jane Doe" }, phones: [{ phone: "+1", type: "MOBILE" }] }]
+)
+# => ActiveModel::ValidationError: Type is not included in the list
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/contacts-messages>

data/docs/messages/document.md

@@ -0,0 +1,49 @@
+# Document Messages
+
+Shares a file — an invoice, a contract, a PDF — with an optional caption and the
+filename the recipient sees.
+
+```ruby
+Whatsapp::Messages.send_document!(
+  to: "+15551234567",
+  link: "https://example.com/invoice.pdf",
+  filename: "invoice.pdf"
+)
+```
+
+## 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 |
+| `caption` | no | Max **1024** characters |
+| `filename` | no | The name shown to the recipient; not validated |
+
+**Either `id` or `link` is required.** Without `filename`, WhatsApp falls back to
+whatever it can infer from the URL or media asset, which is usually an unhelpful
+hash — set it whenever the recipient will save the file.
+
+## Serialized payload
+
+```ruby
+Whatsapp::Messages::Document.new(
+  to: "+15551234567", link: "https://example.com/invoice.pdf", filename: "invoice.pdf"
+).serialize
+# => {
+#   messaging_product: "whatsapp", recipient_type: "individual", to: "+15551234567", type: "document",
+#   document: { link: "https://example.com/invoice.pdf", filename: "invoice.pdf" }
+# }
+```
+
+## Validation errors
+
+```ruby
+Whatsapp::Messages.send_document!(to: "+15551234567", filename: "invoice.pdf")
+# => ActiveModel::ValidationError: Either id or link must be present
+```
+
+---
+
+**Meta docs:** <https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/document-messages>

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` | 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 |
+| `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,281 @@
+# 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) |
+
+## Shared fields
+
+| Field | Required | Rules |
+| --- | --- | --- |
+| `to` | yes | The recipient's phone number |
+| `type` | yes | One of the five keys above (Symbol or String) |
+| `body` | yes | Body text, max **1024** characters |
+| `action` | yes | Shape depends on `type` — see each section |
+| `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.
+
+---
+
+## 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` | yes | The recipient's phone number |
+| `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` | yes | The recipient's phone number |
+| `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
+```