ruby-whatsapp 0.4.0 → 0.6.1

data/README.md

@@ -1,450 +1,245 @@
-# ruby-whatsapp
+<h1 align="center">ruby-whatsapp</h1>
 
-[![Gem Version](https://img.shields.io/gem/v/ruby-whatsapp.svg)](https://rubygems.org/gems/ruby-whatsapp)
-[![Build Status](https://github.com/saleszera/ruby-whatsapp/actions/workflows/main.yml/badge.svg)](https://github.com/saleszera/ruby-whatsapp/actions/workflows/main.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+<p align="center">
+  <strong>A small, dependency-light Ruby client for the Meta WhatsApp Cloud API.</strong>
+</p>
 
-A small, dependency-light Ruby client for the [Meta WhatsApp Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp). Every message type the Cloud API supports — text, media, location, contacts, templates, and the full family of interactive messages (reply buttons, lists, CTA URLs, carousels) — is modeled as its own `ActiveModel`-validated Ruby class, so a malformed payload raises locally instead of round-tripping to Meta's servers first. The gem also handles media upload/download and parses API responses into typed objects.
+<p align="center">
+  <a href="https://rubygems.org/gems/ruby-whatsapp"><img alt="Gem Version" src="https://img.shields.io/gem/v/ruby-whatsapp.svg"></a>
+  <a href="https://github.com/saleszera/ruby-whatsapp/actions/workflows/main.yml"><img alt="Build Status" src="https://github.com/saleszera/ruby-whatsapp/actions/workflows/main.yml/badge.svg"></a>
+  <a href="https://rubygems.org/gems/ruby-whatsapp"><img alt="Downloads" src="https://img.shields.io/gem/dt/ruby-whatsapp.svg"></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/ruby-%3E%3D%203.2-CC342D.svg"></a>
+</p>
 
-## Table of Contents
-
-- [Installation](#installation)
-- [Configuration](#configuration)
-- [Quick Start](#quick-start)
-- [Features](#features)
-- [Sending Messages](#sending-messages)
-  - [Text](#text)
-  - [Image](#image)
-  - [Video](#video)
-  - [Audio](#audio)
-  - [Document](#document)
-  - [Sticker](#sticker)
-  - [Reaction](#reaction)
-  - [Location](#location)
-  - [Contacts](#contacts)
-  - [Address](#address)
-  - [Location Request](#location-request)
-  - [Template](#template)
-  - [Interactive](#interactive)
-  - [Mark Message As Read](#mark-message-as-read)
-- [Handling Responses](#handling-responses)
-- [Media](#media)
-- [Managing Templates](#managing-templates)
-- [Managing Subscribed Apps](#managing-subscribed-apps)
-- [Registering Business Phone Numbers](#registering-business-phone-numbers)
-- [Webhooks](#webhooks)
-- [Development](#development)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Installation
-
-Add to your Gemfile:
-
-```ruby
-gem "ruby-whatsapp"
-```
-
-Then run `bundle install`. Or install directly:
-
-```bash
-gem install ruby-whatsapp
-```
-
-## Configuration
-
-```ruby
-Whatsapp.configure do |config|
-  config.api_key  = ENV.fetch("WHATSAPP_TOKEN")   # a Meta system-user / app access token
-  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID") # the sending phone number ID
-  # optional overrides:
-  # config.version      = "v24.0"
-  # config.host         = "https://graph.facebook.com"
-  # config.waba_id      = ENV.fetch("WHATSAPP_WABA_ID")   # for template management, see below
-  # config.verify_token = ENV.fetch("WHATSAPP_VERIFY_TOKEN") # for webhooks, see below
-  # config.app_secret   = ENV.fetch("WHATSAPP_APP_SECRET")   # for webhooks, see below
-end
-```
-
-`api_key`, `app_secret`, and `verify_token` are redacted from `Configuration#inspect` and `Client#inspect`, so they will not leak into logs or error reports.
-
-## Quick Start
-
-```ruby
-require "ruby/whatsapp"
-
-Whatsapp.configure do |config|
-  config.api_key  = ENV.fetch("WHATSAPP_TOKEN")
-  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID")
-end
-
-response = Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hello from ruby-whatsapp!")
-
-response.messages.first.id # => "wamid.HBgLMTU1NTU1NTU1NTUV..."
-```
+---
 
-## Features
-
-- **Typed, validated message classes** for every Cloud API message kind — invalid payloads raise before any HTTP request is made.
-- **Persistent HTTP connections** via `HTTP.persistent`, reused across requests.
-- **Pluggable instrumentation** — pass a `Logger` to `Whatsapp::Client.new` to log every request/response.
-- **Hardened media downloads** — `Media#download` refuses to attach the bearer token to non-HTTPS URLs or hosts outside an allowlist, so a token can never leak to an attacker-influenced URL.
-- **Structured response parsing** — `Whatsapp::Messages::Response` exposes typed `#contacts` and `#messages` instead of raw JSON.
-- **Template management** — create, list, edit and delete the message templates on your WhatsApp Business Account from Ruby, with Meta's documented rules checked client-side so a rejection costs a validation error instead of a 24-hour review cycle.
-- **Subscribed apps management** — subscribe or unsubscribe this app from a WhatsApp Business Account's webhook notifications, and list who's currently subscribed, straight from Ruby.
-- **Business phone number onboarding** — request and verify a phone number's verification code, then register or deregister it with Cloud API, with the 6-digit two-step verification PIN and local-storage region checked client-side before any request is made.
-- **Inbound webhook parsing** — a typed object tree for all 19 documented Meta notification field types, plus signature verification.
-
-## Sending Messages
-
-Every registered message kind gets its own `Whatsapp::Messages.send_<kind>!` class method — pass the recipient and the kind-specific fields as keyword arguments:
+Every message type the Cloud API supports — text, media, location, contacts,
+templates, and the full family of interactive messages — is modeled as its own
+`ActiveModel`-validated Ruby class. A malformed payload raises **in your own process,
+naming the field that's wrong**, instead of travelling to Meta and coming back as
+error `131009` — the catch-all code the Cloud API returns for a too-long caption, an
+unsupported message type, a bad message ID, and a dozen other unrelated mistakes.
 
 ```ruby
-Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hello!")
-```
+photo = "https://example.com/new-arrivals.jpg"
 
-Each `send_<kind>!` method accepts an optional `client:` keyword (defaults to a new `Whatsapp::Client` built from `Whatsapp.configuration`) and returns a `Whatsapp::Messages::Response` (see [Handling Responses](#handling-responses)). It raises `ActiveModel::ValidationError` if any field fails validation, and `Whatsapp::RequestError` on a non-2xx API response.
+# Send it 📸
+Whatsapp::Messages.send_image!(to: "+15551234567", link: photo, caption: "Just landed")
 
-If the kind is only known at runtime, drop down to the underlying factory these methods are built on:
-
-```ruby
-Whatsapp::Messages.new(
-  kind: :text, # or a variable
-  payload: { to: "+15551234567", body: "Hello!" },
-  client: Whatsapp::Client.new # optional — defaults to a new Client built from Whatsapp.configuration
-).send!
+# Get a field wrong, and you find out here — not from Meta, three seconds later
+Whatsapp::Messages.send_image!(to: "+15551234567", link: photo, caption: "x" * 2000)
+# => ActiveModel::ValidationError: Caption is too long (maximum is 1024 characters)
 ```
 
-This form raises `Whatsapp::Messages::PayloadError` for an unknown `kind` (in addition to the same validation/request errors above).
+Beyond sending, the gem covers the whole surface: media upload and download, template
+creation and management, inbound webhook parsing, webhook subscription, phone number
+onboarding, and reading or updating the business account itself.
 
-| Method | Sends |
-| --- | --- |
-| [`send_text!`](#text) | Plain text with an optional link preview |
-| [`send_image!`](#image) | An image with an optional caption |
-| [`send_video!`](#video) | A video with an optional caption |
-| [`send_audio!`](#audio) | An audio clip |
-| [`send_document!`](#document) | A file with an optional caption and filename |
-| [`send_sticker!`](#sticker) | A sticker |
-| [`send_reaction!`](#reaction) | An emoji reaction to a previous message |
-| [`send_location!`](#location) | A latitude/longitude pin |
-| [`send_contacts!`](#contacts) | A rich contact card |
-| [`send_address!`](#address) | A delivery-address request/confirmation form (India & Singapore only) |
-| [`send_location_request!`](#location-request) | A prompt asking the user to share their location |
-| [`send_template!`](#template) | A pre-approved marketing/utility/authentication template |
-| [`send_interactive!`](#interactive) | Reply buttons, lists, CTA URLs, or carousels |
-
-### Text
-
-```ruby
-Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hello!", preview_url: false)
-```
-
-`body` is required (max 4096 characters). `preview_url` defaults to `true`.
-
-### Image
+## Table of Contents
 
-```ruby
-Whatsapp::Messages.send_image!(
-  to: "+15551234567",
-  link: "https://example.com/photo.jpg",
-  caption: "Our new product"
-)
+- [✨ Why ruby-whatsapp](#-why-ruby-whatsapp)
+- [📦 Installation](#-installation)
+- [🔧 Configuration](#-configuration)
+- [🚀 Quick Start](#-quick-start)
+- [📚 Documentation](#-documentation)
+- [💬 Sending Messages](#-sending-messages)
+- [📋 Managing Templates](#-managing-templates)
+- [🔔 Webhooks](#-webhooks)
+- [📷 Media](#-media)
+- [🔌 Subscribed Apps](#-subscribed-apps)
+- [📅 Scheduling Campaigns](#-scheduling-campaigns)
+- [📞 Business Phone Numbers](#-business-phone-numbers)
+- [🚨 Errors](#-errors)
+- [🧩 Compatibility](#-compatibility)
+- [🔨 Development](#-development)
+- [🤝 Contributing](#-contributing)
+- [📄 License](#-license)
+
+## ✨ Why ruby-whatsapp
+
+- **Typed, validated message classes** for every Cloud API message kind — invalid
+  payloads raise before any HTTP request is made, with the failing attribute named.
+- **Template rules checked client-side.** Meta's documented constraints — name format,
+  character limits, placeholder/example matching, quick-reply contiguity, carousel
+  structure — are enforced locally, so a mistake costs a validation error instead of a
+  24-hour review cycle.
+- **Hardened media downloads.** `Media#download` refuses to attach your bearer token to
+  a non-HTTPS URL or a host outside an allowlist, so a token can never leak to an
+  attacker-influenced URL.
+- **Secrets stay out of logs.** `api_key`, `app_secret`, and `verify_token` are
+  redacted from every `#inspect`, including credentials in transit like a
+  registration PIN.
+- **Inbound webhooks, fully typed.** An object tree for all 21 documented Meta
+  notification fields, plus HMAC signature verification and a Rails controller
+  generator.
+- **Usernames and BSUIDs, both directions.** Once a WhatsApp user adopts a username,
+  their phone number can vanish from your payloads. Inbound notifications still identify
+  their sender through a Business-Scoped User ID, and `recipient:` sends straight back to
+  one — so a BSUID read off a webhook can be replied to without ever knowing the number.
+  Your own business username is managed too, along with Meta's contact book.
+- **Persistent HTTP connections** via `HTTP.persistent`, reused across requests, with
+  pluggable logging.
+- **Four runtime dependencies**, no Rails requirement. Rails integration activates
+  itself when Rails is present.
+
+## 📦 Installation
+
+```ruby
+# Gemfile
+gem "ruby-whatsapp"
 ```
 
-Either `id` (an uploaded [media](#media) ID) or `link` is required. `caption` is optional (max 1024 characters).
-
-### Video
-
-```ruby
-Whatsapp::Messages.send_video!(to: "+15551234567", id: "1234567890", caption: "Demo video")
+```bash
+bundle install
 ```
 
-Either `id` or `link` is required. `caption` is optional (max 1024 characters).
-
-### Audio
+Or standalone:
 
-```ruby
-Whatsapp::Messages.send_audio!(to: "+15551234567", link: "https://example.com/clip.mp3")
+```bash
+gem install ruby-whatsapp
 ```
 
-Either `id` or `link` is required. Audio messages do not support captions.
-
-### Document
+## 🔧 Configuration
 
 ```ruby
-Whatsapp::Messages.send_document!(
-  to: "+15551234567",
-  link: "https://example.com/invoice.pdf",
-  filename: "invoice.pdf"
-)
+Whatsapp.configure do |config|
+  config.api_key  = ENV.fetch("WHATSAPP_API_KEY")   # a Meta system-user / app access token
+  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID")  # the sending phone number ID
+end
 ```
 
-Either `id` or `link` is required. `caption` (max 1024 characters) and `filename` are optional.
+| Option | Default | Needed for |
+| --- | --- | --- |
+| `api_key` | — | Everything |
+| `phone_id` | — | Messages, media, phone-number onboarding |
+| `waba_id` | — | Template management, subscribed apps, the business account |
+| `verify_token` | — | The webhook GET handshake |
+| `app_secret` | — | Webhook signature verification |
+| `host` | `https://graph.facebook.com` | Overriding the API host |
+| `version` | `v24.0` | Pinning a Graph API version |
+| `media_host_allowlist` | 3 Meta hosts | Media download safety |
 
-### Sticker
+**Which ID addresses what** — the most common source of confusion:
 
-```ruby
-Whatsapp::Messages.send_sticker!(to: "+15551234567", id: "STICKER_MEDIA_ID")
 ```
+phone_id  ──►  Messages · Media · BusinessPhoneNumber
+               permission: whatsapp_business_messaging
 
-Either `id` or `link` is required — prefer `id` (from [`Media#upload`](#media)) over `link` for performance.
-
-### Reaction
-
-```ruby
-Whatsapp::Messages.send_reaction!(to: "+15551234567", message_id: "wamid.HBg...", emoji: "👍")
+waba_id   ──►  MessageTemplates · SubscribedApp · Schedule · BusinessPhoneNumber::Account
+               permission: whatsapp_business_management
 ```
 
-`message_id` and `emoji` are required. Pass `emoji: ""` to remove a reaction you sent previously.
+`BusinessPhoneNumber` appears on both sides: its onboarding actions address a phone
+number, its `Account` actions the account that number belongs to.
 
-### Location
+`Schedule`'s permission is an assumption: Meta's Schedules reference names none, so it
+is grouped under `whatsapp_business_management` only because it addresses the WABA.
 
-```ruby
-Whatsapp::Messages.send_location!(to: "+15551234567", latitude: 37.4847, longitude: -122.1477, name: "Meta HQ")
-```
+`api_key`, `app_secret`, and `verify_token` are redacted from `Configuration#inspect`
+and `Client#inspect`, so they will not leak into logs or error reports.
 
-`latitude` and `longitude` are required. `name` and `address` are optional.
+→ **[Full configuration reference](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/configuration.md)**
 
-### Contacts
+## 🚀 Quick Start
 
 ```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" }],
-      org: { company: "Acme Inc." },
-      birthday: "1990-05-12",
-    },
-  ]
-)
-```
+require "ruby/whatsapp"
 
-`contacts` must contain exactly one contact — the Cloud API currently allows only one per message. Each contact requires a `name.formatted_name`; `phones`, `emails`, `addresses`, `org`, `urls`, and `birthday` are all optional.
+Whatsapp.configure do |config|
+  config.api_key  = ENV.fetch("WHATSAPP_API_KEY")
+  config.phone_id = ENV.fetch("WHATSAPP_PHONE_ID")
+end
 
-### Address
+response = Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hello from ruby-whatsapp!")
 
-```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", city: "Bangalore" }
-)
+response.messages.first.id     # => "wamid.HBgLMTU1NTU1NTU1NTUV..."
+response.contacts.first.wa_id  # => "15551234567"
 ```
 
-Only available for businesses based in India (`country: "IN"`) or Singapore (`country: "SG"`). `body` and `country` are required; `footer`, `values`, and `saved_addresses` are optional.
+## 📚 Documentation
 
-### Location Request
+| Area | What it covers |
+| --- | --- |
+| [**Configuration**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/configuration.md) | Credentials, the client, connection reuse, instrumentation |
+| [**Messages**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/README.md) | Every message kind, one page each, with exact payloads |
+| [**Message Templates**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/message_templates/README.md) | Creating and managing templates: standard, auth, carousel, offers, library |
+| [**Webhooks**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/webhooks/README.md) | Install, verification, signatures, and all 21 notification fields |
+| [**Media**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/media/README.md) | Upload, download, delete, and the token-safety allowlist |
+| [**Subscribed Apps**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/subscribed_app/README.md) | Turning webhook delivery on and off for an account |
+| [**Campaign Schedules**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/schedule/README.md) | Sending an approved template to an audience at a set time |
+| [**Business Phone Numbers**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/README.md) | Onboarding: request code → verify → register |
+| [**Business Account**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/account.md) | Reading and updating the account: name, timezone, review status |
+| [**Business Profile**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/profile.md) | The profile a user sees: about, description, address, vertical, picture |
+| [**Errors**](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/errors.md) | The exception hierarchy and retry strategy |
 
-```ruby
-Whatsapp::Messages.send_location_request!(to: "+15551234567", body: "Can you share your delivery location?")
-```
+Or start at the [documentation index](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/README.md).
 
-Prompts the user to share their current location. `body` is required.
+## 💬 Sending Messages
 
-### Template
+Every registered kind gets its own `Whatsapp::Messages.send_<kind>!` class method.
+Address a recipient by phone number, by BSUID, or both — at least one is required:
 
 ```ruby
-Whatsapp::Messages.send_template!(
-  to: "+15551234567",
-  name: "order_confirmation",
-  language: { code: "en_US" },
-  components: [
-    { type: "body", parameters: [{ type: "text", text: "Jane" }, { type: "text", text: "#1234" }] },
-  ]
-)
+Whatsapp::Messages.send_text!(to: "+15551234567", body: "Hi")                   # phone number
+Whatsapp::Messages.send_text!(recipient: "US.13491208655302741918", body: "Hi") # BSUID
 ```
 
-`name` and `language` are required — `language.code` is validated against `Whatsapp::Utils::LanguageCodes`. `components` is optional and follows the Cloud API's `header`/`body`/`button` component shape, each with typed `parameters` (`text`, `currency`, `date_time`, `image`, `document`, `video`, `location`, or `payload`).
-
-### Interactive
-
-Interactive messages share one class, `Whatsapp::Messages::Interactive`; the `type:` you pass selects which action shape `action:` must match. All variants accept an optional `header:` (`text`, `image`, `video`, or `document`) and `footer:`.
-
-**Reply buttons** — up to 3 quick-reply buttons:
-
 ```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" }] }
-)
-```
-
-**List** — a button that expands into up to 10 sections of up to 10 rows each:
-
-```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" }] },
-    ],
-  }
-)
-```
-
-**CTA URL button** — surfaces a link as a button instead of raw text:
-
-```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" }
-)
-```
-
-**Media carousel** — 2 to 10 swipeable cards, each with its own header/body/CTA/quick-replies:
-
-```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" } }],
-      },
-    ],
-  }
-)
-```
-
-**Product carousel** — 2 to 10 cards referencing products in your Meta catalog:
-
-```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" },
-    ],
-  }
+  action: { buttons: [{ id: "confirm", title: "Confirm" },
+                      { id: "cancel",  title: "Cancel" }] }
 )
 ```
 
-> **Note:** the wire values for the carousel types (`"carousel"` and `"product_list"`) are flagged in the source as worth double-checking against Meta's docs for your specific API version before relying on them in production.
-
-### Mark Message As Read
-
-```ruby
-Whatsapp::Messages.mark_message_as_read!(message_id: "wamid.HBgLMTU1NTU1NTU1NTUV...")
-```
-
-Marks an inbound message — and every earlier message in that conversation — as read, powering the "seen" checkmarks on the user's side. Must be called within 30 days of receipt. Unlike every other kind above, this isn't sent through `Messages.new(kind:, payload:).send!`: there's no recipient or `type` envelope, just `message_id:`, so it has its own dedicated method instead of a `kind:` in the factory.
-
-## Handling Responses
-
-A successful `send!` returns a `Whatsapp::Messages::Response`, built from a payload 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.messages.first.id     # => "wamid.HBgLMTU1NTU1NTU1NTUV..."
-response.contacts.first.wa_id  # => "15551234567"
-```
-
-Sending raises `ActiveModel::ValidationError` if a field fails local validation, `Whatsapp::Messages::PayloadError` if `kind:` is unrecognized (only reachable through the `Messages.new(kind:, payload:).send!` form), and `Whatsapp::RequestError` if the API responds with a non-2xx status.
-
-## Media
-
-```ruby
-media = Whatsapp::Media.new
-
-media_id = media.upload(file_path: "photo.jpg", type: "image/jpeg")
-info     = media.get_url(media_id: media_id)          # => { "url" => ..., ... }
-media.download(url: info["url"], save_to: "photo.jpg") # only HTTPS + allowlisted Meta hosts
-media.delete(media_id: media_id)                       # => true
-```
-
-`download` refuses to attach the API token to a non-HTTPS URL or a host that is not on
-`Configuration#media_host_allowlist`, so a token is never sent to an attacker-influenced URL.
+| Method | Sends |
+| --- | --- |
+| [`send_text!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/text.md) | Plain text with an optional link preview |
+| [`send_image!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/image.md) | An image with an optional caption |
+| [`send_video!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/video.md) | A video with an optional caption |
+| [`send_audio!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/audio.md) | A voice note or audio clip |
+| [`send_document!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/document.md) | A file with an optional caption and filename |
+| [`send_sticker!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/sticker.md) | A sticker |
+| [`send_reaction!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/reaction.md) | An emoji reaction to a previous message |
+| [`send_location!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/location.md) | A latitude/longitude pin |
+| [`send_contacts!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/contacts.md) | A rich, vCard-like contact card |
+| [`send_address!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/address.md) | A delivery-address form (India & Singapore only) |
+| [`send_location_request!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/location_request.md) | A prompt asking the user to share their location |
+| [`send_template!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/template.md) | A pre-approved marketing/utility/authentication template |
+| [`send_interactive!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/interactive.md) | Reply buttons, lists, CTA URLs, or carousels |
+| [`mark_message_as_read!`](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/mark_message_as_read.md) | Closes the read-receipt loop on an inbound message |
+
+Each accepts an optional `client:` and returns a `Whatsapp::Messages::Response` with
+typed `#contacts` and `#messages`. Invalid input raises
+`ActiveModel::ValidationError` before any request is made.
 
-## Managing Templates
+→ **[Sending messages](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/messages/README.md)**
 
-[Sending a template](#template) requires one that already exists and has been approved by
-Meta. `Whatsapp::MessageTemplates` creates and manages those templates, so they can live in
-your codebase and ship from CI instead of being clicked together in WhatsApp Manager.
+## 📋 Managing Templates
 
-This is a different API from sending: it addresses your **WhatsApp Business Account**
-(`waba_id`, not `phone_id`) and needs the `whatsapp_business_management` permission.
+Sending a template requires one that already exists and has been approved by Meta.
+`Whatsapp::MessageTemplates` creates and manages those, so they live in your codebase
+and ship from CI instead of being clicked together in WhatsApp Manager.
 
 ```ruby
-Whatsapp.configure do |config|
-  config.api_key = ENV["WHATSAPP_API_KEY"]
-  config.waba_id = ENV["WHATSAPP_WABA_ID"]
-end
+templates = Whatsapp::MessageTemplates.new   # needs waba_id
 
-templates = Whatsapp::MessageTemplates.new
-```
-
-### Creating
-
-```ruby
 created = templates.create(
-  name: "order_confirmation",           # lowercase alphanumerics and underscores only
-  language: "en_US",
-  category: "UTILITY",                  # UTILITY | MARKETING | AUTHENTICATION
+  name: "order_confirmation", language: "en_US", category: "UTILITY",
   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
-```
-
-Named parameters read better than positional ones for anything non-trivial:
-
-```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" } },
-  ]
-)
 ```
 
 Meta's rules are checked before the request, so a mistake raises immediately instead of
@@ -454,180 +249,119 @@ costing a review cycle:
 templates.create(name: "Order Confirmation", ...)
 # => ActiveModel::ValidationError: Name must contain only lowercase alphanumeric
 #    characters and underscores
-
-templates.create(..., components: [{ type: :body, text: "Hi {{1}} and {{2}}", example: ["Pablo"] }])
-# => ActiveModel::ValidationError: Example does not match the body text:
-#    2 placeholders but 1 example
 ```
 
-### Listing, reading, editing, deleting
+Covers standard, [authentication/OTP](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/message_templates/authentication.md),
+[carousel](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/message_templates/carousel.md),
+[limited-time offer](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/message_templates/limited_time_offer.md), and
+[library](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/message_templates/library.md) templates,
+plus list, find, update, and delete.
 
-```ruby
-page = templates.list(status: %w[APPROVED], fields: %w[name category status], limit: 25)
-page.select(&:approved?).map(&:name)   # Collection is Enumerable
-page.remaining                         # headroom against your account's template cap
-templates.list(after: page.next_cursor) if page.next_cursor
+→ **[Managing templates](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/message_templates/README.md)**
 
-template = templates.find(template_id: "1259544702043867")
-template.status      # => "APPROVED"
-template.editable?   # => true (APPROVED, REJECTED and PAUSED templates can be edited)
+## 🔔 Webhooks
 
-templates.update(template_id: template.id, category: "MARKETING")  # => true
-templates.update(template_id: template.id, components: [...])      # full replacement
+Meta pushes inbound messages, delivery statuses, and 20 other notification types to a
+callback URL you register. Inside a Rails app:
 
-templates.delete(name: "order_confirmation")                       # every language variant
-templates.delete(hsm_id: "1407680676729941", name: "order_confirmation")
-templates.delete(hsm_ids: %w[1387372356726668 1304694804498707])   # up to 100
+```bash
+bundle exec rake whatsapp:install:webhook
 ```
 
-Editing an approved template re-submits it for review but it keeps working meanwhile.
-Approved templates allow 10 edits per 30 days and 1 per 24 hours. Deleting an approved
-template blocks reuse of its name for 30 days.
-
-### Other template kinds
-
-**Authentication (OTP)** templates invert the usual shape — Meta supplies and localises the
-wording, so you pass flags rather than text, and `upsert` creates every language at once:
+That copies a personalizable controller to
+`app/controllers/whatsapp/webhooks_controller.rb` and prints the routes to add:
 
 ```ruby
-templates.upsert(
-  name: "authentication_code", languages: %w[en_US es_ES fr], category: "AUTHENTICATION",
-  components: [
-    { type: :body, add_security_recommendation: true },
-    { type: :footer, code_expiration_minutes: 15 },
-    { type: :buttons, buttons: [{ type: :otp, otp_type: "COPY_CODE" }] },
-  ]
-)
-```
-
-**Marketing carousels** take 2–10 cards that must all share the same structure:
+def receive
+  raw_body = request.body.read
+  return head(:unauthorized) unless Whatsapp::Webhook::Signature.valid?(
+    payload: raw_body, header: request.headers["X-Hub-Signature-256"]
+  )
 
-```ruby
-card = {
-  header: { format: "IMAGE", header_handle: "4::aW..." },
-  body: { text: "Rare {{1}} in stock!", example: ["Tulips"] },
-  buttons: [{ type: :quick_reply, text: "More like this" }],
-}
-
-templates.create(
-  name: "summer_carousel", language: "en_US", category: "MARKETING",
-  components: [
-    { type: :body, text: "Summer is here, {{1}}!", example: ["Pablo"] },
-    { type: :carousel, cards: [card, card] },
-  ]
-)
-```
+  notification = Whatsapp::Webhook::Notification.deserialize(JSON.parse(raw_body))
 
-**Limited-time offers** add a countdown and a coupon code (marketing only; footers are not
-allowed and the body drops to 600 characters):
+  notification.entry.each do |entry|
+    entry.changes.each { |change| WebhookJob.perform_later(change) }
+  end
 
-```ruby
-templates.create(
-  name: "spring_offer", language: "en_US", category: "MARKETING",
-  components: [
-    { type: :header, format: "IMAGE", header_handle: "4::aW..." },
-    { type: :limited_time_offer, text: "Expiring offer!", has_expiration: true },
-    { type: :body, text: "Good news, {{1}}! Use code {{2}} for 25% off.",
-      example: ["Pablo", "SPRING25"] },
-    { type: :buttons, buttons: [
-      { type: :copy_code, example: "SPRING25" },
-      { type: :url, text: "Book now!", url: "https://example.com/o?c={{1}}", example: "n3mtql" },
-    ] },
-  ]
-)
+  head :ok
+end
 ```
 
-**Library templates** are pre-written and pre-approved by Meta, so they usually come back
-`APPROVED` immediately:
+Every notification deserializes into typed objects — no raw hash spelunking:
 
 ```ruby
-templates.create_from_library(
-  name: "my_delivery_update", language: "en_US", category: "UTILITY",
-  library_template_name: "delivery_update_1",
-  library_template_button_inputs: [
-    { type: "URL", url: { base_url: "https://example.com/{{1}}",
-                          url_suffix_example: "https://example.com/order_update" } },
-  ]
-)
-```
-
-### Notes
+message = change.value.messages.first
 
-- **Media headers** take a `header_handle` you already hold. Producing one needs Meta's
-  Resumable Upload API, which this gem does not wrap — note it is a different flow from
-  [`Media#upload`](#media), whose media IDs are for *sending*, not template creation.
-- **Review outcomes arrive by webhook**, not by polling: see
-  `message_template_status_update` and friends under [Webhooks](#webhooks).
-- Text containing `#{{1}}` needs single quotes in Ruby, or `#{` starts interpolation.
+message.from    # => "16505551234"
+message.id      # => "wamid.HBg..."
+message.body    # => "Does it come in another color?"
+```
 
-## Managing Subscribed Apps
+All 21 documented fields get a class. `messages`, `user_id_update`, and
+`business_username_updates`, `user_preferences`, and `history` have a Meta-published schema; the other 16 are best-effort
+and flagged as such, per field.
 
-Before your app receives any [webhook](#webhooks) notifications for a WhatsApp
-Business Account, it needs to be subscribed to it. `Whatsapp::SubscribedApp` wraps the
-`subscribed_apps` edge: one class per action, since — unlike templates — these three
-actions don't share an identity or validation rules to justify one combined class.
+→ **[Webhooks](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/webhooks/README.md)**
+· [inbound messages & statuses](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/webhooks/messages.md)
 
-This addresses your **WhatsApp Business Account** (`waba_id`, not `phone_id`) and needs
-the `whatsapp_business_management` permission, same as [template management](#managing-templates).
+## 📷 Media
 
 ```ruby
-Whatsapp.configure do |config|
-  config.api_key = ENV["WHATSAPP_API_KEY"]
-  config.waba_id = ENV["WHATSAPP_WABA_ID"]
-end
+media = Whatsapp::Media.new
 
-Whatsapp::SubscribedApp::Subscribe.call                         # subscribe this app
-Whatsapp::SubscribedApp::List.call.map(&:name)                  # => ["My App"]
-Whatsapp::SubscribedApp::Unsubscribe.call                       # stop all webhook delivery
+media_id = media.upload(file_path: "photo.jpg", type: "image/jpeg")
+info     = media.get_url(media_id: media_id)
+media.download(url: info["url"], save_to: "photo.jpg")
+media.delete(media_id: media_id)                        # => true
 ```
 
-### Subscribing
+`download` refuses to attach the API token to a non-HTTPS URL or a host that is not on
+`Configuration#media_host_allowlist`, so a token is never sent to an
+attacker-influenced URL. Bodies stream to disk rather than buffering in memory.
 
-```ruby
-result = Whatsapp::SubscribedApp::Subscribe.call
-result.success       # => true
-result.map(&:name)   # => ["My App"] — every app now subscribed, Meta's own echo
-```
+→ **[Media](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/media/README.md)**
+
+## 🔌 Subscribed Apps
 
-Tech Providers routing several WABAs' notifications to different callback URLs pass an
-override instead of relying on the one callback URL configured on the app itself:
+Before your app receives any webhook notifications for a business account, it has to be
+subscribed to it:
 
 ```ruby
-Whatsapp::SubscribedApp::Subscribe.call(
-  override_callback_uri: "https://example.com/webhooks/acme_corp",
-  verify_token: "a-per-account-secret"
-)
+Whatsapp::SubscribedApp::Subscribe.call            # start webhook delivery
+Whatsapp::SubscribedApp::List.call.map(&:name)     # => ["My App"]
+Whatsapp::SubscribedApp::Unsubscribe.call          # stop it
 ```
 
-### Listing
+Tech Providers routing several accounts to different callback URLs pass an
+`override_callback_uri:`.
 
-```ruby
-apps = Whatsapp::SubscribedApp::List.call
-apps.map(&:name)          # Collection is Enumerable
-apps.first.link           # => "https://www.facebook.com/games/?app_id=..."
+→ **[Subscribed apps](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/subscribed_app/README.md)**
 
-Whatsapp::SubscribedApp::List.call(fields: %w[id name])  # restrict the fields returned
-```
+## 📅 Scheduling Campaigns
 
-### Unsubscribing
+Send an approved template to an audience at a set time, and list what is scheduled:
 
 ```ruby
-Whatsapp::SubscribedApp::Unsubscribe.call.success   # => true
+Whatsapp::Schedule::Create.call(
+  hsm_id: "1234567890", audience_id: "2345678901", waba_cs_id: "3456789012",
+  name: "Black Friday", description: "Black Friday promo to VIP customers",
+  delivery_time: Time.now.to_i + 3600
+).id                                                            # => "9876543210"
+
+page = Whatsapp::Schedule::List.call(fields: Whatsapp::Schedule::List::Fields::ALL, limit: 50)
+page.select(&:scheduled?).map(&:name)                           # => ["Black Friday"]
+Whatsapp::Schedule::List.call(after: page.next_cursor) if page.next_cursor
 ```
 
-Stops all webhook deliveries for this WABA immediately.
+Meta's default fields leave out `id`, so ask for it with `fields:` when you need it.
 
-Every action accepts an optional `client:` keyword (defaults to a new
-`Whatsapp::Client` built from `Whatsapp.configuration`), and raises
-`Whatsapp::SubscribedApp::Error` if no `waba_id` is configured or the API rejects the
-request.
+→ **[Campaign schedules](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/schedule/README.md)**
 
-## Registering Business Phone Numbers
+## 📞 Business Phone Numbers
 
-A business phone number is unusable with Cloud API until it is **registered** —
-registration is the prerequisite that makes sending, media, and templates work for that
-number at all. `Whatsapp::BusinessPhoneNumber` wraps all four endpoints in that
-onboarding flow:
+A phone number is unusable with Cloud API until it is **registered** — the prerequisite
+that makes sending, media, and templates work for it at all.
 
 ```
 RequestCode  ->  VerifyCode  ->  Register            (onboarding)
@@ -636,161 +370,132 @@ RequestCode  ->  VerifyCode  ->  Register            (onboarding)
 Deregister                                            (the reverse switch)
 ```
 
-This addresses your **phone number** (`phone_id`, not `waba_id`), like
-[messages](#sending-messages) and [media](#media), and needs the
-`whatsapp_business_messaging` and `whatsapp_business_management` permissions.
-
-```ruby
-Whatsapp.configure do |config|
-  config.api_key  = ENV["WHATSAPP_API_KEY"]
-  config.phone_id = ENV["WHATSAPP_PHONE_ID"]
-end
-
-Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "SMS", language: "en_US")  # send an OTP
-Whatsapp::BusinessPhoneNumber::VerifyCode.call(code: "123456")                         # confirm it
-Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")   # register with your two-step verification PIN
-Whatsapp::BusinessPhoneNumber::Deregister.call                # release the number from Cloud API
-```
-
-### Requesting a verification code
-
 ```ruby
-Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "SMS", language: "en_US").success   # => true
+Whatsapp::BusinessPhoneNumber::RequestCode.call(code_method: "SMS", language: "en_US")
+Whatsapp::BusinessPhoneNumber::VerifyCode.call(code: "123456")
+Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")
+Whatsapp::BusinessPhoneNumber::Deregister.call
 ```
 
-`code_method` must be `"SMS"` or `"VOICE"`; `language` is the locale for the
-verification message (e.g. `"en_US"`). Both are required — an invalid or missing value
-raises `ActiveModel::ValidationError` before any request is made.
+The 6-digit two-step verification PIN and the local-storage region are validated
+client-side — which matters here, because a rejected attempt still counts against a
+rate limit of 10 requests per number per 72-hour window.
 
-### Verifying the code
+The account that number belongs to is readable and writable too — the one part of this
+module that addresses `waba_id` rather than `phone_id`:
 
 ```ruby
-result = Whatsapp::BusinessPhoneNumber::VerifyCode.call(code: "123456")
-result.success   # => true
-result.id        # => the phone number ID, when Meta returns one
-```
+details = Whatsapp::BusinessPhoneNumber::Account::Get.call(fields: %w[name account_review_status])
 
-### Registering
+details.name        # => "Acme Corp"
+details.approved?   # => true
 
-```ruby
-result = Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834")
-result.success   # => true
+Whatsapp::BusinessPhoneNumber::Account::Update.call(name: "Acme Corporation").success  # => true
 ```
 
-`pin` must be exactly 6 digits — the existing two-step verification PIN if one is
-already set, otherwise the PIN to set. An invalid PIN raises
-`ActiveModel::ValidationError` before any request is made.
-
-Pass `data_localization_region` to enable local storage in one of Meta's supported
-regions (`AU ID IN JP SG KR DE CH GB BR BH ZA AE CA`):
+And so is the **business profile** — the card a user sees before they reply. It addresses
+the same `phone_id` as the onboarding actions:
 
 ```ruby
-Whatsapp::BusinessPhoneNumber::Register.call(pin: "212834", data_localization_region: "CH")
-```
+Whatsapp::BusinessPhoneNumber::Profile::Get.call.about
+# => "Open daily 9-5"
 
-### Deregistering
-
-```ruby
-Whatsapp::BusinessPhoneNumber::Deregister.call.success   # => true
+Whatsapp::BusinessPhoneNumber::Profile::Update.call(
+  about: "Open daily 9-6", vertical: "RETAIL", websites: ["https://acme.test"]
+).success
+# => true
 ```
 
-Deregistering makes the number unusable with Cloud API and disables local storage — it
-does **not** delete the number or its message history. A number in use with both Cloud
-API and the WhatsApp Business app cannot be deregistered.
+Character limits, the 21-value vertical enum, and the two-website cap are all checked
+before the request goes out.
 
-Every action accepts an optional `client:` keyword (defaults to a new
-`Whatsapp::Client` built from `Whatsapp.configuration` — pass one with a different
-`phone_id:` to target another number), and raises
-`Whatsapp::BusinessPhoneNumber::Error` if no `phone_id` is configured or the API rejects
-the request.
+The **business username** — the searchable `@name` a user can find you by — is managed on
+the same `phone_id`:
 
-> **Rate limits:** `Register`/`Deregister` are capped at 10 requests per business number
-> in a 72-hour moving window; exceeding it returns error `133016` and blocks the
-> operation for the next 72 hours. `RequestCode`/`VerifyCode` document only "standard
-> Graph API rate limits" plus possible additional throttling, with no published number.
-
-## Webhooks
+```ruby
+Whatsapp::BusinessPhoneNumber::Username::Suggest.call.to_a
+# => ["jaspersmarket", "jaspers_market"]   — names Meta reserved for you
 
-Meta pushes inbound messages, delivery statuses, and ~18 other account/template
-notification types to a callback URL you register. Inside a Rails app:
+Whatsapp::BusinessPhoneNumber::Username::Claim.call(username: "jaspersmarket").reserved?
+# => true, until Meta makes the feature generally available
 
-```bash
-bundle exec rake whatsapp:install:webhook
+Whatsapp::BusinessPhoneNumber::Username::Get.call.approved?  # => false, for now
 ```
 
-This copies a personalizable controller to `app/controllers/whatsapp/webhooks_controller.rb`
-and prints the routes and configuration you still need to add by hand:
+Every one of Meta's format rules is checked locally first, so a name that was never going
+to be accepted doesn't cost you a rate-limited attempt. And Meta's **contact book** — the
+store that keeps putting a username adopter's phone number in your webhooks — can be
+pruned:
 
 ```ruby
-# config/routes.rb
-get  "/whatsapp/webhooks", to: "whatsapp/webhooks#verify"
-post "/whatsapp/webhooks", to: "whatsapp/webhooks#receive"
-
-# config/initializers/whatsapp.rb
-Whatsapp.configure do |config|
-  config.verify_token = Rails.application.credentials.whatsapp_verify_token
-  config.app_secret    = Rails.application.credentials.whatsapp_app_secret
-end
+result = Whatsapp::BusinessPhoneNumber::ContactBook::Delete.call(bsuid: "US.13491208655302741918")
+result.deleted  # => false means there was simply nothing stored, not a failure
 ```
 
-The generated controller is yours to edit — it deserializes every notification into typed
-objects and leaves a `# TODO` where your own handling goes:
-
-```ruby
-class Whatsapp::WebhooksController < ApplicationController
-  def verify
-    challenge = Whatsapp::Webhook::Verification.call(params: params)
-    challenge ? render(plain: challenge) : head(:forbidden)
-  end
+→ **[Business phone numbers](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/README.md)**
+· [the business account](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/account.md)
+· [the business profile](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/profile.md)
+· [business usernames](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/username.md)
+· [the contact book](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/business_phone_number/contact_book.md)
 
-  def receive
-    raw_body = request.body.read
-    return head(:unauthorized) unless Whatsapp::Webhook::Signature.valid?(
-      payload: raw_body, header: request.headers["X-Hub-Signature-256"]
-    )
+## 🚨 Errors
 
-    notification = Whatsapp::Webhook::Notification.deserialize(JSON.parse(raw_body))
-    # notification.entry.each { |entry| entry.changes.each { |change| WebhookJob.perform_later(change) } }
+Everything descends from `Whatsapp::Error`, and each module raises its own subclass so
+you can rescue narrowly:
 
-    head :ok
-  end
-end
-```
-
-`notification.entry.first.changes.first` gives you a `field` (e.g. `"messages"`) and a typed
-`value` — for the `messages` field, `value.messages` and `value.statuses` are arrays of typed
-message/status objects (`Whatsapp::Webhook::Message::Text`, `Whatsapp::Webhook::Status`, etc.).
-The other ~18 documented fields (`account_alerts`, `message_template_status_update`, and so on)
-each deserialize into their own best-effort typed class — see
-[`lib/ruby/whatsapp/webhook/CLAUDE.md`](lib/ruby/whatsapp/webhook/CLAUDE.md) for the full field
-reference and confidence notes, since Meta's docs don't publish a JSON schema for most of them.
+| Class | Raised by |
+| --- | --- |
+| `Whatsapp::RequestError` | A failed message send |
+| `Whatsapp::Messages::PayloadError` | An unknown message kind |
+| `Whatsapp::Media::MediaError` | Anything in `Media` |
+| `Whatsapp::MessageTemplates::TemplateError` | Anything in `MessageTemplates` |
+| `Whatsapp::SubscribedApp::Error` | Anything in `SubscribedApp` |
+| `Whatsapp::Schedule::Error` | Anything in `Schedule` |
+| `Whatsapp::BusinessPhoneNumber::Error` | Anything in `BusinessPhoneNumber`, including `Account` |
 
-**Multi-tenant apps** (many customers, each with their own Meta App) pass `verify_token:`/
-`app_secret:` explicitly instead of relying on the global config default:
+Local validation failures raise `ActiveModel::ValidationError` instead — they happen at
+construction time, before any network call, and carry per-attribute detail:
 
 ```ruby
-account = Account.find_by!(slug: params[:account_slug])
-Whatsapp::Webhook::Verification.call(params:, verify_token: account.verify_token)
-Whatsapp::Webhook::Signature.valid?(payload: raw_body, header:, app_secret: account.app_secret)
+rescue ActiveModel::ValidationError => e
+  e.model.errors.full_messages
+  # => ["Caption is too long (maximum is 1024 characters)"]
 ```
 
-See Meta's [webhook documentation](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview) for the full notification catalog, retry behavior, and signature details.
+→ **[Errors](https://github.com/saleszera/ruby-whatsapp/blob/main/docs/errors.md)**
 
-## Development
+## 🧩 Compatibility
+
+| | |
+| --- | --- |
+| Ruby | >= 3.2 (CI runs 3.2 and 3.4) |
+| Graph API | `v24.0` by default, overridable |
+| Rails | Optional. Webhook controller generator activates when Rails is loaded |
+| Dependencies | `activemodel`, `http`, `logger`, `zeitwerk` |
+
+## 🔨 Development
 
 After checking out the repo, run `bundle install`, then:
 
 ```bash
-bundle exec rake      # run the specs and RuboCop (the default task)
+bundle exec rake      # specs + RuboCop (the default task)
 bundle exec rspec     # specs only
 bundle exec rubocop   # lint only
 bin/console           # interactive prompt
 ```
 
-## Contributing
+## 🤝 Contributing
+
+Bug reports and pull requests are welcome at
+<https://github.com/saleszera/ruby-whatsapp>. Please write the failing spec first —
+this gem is developed test-first — and make sure `bundle exec rake` is green before
+opening a PR.
+
+## 📄 License
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/saleszera/ruby-whatsapp.
+Available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
 
-## License
+---
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+![that's all folks](https://media.giphy.com/media/v1.Y2lkPTc5MGI3NjExaWlsc3ZkcGhiNWlmMXgwZmNhdnAwaWFleDM5YjZlZmRqa2MxcnM0NCZlcD12MV9naWZzX3NlYXJjaCZjdD1n/xUPOqo6E1XvWXwlCyQ/giphy.gif)