ruby-whatsapp 0.4.0 → 0.6.1

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,212 @@
+# 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 the
+recipient 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
+}
+```
+
+### Addressing: `to`, `recipient`, or both
+
+There are two ways to name a recipient, and **at least one is required**:
+
+| Keyword | Value |
+| --- | --- |
+| `to` | The recipient's phone number |
+| `recipient` | Their [business-scoped user ID](#business-scoped-user-ids-bsuid) (BSUID), or parent BSUID |
+
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi")            # phone number
+Whatsapp::Messages.send_text!(recipient: "US.13491208655302741918", body: "Hi")  # BSUID
+```
+
+Pass both and Meta gives `to` precedence, answering as though `recipient` had not been
+sent. Pass neither and you get an `ActiveModel::ValidationError` before any request:
+
+```ruby
+Whatsapp::Messages.send_text!(body: "Hi")
+# => ActiveModel::ValidationError: at least one of to or recipient must be provided
+```
+
+Whichever you omit is left out of the payload entirely, never sent as `null`.
+
+#### Business-scoped user IDs (BSUID)
+
+Once a WhatsApp user adopts a username, their phone number can stop appearing in your
+webhooks — and their BSUID becomes the only identifier you have. `recipient` is how you
+reply to them. A BSUID is a country code, a period, and up to 128 alphanumeric
+characters (`"US.13491208655302741918"`); a
+[parent BSUID](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#parent-business-scoped-user-ids),
+usable across enrolled business portfolios, carries an extra `ENT.` segment
+(`"US.ENT.11815799212886844830"`). Pass the whole value — dropping or altering any part
+of it fails the request.
+
+The gem does **not** format-check it. Meta describes the shape but publishes no
+client-side rule, and the value you pass here normally comes straight off the
+[inbound webhook side](../webhooks/messages.md#business-scoped-user-ids-bsuid), which
+keeps it as a raw string. Replying to a customer Meta just told you about is exactly the
+case a local regex would break.
+
+```ruby
+# In your webhook handler, replying to whoever wrote in
+contact = change.value.contacts.first
+Whatsapp::Messages.send_text!(recipient: contact.user_id, body: "Thanks for reaching out!")
+```
+
+BSUIDs are scoped to a business portfolio: a BSUID from one portfolio cannot be
+messaged from a phone number owned by another.
+
+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.contacts.first.user_id # => nil — see below
+response.success                # => nil for a normal send
+```
+
+Which identifiers come back mirrors how you addressed the message:
+
+| Accessor | Value |
+| --- | --- |
+| `input` | Exactly what you sent: the phone number, the BSUID or parent BSUID, or a group ID |
+| `wa_id` | The phone number — **only** if you addressed it by phone number |
+| `user_id` | The BSUID or parent BSUID — **only** if you addressed it by BSUID |
+
+```ruby
+response = Whatsapp::Messages.send_text!(recipient: "US.13491208655302741918", body: "Hi")
+
+response.contacts.first.input   # => "US.13491208655302741918"
+response.contacts.first.user_id # => "US.13491208655302741918"
+response.contacts.first.wa_id   # => nil
+```
+
+> **The precedence trap.** Send both `to` and `recipient` and `user_id` comes back
+> **omitted**, because `to` wins and Meta answers as though you had only sent that. So
+> `user_id` being `nil` does not mean the recipient has no BSUID — and code that
+> correlates a send by reading `contacts.first.user_id` must not also pass `to:`.
+
+Unlike the webhook classes, which separate `user_id` from `parent_user_id`, the send
+response returns either kind in the single `user_id` field.
+
+`#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` | A required keyword is missing (the recipient is a *validation*, not an arity, concern — see below) |
+| `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.send_text!(body: "Hi")
+# => ActiveModel::ValidationError: at least one of to or recipient must be provided
+
+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` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `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` / `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.**
+
+> **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>

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` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
+| `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` / `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 |
+| `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>