ruby-whatsapp 0.4.2 → 0.6.1

data/docs/errors.md

@@ -22,6 +22,7 @@ StandardError
     ├── Whatsapp::Media::MediaError                         any Media failure
     ├── Whatsapp::MessageTemplates::TemplateError           any template-management failure
     ├── Whatsapp::SubscribedApp::Error                      any subscribed-apps failure
+    ├── Whatsapp::Schedule::Error                           any campaign-schedule failure
     └── Whatsapp::BusinessPhoneNumber::Error                any phone-number-onboarding or account failure
 ```
 
@@ -85,9 +86,19 @@ end
 A required Ruby keyword that isn't supplied raises `ArgumentError`, not a validation
 error — it never reaches the validator:
 
+```ruby
+Whatsapp::Messages.send_text!(to: "+15551234567")
+# => ArgumentError: missing keyword: :body
+```
+
+The recipient is the exception. Since a message can be addressed by phone number
+(`to:`) *or* by [BSUID](messages/README.md#addressing-to-recipient-or-both)
+(`recipient:`), neither keyword is individually required, so omitting both is a
+validation failure rather than an arity one:
+
 ```ruby
 Whatsapp::Messages.send_text!(body: "Hi")
-# => ArgumentError: missing keyword: :to
+# => ActiveModel::ValidationError: at least one of to or recipient must be provided
 ```
 
 ## API failures

data/docs/message_templates/README.md

@@ -191,7 +191,7 @@ templates.delete(hsm_ids: [], name: "x")
   [`Media#upload`](../media/README.md), whose media IDs are for *sending*, not
   template creation.
 - **Undocumented button types:** `FLOW`, `MPM`, `CATALOG`, `VOICE_CALL`, `VIDEO_CALL`,
-  `POSTBACK`, `BOOKING_STATUS`, `PAYMENT_REQUEST`, `REQUEST_CONTACT_INFO`. Named in
+  `POSTBACK`, `BOOKING_STATUS`, `PAYMENT_REQUEST`. Named in
   Meta's Graph enum with no published field reference.
   [`LibraryTemplate`](library.md) does accept most of them, because Meta documents them
   by name in *that* context.

data/docs/message_templates/components.md

@@ -108,6 +108,7 @@ Resolved through the frozen `Button::TYPES` registry.
 | `:phone_number` | `PHONE_NUMBER` | `text` ≤ 25, `phone_number` ≤ **20** |
 | `:copy_code` | `COPY_CODE` | `example` ≤ **20** (a bare String), **no `text`** |
 | `:otp` | `OTP` | `otp_type`, `supported_apps`, `zero_tap_terms_accepted` |
+| `:request_contact_info` | `REQUEST_CONTACT_INFO` | **no fields** — `text` optional and only ever `"Share Contact Info"` |
 
 ```ruby
 { type: :quick_reply,  text: "More like this" }
@@ -115,6 +116,7 @@ Resolved through the frozen `Button::TYPES` registry.
 { type: :phone_number, text: "Call", phone_number: "15550051310" }
 { type: :copy_code,    example: "SPRING25" }
 { type: :otp,          otp_type: "COPY_CODE" }
+{ type: :request_contact_info }
 ```
 
 ### The URL button's single trailing variable
@@ -146,6 +148,39 @@ those labels:
 #    Meta supplies the label
 ```
 
+### The request-contact-info button
+
+Asks the recipient to share their phone number, which they hand over with one tap. It
+takes nothing:
+
+```ruby
+{ type: :buttons, buttons: [{ type: :request_contact_info }] }
+```
+
+This is the counterpart to Meta's usernames rollout: once a user adopts a username their
+phone number may stop reaching you, leaving only their
+[BSUID](../webhooks/messages.md#business-scoped-user-ids-bsuid). It is also the only way
+to reach such a user with a one-tap, zero-tap, or copy-code
+[authentication template](authentication.md), since those require a phone number.
+
+Three things about it:
+
+- **The label is not customizable.** Meta renders it in the recipient's own app language.
+  A `text` field is accepted but must be exactly `"Share Contact Info"`, so the simplest
+  correct thing is to omit it.
+- **`UTILITY` and `MARKETING` only** — a cross-component rule, listed below.
+- **Nothing to fill in when sending.** Unlike a URL or copy-code button, it takes no
+  parameter values, so a template carrying one needs no `button` component in the
+  [send payload](../messages/template.md) at all.
+
+A tap arrives as an inbound [`contacts` message](../webhooks/messages.md#contacts) whose
+`origin` is `"contact_request"`. There is also an
+[interactive-message form](../messages/interactive.md) of the same button, for use inside
+the 24-hour service window.
+
+No per-type cap is enforced: Meta publishes none, and inventing one would reject valid
+payloads — the same reason `OTP` is uncapped. The overall 10-button limit still applies.
+
 ## Cross-component rules
 
 Owned by `ComponentSet`, because it is the only object that can see the siblings:
@@ -155,6 +190,7 @@ Owned by `ComponentSet`, because it is the only object that can see the siblings
   `LIMITED_TIME_OFFER`.
 - `CAROUSEL` or `LIMITED_TIME_OFFER` → category must be `MARKETING`.
 - A `LOCATION` header → category must be `UTILITY` or `MARKETING`.
+- A `REQUEST_CONTACT_INFO` button → category must be `UTILITY` or `MARKETING`.
 - `LIMITED_TIME_OFFER` present → `FOOTER` forbidden, `BODY` ≤ **600**, header
   `IMAGE`/`VIDEO` only, copy-code `example` ≤ **15** and that button must be **first**.
 
@@ -170,7 +206,7 @@ enum but deliberately absent:
 - **Components:** `GREETING`, `ALBUM`, `CALL_PERMISSION_REQUEST`,
   `TAP_TARGET_CONFIGURATION`, `ATTACHMENT`.
 - **Buttons:** `FLOW`, `MPM`, `CATALOG`, `VOICE_CALL`, `VIDEO_CALL`, `POSTBACK`,
-  `BOOKING_STATUS`, `PAYMENT_REQUEST`, `REQUEST_CONTACT_INFO`. Most of these *are*
+  `BOOKING_STATUS`, `PAYMENT_REQUEST`. Most of these *are*
   accepted by [`LibraryTemplate`](library.md), because Meta documents them by name in
   that context.
 

data/docs/messages/README.md

@@ -61,9 +61,8 @@ Plus one endpoint that isn't a message kind at all:
 
 ## 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:
+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
 {
@@ -75,6 +74,56 @@ kind-specific hash in a common envelope:
 }
 ```
 
+### 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"`.
@@ -95,13 +144,38 @@ body shaped like:
 ```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
+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).
@@ -110,7 +184,7 @@ status-update endpoints that reply `{"success": true}` — today just
 
 | Raised | When |
 | --- | --- |
-| `ArgumentError` | `to:` (or another required keyword) is missing |
+| `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 |
@@ -122,6 +196,9 @@ field raises at *construction* time, before a client is ever touched:
 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,

data/docs/messages/address.md

@@ -20,7 +20,7 @@ Whatsapp::Messages.send_address!(
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |

data/docs/messages/audio.md

@@ -10,7 +10,7 @@ Whatsapp::Messages.send_audio!(to: "+15551234567", link: "https://example.com/cl
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |
 

data/docs/messages/contacts.md

@@ -15,7 +15,7 @@ Whatsapp::Messages.send_contacts!(
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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

data/docs/messages/document.md

@@ -15,7 +15,7 @@ Whatsapp::Messages.send_document!(
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |

data/docs/messages/image.md

@@ -14,7 +14,7 @@ Whatsapp::Messages.send_image!(
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |

data/docs/messages/interactive.md

@@ -14,15 +14,16 @@ Unlike every other kind, `Interactive` is a **single class** that dispatches on
 | `: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` | yes | The recipient's phone number |
-| `type` | yes | One of the five keys above (Symbol or String) |
+| `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` | yes | Shape depends on `type` — see each section |
+| `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 |
 
@@ -253,6 +254,66 @@ server-side.
 
 ---
 
+## 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.

data/docs/messages/location.md

@@ -17,7 +17,7 @@ Whatsapp::Messages.send_location!(
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |

data/docs/messages/location_request.md

@@ -15,7 +15,7 @@ Whatsapp::Messages.send_location_request!(
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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

data/docs/messages/reaction.md

@@ -11,7 +11,7 @@ Whatsapp::Messages.send_reaction!(to: "+15551234567", message_id: "wamid.HBg..."
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |
 

data/docs/messages/sticker.md

@@ -10,7 +10,7 @@ Whatsapp::Messages.send_sticker!(to: "+15551234567", id: "STICKER_MEDIA_ID")
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |
 

data/docs/messages/template.md

@@ -23,7 +23,7 @@ Whatsapp::Messages.send_template!(
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `to` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
 | `name` | yes | The approved template's name |
 | `language` | yes | `{ code: "en_US" }` — validated against the supported list |
 | `components` | no | Array of components supplying placeholder values. Defaults to `[]` |
@@ -36,6 +36,33 @@ Whatsapp::Utils::LanguageCodes.valid?("en_US")  # => true
 Whatsapp::Utils::LanguageCodes.all.size         # => 71
 ```
 
+### Authentication templates cannot go to a BSUID
+
+One-tap, zero-tap, and copy-code
+[authentication templates](../message_templates/authentication.md) require the
+recipient's **phone number**. Address one to a
+[BSUID](README.md#business-scoped-user-ids-bsuid) via `recipient:` and Meta answers
+with error `131062`:
+
+```
+Business-scoped User ID (BSUID) recipients are not supported for this message.
+```
+
+The gem cannot catch this locally, and deliberately does not try. A template is
+addressed at send time by `name` and `language` only — `Messages::Template` never
+learns its own category, and the OTP configuration lives in the WABA. Guessing from
+`components` would be worse than not guessing: a `copy_code` sub-type appears both on
+copy-code authentication templates *and* on limited-time-offer marketing templates,
+which have no such restriction, so any local rule would reject valid sends.
+
+If you need to reach a username-only user with an authentication template, ask for
+their phone number first — see the `REQUEST_CONTACT_INFO` button in
+[components.md](../message_templates/components.md).
+
+> Meta names one-tap, zero-tap, and copy-code specifically. Whether a plain
+> `NO_BUTTONS` authentication template is also refused is **not documented** — treat it
+> as untested rather than assuming either way.
+
 ## Components
 
 A component supplies the *values* for the placeholders the template defines. It has a

data/docs/messages/text.md

@@ -12,7 +12,7 @@ Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hello from ruby-whatsap
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `to` / `recipient` | at least one | Phone number and/or [BSUID](README.md#addressing-to-recipient-or-both) |
 | `body` | yes | Max **4096** characters |
 | `preview_url` | no | `true` or `false`. **Defaults to `true`** |
 

data/docs/messages/video.md

@@ -10,7 +10,7 @@ Whatsapp::Messages.send_video!(to: "+15551234567", id: "1234567890", caption: "D
 
 | Field | Required | Rules |
 | --- | --- | --- |
-| `to` | yes | The recipient's phone number |
+| `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 |