flow_chat 0.9.0 → 0.10.0

data/docs/platforms/whatsapp.md

@@ -1,22 +1,23 @@
-# WhatsApp Development Guide
+# WhatsApp
 
-FlowChat provides comprehensive WhatsApp Business API integration with support for rich media, interactive elements, secure webhook validation, and flexible deployment modes.
+The `FlowChat::Whatsapp::Gateway::CloudApi` gateway integrates the WhatsApp Business Cloud API. It handles Meta's webhook verification and signature checks, parses inbound messages (text, interactive replies, media, location, contacts), and renders your flow's output as WhatsApp interactive messages.
 
-## ✨ Key Features
+## Credentials
 
-- **Rich Media Support**: Images, documents, audio, video, and stickers
-- **Interactive Elements**: Buttons (up to 3), lists (up to 10 items per section)
-- **Secure Webhooks**: HMAC-SHA256 signature validation
-- **Multiple Processing Modes**: Inline, background, and simulator
-- **Media Upload & Download**: Direct file upload and media handling
-- **Multi-Tenant Support**: Named configurations for different accounts
-- **Development Tools**: Built-in simulator for testing flows
+The gateway needs an access token, a phone number id, and a verify token; an app secret is needed to validate webhook signatures. Provide them through Rails credentials, environment variables, or a configuration object.
 
-## 🚀 Quick Start
+```yaml
+# config/credentials.yml.enc
+whatsapp:
+  access_token: "..."
+  phone_number_id: "..."
+  verify_token: "..."          # your own value, echoed back during webhook setup
+  app_secret: "..."            # used to verify X-Hub-Signature-256
+```
 
-FlowChat supports two WhatsApp gateway options:
+Equivalent environment variables: `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_VERIFY_TOKEN`, `WHATSAPP_APP_SECRET`, `WHATSAPP_BUSINESS_ACCOUNT_ID`.
 
-### Option 1: Meta Cloud API (Recommended)
+## Setup
 
 ```ruby
 # app/controllers/whatsapp_controller.rb
@@ -29,1367 +30,118 @@ class WhatsappController < ApplicationController
       config.use_session_store FlowChat::Session::CacheSessionStore
     end
 
-    processor.run WelcomeFlow, :main_page
-  rescue => e
-    Rails.logger.error "WhatsApp webhook error: #{e.message}"
-    head :internal_server_error
-  end
-end
-```
-
-### Option 2: Twilio WhatsApp API
-
-```ruby
-# app/controllers/whatsapp_twilio_controller.rb
-class WhatsappTwilioController < ApplicationController
-  skip_forgery_protection
-
-  def webhook
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::Twilio
-      config.use_session_store FlowChat::Session::CacheSessionStore
-    end
-
-    processor.run WelcomeFlow, :main_page
-  rescue => e
-    Rails.logger.error "Twilio WhatsApp webhook error: #{e.message}"
-    head :internal_server_error
+    processor.run RegistrationFlow, :main_page
   end
 end
 ```
 
-### 2. Add Routes
-
 ```ruby
 # config/routes.rb
-post '/whatsapp/webhook', to: 'whatsapp#webhook'            # Meta Cloud API
-post '/whatsapp/twilio/webhook', to: 'whatsapp_twilio#webhook'  # Twilio API
-```
-
-### 3. Create a Flow
-
-```ruby
-# app/flow_chat/welcome_flow.rb
-class WelcomeFlow < FlowChat::Flow
-  def main_page
-    name = app.screen(:name) do |prompt|
-      prompt.ask "Hello! What's your name?",
-        transform: ->(input) { input.strip.titleize }
-    end
-
-    choice = app.screen(:main_menu) do |prompt|
-      prompt.select "Hi #{name}! How can I help?", {
-        "info" => "📋 Get Information",
-        "support" => "🆘 Contact Support",
-        "feedback" => "💬 Give Feedback"
-      }
-    end
-
-    case choice
-    when "info"
-      show_info
-    when "support"
-      contact_support
-    when "feedback"
-      collect_feedback
-    end
-  end
-
-  private
-
-  def show_info
-    app.say "📍 Located at 123 Main Street\n🕒 Hours: Mon-Fri 9AM-6PM"
-  end
-
-  def contact_support
-    app.say "📞 Call us at (555) 123-4567\n📧 Email: support@example.com"
-  end
-
-  def collect_feedback
-    rating = app.screen(:rating) do |prompt|
-      prompt.select "Rate our service:", ["⭐", "⭐⭐", "⭐⭐⭐", "⭐⭐⭐⭐", "⭐⭐⭐⭐⭐"]
-    end
-
-    app.say "Thank you for your #{rating} rating! 🙏"
-  end
-end
-```
-
-## 🔧 Configuration
-
-### Meta Cloud API Configuration
-
-#### Option 1: Rails Credentials (Recommended)
-
-```bash
-rails credentials:edit
-```
-
-```yaml
-whatsapp:
-  access_token: "your_access_token"
-  phone_number_id: "your_phone_number_id"
-  verify_token: "your_verify_token"
-  app_id: "your_app_id"
-  app_secret: "your_app_secret"
-  business_account_id: "your_business_account_id"
-  skip_signature_validation: false  # Set to true only for development
-```
-
-#### Option 2: Environment Variables
-
-```bash
-export WHATSAPP_ACCESS_TOKEN="your_access_token"
-export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"
-export WHATSAPP_VERIFY_TOKEN="your_verify_token"
-export WHATSAPP_APP_ID="your_app_id"
-export WHATSAPP_APP_SECRET="your_app_secret"
-export WHATSAPP_BUSINESS_ACCOUNT_ID="your_business_account_id"
-export WHATSAPP_SKIP_SIGNATURE_VALIDATION="false"
-```
-
-### Twilio WhatsApp Configuration
-
-#### Option 1: Rails Credentials (Recommended)
-
-```bash
-rails credentials:edit
-```
-
-```yaml
-twilio_whatsapp:
-  account_sid: "your_twilio_account_sid"
-  auth_token: "your_twilio_auth_token"
-  phone_number: "+15551234567"  # Your Twilio WhatsApp number
-  skip_signature_validation: false  # Set to true only for development
-```
-
-#### Option 2: Environment Variables
-
-```bash
-export TWILIO_ACCOUNT_SID="your_twilio_account_sid"
-export TWILIO_AUTH_TOKEN="your_twilio_auth_token"
-export TWILIO_WHATSAPP_PHONE_NUMBER="+15551234567"
-export TWILIO_WHATSAPP_SKIP_SIGNATURE_VALIDATION="false"
-```
-
-### Gateway Comparison
-
-| Feature | Meta Cloud API | Twilio |
-|---------|----------------|--------|
-| **Interactive Elements** | Native buttons/lists | Text fallback |
-| **Webhook Format** | JSON | Form-encoded |
-| **Signature Validation** | X-Hub-Signature-256 (SHA256) | X-Twilio-Signature (SHA1) |
-| **Response Format** | JSON | TwiML XML |
-| **Setup Complexity** | Moderate (Meta Business) | Simple (Twilio account) |
-| **Features** | Full WhatsApp features | Basic messaging |
-| **Cost** | Per conversation | Per message |
-
-### Option 3: Programmatic Configuration
-
-```ruby
-# Meta Cloud API
-cloud_config = FlowChat::Whatsapp::Configuration.new(:my_account)
-cloud_config.access_token = "your_access_token"
-cloud_config.phone_number_id = "your_phone_number_id"
-cloud_config.verify_token = "your_verify_token"
-cloud_config.app_secret = "your_app_secret"
-
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, cloud_config
-  config.use_session_store FlowChat::Session::CacheSessionStore
-end
-
-# Twilio WhatsApp
-twilio_config = FlowChat::Whatsapp::TwilioConfiguration.new(:twilio_account)
-twilio_config.account_sid = "your_account_sid"
-twilio_config.auth_token = "your_auth_token"
-twilio_config.phone_number = "+15551234567"
-
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Whatsapp::Gateway::Twilio, twilio_config
-  config.use_session_store FlowChat::Session::CacheSessionStore
-end
-```
-
-## 📱 Interactive Elements
-
-### Buttons (Up to 3)
-
-FlowChat automatically uses buttons for 3 or fewer choices:
-
-```ruby
-def main_menu
-  choice = app.screen(:menu) do |prompt|
-    prompt.select "What would you like to do?", {
-      "balance" => "💰 Check Balance",
-      "transfer" => "📤 Transfer Money", 
-      "history" => "📜 View History"
-    }
-  end
-  
-  handle_choice(choice)
-end
-```
-
-### Lists (4+ Items)
-
-FlowChat automatically uses interactive lists for more than 3 choices:
-
-```ruby
-def product_menu
-  product = app.screen(:products) do |prompt|
-    prompt.select "Choose a product:", {
-      "laptop" => "💻 Laptop - $999",
-      "phone" => "📱 Smartphone - $599", 
-      "tablet" => "📱 Tablet - $399",
-      "watch" => "⌚ Smartwatch - $299",
-      "headphones" => "🎧 Headphones - $199"
-    }
-  end
-  
-  show_product_details(product)
-end
-```
-
-Lists support:
-- Up to 10 items per section
-- Automatic pagination for more items
-- Title truncation (24 chars) with full description (72 chars)
-
-## 🎨 Rich Media Support
-
-### Sending Media in Flows
-
-```ruby
-def product_showcase
-  # Image with prompt
-  feedback = app.screen(:product_feedback) do |prompt|
-    prompt.ask "What do you think of this product?",
-      media: {
-        type: :image,
-        url: "https://example.com/product.jpg"
-      }
-  end
-
-  # Document response
-  app.say "Thanks! Here's the product catalog:",
-    media: {
-      type: :document,
-      url: "https://example.com/catalog.pdf",
-      filename: "product_catalog.pdf"
-    }
-end
-
-def video_tutorial
-  app.say "Watch this tutorial:",
-    media: {
-      type: :video,
-      url: "https://example.com/tutorial.mp4"
-    }
-end
-```
-
-### Media Types Supported
-
-| Type | Usage | Options |
-|------|-------|---------|
-| `:image` | Photos, screenshots | `url`, `caption` |
-| `:document` | PDFs, docs, files | `url`, `caption`, `filename` |
-| `:audio` | Voice messages, music | `url`, `caption` |
-| `:video` | Video files | `url`, `caption` |
-| `:sticker` | Stickers/animated | `url` (no caption) |
-
-### Buttons with Media Headers
-
-```ruby
-def media_menu
-  choice = app.screen(:options) do |prompt|
-    prompt.select "Choose an option:", 
-      {
-        "details" => "📋 More Details",
-        "buy" => "🛒 Buy Now",
-        "share" => "📤 Share"
-      },
-      media: {
-        type: :image,
-        url: "https://example.com/product.jpg"
-      }
-  end
-end
-```
-
-### Handling Incoming Media
-
-```ruby
-def handle_media_upload
-  if app.media
-    media_type = app.media["type"]
-    media_id = app.media["id"]
-    
-    case media_type
-    when "image"
-      app.say "Thanks for the image! Processing..."
-      process_image(media_id)
-    when "document"
-      app.say "Document received. Reviewing..."
-      process_document(media_id)
-    when "audio"
-      app.say "Got your voice message!"
-      process_audio(media_id)
-    end
-  else
-    app.say "Please send a photo of your receipt."
-  end
-end
-```
-
-## 📤 WhatsApp Client API
-
-The `FlowChat::Whatsapp::Client` provides a comprehensive API for sending messages outside of flows and integrating with other systems.
-
-### Client Initialization
-
-```ruby
-# From credentials/environment variables
-config = FlowChat::Whatsapp::Configuration.from_credentials
-client = FlowChat::Whatsapp::Client.new(config)
-
-# Using named configuration
-config = FlowChat::Whatsapp::Configuration.get(:my_account)
-client = FlowChat::Whatsapp::Client.new(config)
-```
-
-### Text Messages
-
-```ruby
-# Simple text message
-client.send_text("+1234567890", "Hello! How can I help you today?")
-```
-
-### Interactive Messages
-
-```ruby
-# Interactive buttons (up to 3)
-buttons = [
-  {id: "option1", title: "View Orders"},
-  {id: "option2", title: "Track Package"},
-  {id: "option3", title: "Contact Support"}
-]
-client.send_buttons("+1234567890", "What would you like to do?", buttons)
-
-# Interactive lists (4+ options)
-sections = [
-  {
-    title: "Products",
-    rows: [
-      {id: "laptop", title: "💻 Laptop", description: "High-performance laptop - $999"},
-      {id: "phone", title: "📱 Smartphone", description: "Latest model smartphone - $599"},
-      {id: "tablet", title: "📱 Tablet", description: "10-inch tablet - $399"}
-    ]
-  },
-  {
-    title: "Accessories", 
-    rows: [
-      {id: "headphones", title: "🎧 Headphones", description: "Wireless headphones - $199"},
-      {id: "case", title: "📱 Phone Case", description: "Protective case - $29"}
-    ]
-  }
-]
-client.send_list("+1234567890", "Choose a product:", sections, "Browse")
-```
-
-### Media Messages
-
-```ruby
-# Send image
-client.send_image("+1234567890", "https://example.com/image.jpg", "Check out our new product!")
-
-# Send document  
-client.send_document(
-  "+1234567890",
-  "https://example.com/catalog.pdf", 
-  "Here's our product catalog",
-  "catalog.pdf"  # optional filename
-)
-
-# Send video
-client.send_video("+1234567890", "https://example.com/tutorial.mp4", "Watch this tutorial")
-
-# Send audio
-client.send_audio("+1234567890", "https://example.com/message.mp3")
-
-# Send sticker (no caption support)
-client.send_sticker("+1234567890", "https://example.com/sticker.webp")
-```
-
-### Media Upload & Download
-
-```ruby
-# Upload local file and get media ID
-media_id = client.upload_media("/path/to/file.pdf", "application/pdf", "document.pdf")
-
-# Upload from IO object
-File.open("/path/to/image.jpg", "rb") do |file|
-  media_id = client.upload_media(file, "image/jpeg", "photo.jpg")
-end
-
-# Use uploaded media ID in messages
-client.send_document("+1234567890", media_id, "Here's your document")
-
-# Get media URL from ID
-media_url = client.get_media_url(media_id)
-
-# Download media content
-media_content = client.download_media(media_id)
-File.write("/tmp/downloaded_file", media_content, mode: "wb")
-```
-
-### Template Messages
-
-```ruby
-# Send template message (for conversation initiation)
-components = [
-  {
-    type: "body",
-    parameters: [
-      {type: "text", text: "John Doe"},
-      {type: "text", text: "ORD-12345"}
-    ]
-  }
-]
-
-client.send_template(
-  "+1234567890",
-  "order_confirmation",
-  components,
-  "en_US"
-)
+match "/whatsapp/webhook", to: "whatsapp#webhook", via: [:get, :post]
 ```
 
-### Read Receipts & Typing Indicator
-
-Mark an inbound message as read and optionally show a typing indicator while your application processes a slow request (LLM call, lookup, etc.). WhatsApp Cloud API ties the typing indicator to the mark-as-read call — there is no separate typing endpoint.
-
-```ruby
-client = FlowChat::Whatsapp::Client.new(config)
-
-# Just mark as read
-client.mark_as_read("wamid.ABC123")
-
-# Mark as read AND show "typing…" in the user's chat
-client.mark_as_read("wamid.ABC123", typing: true)
-
-# Convenience equivalent of the line above
-client.indicate_typing("wamid.ABC123")
-```
+Both verbs are needed: Meta sends a `GET` with `hub.mode=subscribe` to verify the endpoint (the gateway answers it using your `verify_token`), and `POST`s the actual messages. Each `POST` is checked against `X-Hub-Signature-256` using the app secret; a request with a bad signature is answered `200 OK` without processing, so Meta stops retrying it.
 
-The typing indicator auto-dismisses on the next outbound message or after ~25 seconds. There is **no stop-typing call** — send the real reply and the indicator clears.
+With no second argument, `use_gateway` loads credentials through `FlowChat::Whatsapp::Configuration.from_credentials`, which reads the Rails credentials or environment variables above. That is the setup shown here.
 
-`message_id` must be the id of an inbound user message; you cannot show a typing indicator without an associated inbound message.
+## Explicit and multi-tenant configuration
 
-### Complete Service Example
+To run more than one WhatsApp number, or to load credentials from somewhere other than Rails credentials, build a `FlowChat::Whatsapp::Configuration` and pass it as the second argument to `use_gateway`.
 
 ```ruby
-# Service for sending notifications
-class WhatsappNotificationService
-  def initialize(config_name = :default)
-    @config = FlowChat::Whatsapp::Configuration.get(config_name)
-    @client = FlowChat::Whatsapp::Client.new(@config)
-  end
-
-  def send_order_confirmation(phone_number, order_id)
-    # Send confirmation message
-    @client.send_text(phone_number, "Order ##{order_id} confirmed! 🛍️")
-    
-    # Send invoice document
-    @client.send_document(
-      phone_number,
-      "https://storage.example.com/invoices/#{order_id}.pdf",
-      "Your invoice is ready",
-      "invoice_#{order_id}.pdf"
-    )
-    
-    # Send interactive buttons
-    @client.send_buttons(phone_number, "What would you like to do next?", [
-      {id: "track", title: "Track Order"},
-      {id: "support", title: "Contact Support"}, 
-      {id: "invoice", title: "View Invoice"}
-    ])
-  end
-
-  def send_media_gallery(phone_number, images)
-    images.each_with_index do |image_url, index|
-      @client.send_image(phone_number, image_url, "Image #{index + 1}")
-    end
-  end
-
-  def send_welcome_message(phone_number, user_name)
-    # Upload and send personalized image
-    File.open("welcome_images/#{user_name.downcase}.jpg", "rb") do |file|
-      media_id = @client.upload_media(file, "image/jpeg", "welcome.jpg")
-      @client.send_image(phone_number, media_id, "Welcome #{user_name}! 🎉")
-    end
-  end
+config = FlowChat::Whatsapp::Configuration.new(:support).tap do |c|
+  c.access_token = tenant.whatsapp_access_token
+  c.phone_number_id = tenant.whatsapp_phone_number_id
+  c.verify_token = tenant.whatsapp_verify_token
+  c.app_secret = tenant.whatsapp_app_secret
 end
 
-# Usage in controllers or background jobs
-service = WhatsappNotificationService.new(:main_account)
-service.send_order_confirmation("+1234567890", "ORD-123")
-```
-
-## 🏗️ Template Manager
-
-The `FlowChat::Whatsapp::TemplateManager` provides utilities for managing WhatsApp message templates, which are required for initiating conversations with users.
-
-### Template Manager Setup
-
-```ruby
-# Using default configuration
-template_manager = FlowChat::Whatsapp::TemplateManager.new
-
-# Using specific configuration
-config = FlowChat::Whatsapp::Configuration.get(:my_account)
-template_manager = FlowChat::Whatsapp::TemplateManager.new(config)
-```
-
-### Sending Template Messages
-
-```ruby
-# Basic template message
-template_manager.send_template(
-  to: "+1234567890",
-  template_name: "hello_world",
-  language: "en_US",
-  components: []
-)
-
-# Template with parameters
-components = [
-  {
-    type: "body",
-    parameters: [
-      {type: "text", text: "John Doe"},
-      {type: "text", text: "Order #12345"}
-    ]
-  }
-]
-
-template_manager.send_template(
-  to: "+1234567890", 
-  template_name: "order_update",
-  language: "en_US",
-  components: components
-)
-```
-
-### Pre-built Template Methods
-
-```ruby
-# Send welcome template (uses Meta's default hello_world template)
-template_manager.send_welcome_template(
-  to: "+1234567890",
-  name: "John Doe"  # Optional personalization
-)
-
-# Send notification template
-template_manager.send_notification_template(
-  to: "+1234567890",
-  message: "Your order has shipped! Track it with the link below.",
-  button_text: "Track Package"  # Optional quick reply button
-)
-```
-
-### Template Management
-
-```ruby
-# Create a new template (requires Meta approval)
-template_manager.create_template(
-  name: "order_confirmation",
-  category: "UTILITY",  # AUTHENTICATION, MARKETING, UTILITY
-  language: "en_US",
-  components: [
-    {
-      type: "HEADER",
-      format: "TEXT",
-      text: "Order Confirmed"
-    },
-    {
-      type: "BODY", 
-      text: "Hi {{1}}, your order {{2}} has been confirmed and will arrive by {{3}}."
-    },
-    {
-      type: "FOOTER",
-      text: "Thank you for shopping with us!"
-    },
-    {
-      type: "BUTTONS",
-      buttons: [
-        {
-          type: "QUICK_REPLY",
-          text: "Track Order"
-        },
-        {
-          type: "QUICK_REPLY", 
-          text: "Cancel Order"
-        }
-      ]
-    }
-  ]
-)
-
-# List all templates
-templates = template_manager.list_templates
-templates["data"].each do |template|
-  puts "Template: #{template["name"]} - Status: #{template["status"]}"
+processor = FlowChat::Processor.new(self) do |cfg|
+  cfg.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, config
+  cfg.use_session_store FlowChat::Session::CacheSessionStore
 end
-
-# Check template status
-status = template_manager.template_status("template_id_here")
-puts "Template status: #{status["status"]}"  # PENDING, APPROVED, REJECTED
 ```
 
-### Template Categories
-
-- **AUTHENTICATION**: One-time passwords, account verification
-- **MARKETING**: Promotional messages, newsletters (requires opt-in)
-- **UTILITY**: Order updates, appointment reminders, account notifications
+Passing a name to `new` registers the configuration under that name, so you can retrieve it later with `FlowChat::Whatsapp::Configuration.get(:support)`. For an unnamed configuration, use `FlowChat::Whatsapp::Configuration.new(nil)`. The configuration attributes are `access_token`, `phone_number_id`, `verify_token`, `app_secret`, `business_account_id`, and `skip_signature_validation` (set it to `true` to bypass the `X-Hub-Signature-256` check, for local testing only).
 
-### Template Components
+## The flow is the same
 
 ```ruby
-# Complete template structure example
-components = [
-  # Header (optional)
-  {
-    type: "HEADER",
-    format: "TEXT",  # or IMAGE, VIDEO, DOCUMENT
-    text: "Your Receipt"
-  },
-  
-  # Body (required)
-  {
-    type: "BODY",
-    text: "Hi {{1}}, here's your receipt for order {{2}} totaling {{3}}."
-  },
-  
-  # Footer (optional)
-  {
-    type: "FOOTER", 
-    text: "Questions? Reply to this message."
-  },
-  
-  # Buttons (optional)
-  {
-    type: "BUTTONS",
-    buttons: [
-      {
-        type: "QUICK_REPLY",
-        text: "Download PDF"
-      },
-      {
-        type: "URL",
-        text: "View Online",
-        url: "https://example.com/receipt/{{1}}"
-      },
-      {
-        type: "PHONE_NUMBER",
-        text: "Call Support",
-        phone_number: "+1234567890"
-      }
-    ]
-  }
-]
-```
-
-### Integration with Services
-
-```ruby
-class OrderNotificationService
-  def initialize
-    @template_manager = FlowChat::Whatsapp::TemplateManager.new
-  end
-
-  def notify_order_confirmed(order)
-    @template_manager.send_template(
-      to: order.customer_phone,
-      template_name: "order_confirmation",
-      language: order.customer_locale || "en_US",
-      components: [
-        {
-          type: "body",
-          parameters: [
-            {type: "text", text: order.customer_name},
-            {type: "text", text: order.id},
-            {type: "text", text: order.estimated_delivery.strftime("%B %d")}
-          ]
-        }
-      ]
-    )
-  end
-
-  def notify_order_shipped(order)
-    @template_manager.send_notification_template(
-      to: order.customer_phone,
-      message: "Great news! Order #{order.id} has shipped and is on its way.",
-      button_text: "Track Package"
-    )
-  end
-end
-```
-
-## 📁 Media Upload & Download
-
-### Uploading Files
-
-```ruby
-# Upload local file
-client = FlowChat::Whatsapp::Client.new(config)
-media_id = client.upload_media("/path/to/file.pdf", "application/pdf", "document.pdf")
-
-# Upload from IO
-File.open("/path/to/image.jpg", "rb") do |file|
-  media_id = client.upload_media(file, "image/jpeg", "photo.jpg")
-end
-
-# Use uploaded media ID
-client.send_document("+1234567890", media_id, "Here's your document")
-```
-
-### Downloading Media
-
-```ruby
-# Get media URL from ID
-media_url = client.get_media_url(media_id)
-
-# Download media content
-media_content = client.download_media(media_id)
-
-# Save to file
-File.write("/tmp/downloaded_media", media_content, mode: "wb")
-```
-
-## ⚙️ Processing Modes
-
-FlowChat supports three distinct message processing modes to handle different deployment scenarios and performance requirements. Configure the mode in your initializer:
-
-```ruby
-# config/initializers/flowchat.rb
-FlowChat::Config.whatsapp.message_handling_mode = :inline  # Default
-```
-
-### Mode Comparison
-
-| Feature | Inline | Background | Simulator |
-|---------|--------|------------|-----------|
-| **Response Speed** | Immediate | Async (queued) | Immediate |
-| **Webhook Timeout Risk** | High | None | None |
-| **Scalability** | Limited | High | N/A (testing only) |
-| **Setup Complexity** | Simple | Moderate | Simple |
-| **Production Ready** | Yes | Yes | No (development only) |
-| **Debugging** | Easy | Moderate | Easy |
-| **Message Delivery** | Real WhatsApp | Real WhatsApp | Simulated |
-
-### Inline Mode (Default)
-
-Messages are processed synchronously:
-
-```ruby
-FlowChat::Config.whatsapp.message_handling_mode = :inline
-```
-
-**Pros**: Simple, immediate responses  
-**Cons**: Webhook timeouts for slow operations
-
-### Simulator Mode
-
-Returns response data instead of sending via WhatsApp API, perfect for development and testing:
-
-```ruby
-FlowChat::Config.whatsapp.message_handling_mode = :simulator
-```
-
-#### Simulator Features
-
-- **No API calls**: Messages are not sent to WhatsApp
-- **Response inspection**: Returns full message payload in HTTP response
-- **Flow debugging**: Test conversation flows without real phone numbers
-- **No webhook validation**: Bypasses signature validation for easier testing
-- **Fast iteration**: Immediate feedback without waiting for WhatsApp delivery
-
-#### Simulator Response Format
-
-Instead of sending to WhatsApp, the simulator returns JSON with the message payload:
-
-```json
-{
-  "mode": "simulator",
-  "message_sent": true,
-  "response_data": {
-    "messaging_product": "whatsapp",
-    "to": "+1234567890",
-    "type": "interactive",
-    "interactive": {
-      "type": "button",
-      "body": {"text": "What would you like to do?"},
-      "action": {
-        "buttons": [
-          {"type": "reply", "reply": {"id": "option1", "title": "View Orders"}},
-          {"type": "reply", "reply": {"id": "option2", "title": "Track Package"}}
-        ]
-      }
-    }
-  },
-  "config_used": "default",
-  "timestamp": "2024-01-15T10:30:00Z"
-}
-```
-
-#### Using Simulator in Development
-
-```ruby
-# Enable simulator conditionally
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-  config.use_session_store FlowChat::Session::CacheSessionStore
-end
-
-# Set mode globally in development
-FlowChat::Config.whatsapp.message_handling_mode = Rails.env.development? ? :simulator : :inline
-
-# Or enable per-request (useful for testing)
-# Add ?simulator=true to webhook URL for one-off testing
-```
-
-#### Testing with Simulator
-
-```ruby
-# test/integration/whatsapp_simulator_test.rb
-class WhatsappSimulatorTest < ActionDispatch::IntegrationTest
-  def setup
-    # Force simulator mode for tests
-    @original_mode = FlowChat::Config.whatsapp.message_handling_mode
-    FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  end
-
-  def teardown
-    FlowChat::Config.whatsapp.message_handling_mode = @original_mode
-  end
-
-  def test_welcome_flow_buttons
-    # Simulate WhatsApp webhook
-    webhook_data = {
-      entry: [{
-        changes: [{
-          value: {
-            messages: [{
-              from: "1234567890",
-              id: "msg_123",
-              type: "text",
-              text: { body: "hello" }
-            }],
-            contacts: [{
-              profile: { name: "Test User" }
-            }]
-          }
-        }]
-      }]
-    }
-
-    post "/whatsapp/webhook", params: webhook_data
-
-    assert_response :success
-    response_json = JSON.parse(response.body)
-    
-    assert_equal "simulator", response_json["mode"]
-    assert_equal "interactive", response_json["response_data"]["type"]
-    assert response_json["response_data"]["interactive"]["action"]["buttons"].present?
-  end
-end
-```
-
-**Pros**: Perfect for testing, fast development, no API costs, detailed response inspection  
-**Cons**: Messages aren't actually sent, doesn't test real WhatsApp behavior
-
-## 🔒 Security & Validation
-
-### Webhook Signature Validation
-
-FlowChat automatically validates WhatsApp webhook signatures using HMAC-SHA256 to ensure requests are genuinely from WhatsApp and haven't been tampered with.
-
-#### How Signature Validation Works
-
-```ruby
-# 1. Extract signature from X-Hub-Signature-256 header
-# 2. Calculate HMAC-SHA256 hash of request body using app_secret
-# 3. Compare calculated signature with provided signature using secure comparison
-# 4. Reject request if signatures don't match
-```
-
-#### Production Configuration (Required)
-
-```ruby
-# config/credentials/production.yml
-whatsapp:
-  app_secret: "your_whatsapp_app_secret_from_meta"
-  # ... other settings
-
-# The gateway automatically validates signatures
-processor = FlowChat::Processor.new(self) do |config|
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-  # Signature validation is enabled by default
-end
-```
-
-#### Development Configuration Options
-
-```ruby
-# Option 1: Use real app_secret (recommended for staging)
-config = FlowChat::Whatsapp::Configuration.new
-config.app_secret = "your_whatsapp_app_secret"
-config.skip_signature_validation = false  # Default behavior
-
-# Option 2: Explicitly disable validation (development only)
-config = FlowChat::Whatsapp::Configuration.new
-config.app_secret = nil  # Not required when disabled
-config.skip_signature_validation = true  # Must be explicitly set to true
-
-# Option 3: Environment-based configuration
-config = FlowChat::Whatsapp::Configuration.new
-config.app_secret = Rails.env.production? ? "real_secret" : nil
-config.skip_signature_validation = !Rails.env.production?
-```
-
-#### Configuration Error Handling
-
-The gateway will raise `FlowChat::Whatsapp::ConfigurationError` if:
-
-```ruby
-# Missing app_secret with validation enabled (default)
-# Error: "WhatsApp app_secret is required for webhook signature validation"
-
-# Invalid webhook signature received
-# Returns HTTP 401 Unauthorized
-
-# Valid configuration examples:
-config.app_secret = "secret"; config.skip_signature_validation = false  # ✅ Secure
-config.app_secret = nil; config.skip_signature_validation = true        # ✅ Explicitly disabled
-config.app_secret = "secret"; config.skip_signature_validation = true   # ✅ Secret provided but validation disabled
-
-# Invalid configuration:  
-config.app_secret = nil; config.skip_signature_validation = false       # ❌ Error
-```
-
-#### Security Implementation Details
-
-```ruby
-# The gateway uses secure comparison to prevent timing attacks
-def valid_webhook_signature?(request)
-  # Extract signature from X-Hub-Signature-256 header
-  signature_header = request.headers["X-Hub-Signature-256"]
-  expected_signature = signature_header.sub("sha256=", "")
-  
-  # Calculate HMAC-SHA256 of request body
-  body = request.body.read
-  calculated_signature = OpenSSL::HMAC.hexdigest(
-    OpenSSL::Digest.new("SHA256"), 
-    @config.app_secret, 
-    body
-  )
-  
-  # Use secure comparison to prevent timing attacks
-  ActiveSupport::SecurityUtils.secure_compare(expected_signature, calculated_signature)
-end
-```
-
-⚠️ **Security Warning**: Never disable signature validation in production environments.
-
-### Error Handling
-
-```ruby
-def webhook
-  processor = FlowChat::Processor.new(self) do |config|
-    config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-    config.use_session_store FlowChat::Session::CacheSessionStore
-  end
-
-  processor.run WelcomeFlow, :main_page
-rescue FlowChat::Whatsapp::ConfigurationError => e
-  Rails.logger.error "WhatsApp configuration error: #{e.message}"
-  head :internal_server_error
-rescue => e
-  Rails.logger.error "WhatsApp webhook error: #{e.message}"
-  head :internal_server_error
-end
-```
-
-### Configuration Validation
-
-FlowChat will raise a `ConfigurationError` if:
-- `app_secret` is missing and validation is not explicitly disabled
-- Required credentials are missing
-- Invalid webhook signatures are received
-
-## 🏢 Multi-Tenant Support
-
-### Named Configurations
-
-Register configurations by name for different accounts:
-
-```ruby
-# config/initializers/whatsapp_configs.rb
-tenant_a_config = FlowChat::Whatsapp::Configuration.new(:tenant_a)
-tenant_a_config.access_token = "tenant_a_token"
-tenant_a_config.phone_number_id = "tenant_a_phone"
-tenant_a_config.verify_token = "tenant_a_verify"
-tenant_a_config.app_secret = "tenant_a_secret"
-
-tenant_b_config = FlowChat::Whatsapp::Configuration.new(:tenant_b)
-tenant_b_config.access_token = "tenant_b_token"
-tenant_b_config.phone_number_id = "tenant_b_phone"
-tenant_b_config.verify_token = "tenant_b_verify"
-tenant_b_config.app_secret = "tenant_b_secret"
-```
-
-### Configuration API
-
-The configuration system provides several methods for managing named configurations:
-
-```ruby
-# Check if a configuration exists
-FlowChat::Whatsapp::Configuration.exists?(:tenant_a)  # => true/false
-
-# Get configuration by name (raises error if not found)
-config = FlowChat::Whatsapp::Configuration.get(:tenant_a)
-
-# Get configuration with fallback
-config = FlowChat::Whatsapp::Configuration.get(:tenant_a) rescue FlowChat::Whatsapp::Configuration.from_credentials
-
-# Register configuration programmatically
-config = FlowChat::Whatsapp::Configuration.new(:dynamic_tenant)
-config.access_token = "token_here"
-config.phone_number_id = "phone_id_here"
-# ... other settings
-```
-
-### Using Named Configurations
+class RegistrationFlow < FlowChat::Flow
+  def main_page
+    name = app.screen(:name) { |prompt| prompt.ask "What's your name?" }
 
-```ruby
-class MultiTenantWhatsappController < ApplicationController
-  def webhook
-    tenant = determine_tenant(request)
-    
-    # Verify configuration exists
-    unless FlowChat::Whatsapp::Configuration.exists?(tenant)
-      Rails.logger.error "No WhatsApp configuration found for tenant: #{tenant}"
-      head :not_found
-      return
-    end
-    
-    whatsapp_config = FlowChat::Whatsapp::Configuration.get(tenant)
-    
-    processor = FlowChat::Processor.new(self) do |config|
-      config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi, whatsapp_config
-      config.use_session_store FlowChat::Session::CacheSessionStore
-      # Use tenant-specific session boundaries
-      config.use_session_config(
-        boundaries: [:flow, :platform, :tenant],
-        identifier: :msisdn,
-        tenant: tenant
-      )
+    email = app.screen(:email) do |prompt|
+      prompt.ask "Your email?", validate: ->(input) { "Invalid email" unless input.include?("@") }
     end
 
-    processor.run WelcomeFlow, :main_page
-  end
-
-  private
-
-  def determine_tenant(request)
-    # Multiple strategies for tenant detection
-    if request.subdomain.present?
-      request.subdomain.to_sym
-    elsif request.path.start_with?('/api/')
-      # Extract from API path: /api/v1/tenants/acme/whatsapp
-      request.path.split('/')[4]&.to_sym
-    elsif request.headers['X-Tenant-ID'].present?
-      request.headers['X-Tenant-ID'].to_sym
-    else
-      :default
-    end
+    app.say "Welcome #{name}!"
   end
 end
 ```
 
-### Background Jobs with Multi-Tenancy
+## How choices render
 
-```ruby
-class WhatsappMessageJob < ApplicationJob
-  include FlowChat::Whatsapp::SendJobSupport
+FlowChat picks the WhatsApp interactive type from the number of choices:
 
-  # SendJobSupport automatically handles configuration resolution
-  # It will use send_data[:config_name] if provided, otherwise fallback to default
+- 3 choices or fewer render as reply buttons.
+- 4 to 10 render as a list.
+- Above 10 there is no interactive surface left: the options go straight into the message body, one per line, numbered.
 
-  def on_whatsapp_send_success(send_data, result)
-    # Log with tenant context
-    tenant = send_data[:config_name] || :default
-    Rails.logger.info "Message sent for tenant #{tenant}: #{result["messages"]&.first&.dig("id")}"
-  end
-end
-```
+Button and list row titles are only numbered when they need to be. FlowChat truncates each title to fit (20 characters for a button, 24 for a list row) and checks the whole set: if any title had to be truncated, or if two choices land on the same title, the titles as displayed can no longer identify a choice on their own. When that happens, every title in the set gets prefixed with its 1-based position ("1. ", "2. ", and so on), not just the ones that collided, so a stray "2." never appears next to a title with no "1." beside it. A short menu of distinct options (`Yes` / `No`) stays unprefixed; a menu with a long label, or with two choices sharing a label (two accounts both named "Savings"), gets every title numbered (`1. Yes` / `2. No`, `1. Transfer to savin...` / `2. Transfer to salar...`).
 
-### Dynamic Configuration Management
+A user can reply by tapping, by typing the title exactly as shown, or - only when the screen was numbered - by typing the number. All of these resolve to the same choice key, so your flow reads `select` results the same way regardless of which one the user did. Above 10 choices, where nothing is tappable, the options go straight into the message body, one per line, always numbered, and a typed number is the only way to reply.
 
-```ruby
-class TenantConfigurationService
-  def self.setup_tenant(tenant_name, credentials)
-    config = FlowChat::Whatsapp::Configuration.new(tenant_name)
-    config.access_token = credentials[:access_token]
-    config.phone_number_id = credentials[:phone_number_id] 
-    config.verify_token = credentials[:verify_token]
-    config.app_secret = credentials[:app_secret]
-    config.business_account_id = credentials[:business_account_id]
-    
-    # Validate configuration before registering
-    unless config.valid?
-      raise "Invalid WhatsApp configuration for tenant: #{tenant_name}"
-    end
-    
-    Rails.logger.info "WhatsApp configuration registered for tenant: #{tenant_name}"
-  end
+## Media
 
-  def self.remove_tenant(tenant_name)
-    # Note: The current implementation doesn't provide a removal method
-    # This would need to be added to the Configuration class
-    Rails.logger.info "TODO: Remove configuration for tenant: #{tenant_name}"
-  end
-end
-
-# Usage in tenant onboarding
-TenantConfigurationService.setup_tenant(:new_client, {
-  access_token: "EAAxxxxxxxxx",
-  phone_number_id: "1234567890",
-  verify_token: "my_verify_token",
-  app_secret: "app_secret_here",
-  business_account_id: "business_account_id"
-})
-```
-
-## 🧪 Testing & Development
-
-### Simulator Mode
-
-Enable the simulator for testing during development:
+Read inbound media through `app.media`, an Array of `FlowChat::Media`:
 
 ```ruby
-# Enable simulator in development
-processor = FlowChat::Processor.new(self, enable_simulator: Rails.env.development?) do |config|
-  config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
-  config.use_session_store FlowChat::Session::CacheSessionStore  
+photo = app.media.first
+if photo
+  photo.type       # => :image
+  photo.mime_type  # => "image/jpeg"
+  bytes = photo.download
 end
 ```
 
-The simulator provides:
-- Web interface for testing flows
-- No actual WhatsApp API calls
-- Response data returned in HTTP response
-- Secure cookie-based authentication
-
-### Testing Flows
+Send media outbound by passing `media:` to `ask` or `say`:
 
 ```ruby
-# test/flow_chat/welcome_flow_test.rb
-require 'test_helper'
-
-class WelcomeFlowTest < ActiveSupport::TestCase
-  include FlowChat::TestHelpers
-
-  def test_main_page_flow
-    # Simulate WhatsApp input
-    session = create_test_session
-    app = create_test_app(session: session)
-    flow = WelcomeFlow.new(app)
-
-    # Test the flow
-    simulate_input(app, "John")
-    simulate_input(app, "info")
-    
-    response = flow.main_page
-    
-    assert_includes response.last, "Located at 123 Main Street"
-  end
-end
+app.say "Your receipt", media: { type: :document, url: "https://example.com/receipt.pdf" }
 ```
 
-## 📊 Instrumentation & Monitoring
+The WhatsApp client also exposes direct senders (`send_image`, `send_document`, `send_audio`, `send_video`, `send_sticker`, `send_template`) and `upload_media`, which uploads a file and returns a media id you can reuse.
 
-FlowChat includes built-in instrumentation for WhatsApp events:
+Media and choices combine, but media never changes which choice surface renders. 3 choices or fewer is the one case WhatsApp can carry both in a single message: the media becomes the header on the reply buttons.
 
 ```ruby
-# Events automatically tracked:
-# - FlowChat::Events::MESSAGE_RECEIVED
-# - FlowChat::Events::MESSAGE_SENT  
-# - FlowChat::Events::MEDIA_UPLOAD
-# - FlowChat::Events::WEBHOOK_VERIFIED
-# - FlowChat::Events::WEBHOOK_FAILED
-
-# Custom instrumentation
-FlowChat.instrument("custom.whatsapp.event", {
-  user_id: app.user_id,
-  action: "custom_action",
-  metadata: { key: "value" }
-})
-```
-
-## 🚨 Troubleshooting
-
-### Common Issues
-
-**1. Configuration Error: app_secret required**
-```
-WhatsApp app_secret is required for webhook signature validation.
-```
-**Solution**: Configure `WHATSAPP_APP_SECRET` or disable validation explicitly.
-
-**2. Invalid webhook signature**
-```
-Invalid webhook signature received
-```
-**Solution**: Verify your `app_secret` matches your WhatsApp app configuration.
-
-**3. Media upload fails**
-```
-Media upload failed: Invalid mime type
-```
-**Solution**: Ensure MIME type is correctly specified and supported.
-
-**4. Background job class not found**
-```
-Background mode requested but no WhatsappMessageJob found
-```
-**Solution**: Create the background job class or use inline mode.
-
-### Debug Mode
-
-Enable debug logging:
-
-```ruby
-# config/environments/development.rb
-config.log_level = :debug
-
-# This will log:
-# - Webhook signature validation
-# - Message parsing and extraction
-# - API request/response details
-# - Configuration loading
-```
-
-### Environment-Specific Configuration
-
-```ruby
-# config/initializers/flowchat.rb
-case Rails.env
-when 'development'
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  # Skip signature validation for easier testing
-  
-when 'test'
-  FlowChat::Config.whatsapp.message_handling_mode = :simulator
-  
-when 'staging'
-  FlowChat::Config.whatsapp.message_handling_mode = :inline
-  # Full security validation
-  
-when 'production'
-  FlowChat::Config.whatsapp.message_handling_mode = :background
-  FlowChat::Config.whatsapp.background_job_class = 'WhatsappMessageJob'
-  # Maximum security and scalability
+app.screen(:plan) do |prompt|
+  prompt.select "Choose a plan", { "basic" => "Basic", "pro" => "Pro" },
+    media: { type: :image, url: "https://example.com/plans.png" }
 end
 ```
 
-## 🎯 Best Practices
-
-### 1. Message Design
-- Keep button titles under 20 characters
-- Use clear, actionable text
-- Include relevant emojis for visual appeal
-- Test across different devices
-
-### 2. Media Usage
-- Use appropriate file sizes (< 16MB for documents)
-- Provide descriptive captions
-- Use supported formats (JPEG, PNG for images; PDF for documents)
-- Consider bandwidth limitations
-
-### 3. Flow Design
-- Handle media uploads gracefully
-- Provide clear error messages
-- Use progressive disclosure for complex flows
-- Test with real user scenarios
-
-### 4. Security
-- Always validate webhooks in production
-- Use environment variables for secrets
-- Log security events appropriately
-- Monitor for unusual patterns
-
-### 5. Performance
-- Use background processing for heavy operations
-- Cache frequently used data
-- Monitor response times
-- Handle timeouts gracefully
-
-## 📚 API Reference
-
-### Core Classes
-
-- `FlowChat::Whatsapp::Gateway::CloudApi` - Meta Cloud API gateway implementation
-- `FlowChat::Whatsapp::Gateway::Twilio` - Twilio WhatsApp gateway implementation
-- `FlowChat::Whatsapp::Client` - Meta Cloud API client for out-of-band messaging
-- `FlowChat::Whatsapp::TwilioClient` - Twilio API client for out-of-band messaging
-- `FlowChat::Whatsapp::Configuration` - Meta Cloud API configuration management
-- `FlowChat::Whatsapp::TwilioConfiguration` - Twilio configuration management
-- `FlowChat::Whatsapp::Renderer` - Message rendering logic
-
-### Client Methods
+From 4 to 10 choices there is no interactive surface left that can carry media: Meta's interactive message reference documents a `text`-only header for list messages, image and video and document headers are only defined for button messages. So the image goes out as its own message first, with no caption (the question is about to appear in the list body right behind it), followed by the list exactly as it would render with no media at all.
 
-| Method | Description | Parameters |
-|--------|-------------|------------|
-| `send_message(to, response)` | Send FlowChat response format | phone, response array |
-| `send_text(to, text)` | Send text message | phone, message |
-| `send_buttons(to, text, buttons)` | Send interactive buttons | phone, text, button array |
-| `send_list(to, text, sections, button_text)` | Send interactive list | phone, text, sections, button text |
-| `send_template(to, name, components, language)` | Send template message | phone, template name, components, language |
-| `send_image(to, url_or_id, caption, mime_type)` | Send image | phone, url/media ID, caption, mime type |
-| `send_document(to, url_or_id, caption, filename, mime_type)` | Send document | phone, url/media ID, caption, filename, mime type |
-| `send_video(to, url_or_id, caption, mime_type)` | Send video | phone, url/media ID, caption, mime type |
-| `send_audio(to, url_or_id, mime_type)` | Send audio | phone, url/media ID, mime type |
-| `send_sticker(to, url_or_id, mime_type)` | Send sticker | phone, url/media ID, mime type |
-| `upload_media(file_path_or_io, mime_type, filename)` | Upload file and get media ID | file path/IO, mime type, filename |
-| `get_media_url(media_id)` | Get media URL from ID | media ID |
-| `download_media(media_id)` | Download media content | media ID |
-| `build_message_payload(response, to)` | Build WhatsApp API payload | FlowChat response, phone number |
+Above 10 choices the options are already nothing but text, and a WhatsApp media message can carry a caption up to 1024 characters (documented for image, video, and document messages; audio and sticker messages have no caption field at all). When the media type supports a caption and the prompt plus the numbered options fit under that cap, FlowChat sends one message: the media with the whole numbered list as its caption. When either does not hold - a long option list, or an audio or sticker attachment - it falls back to the same two-message shape as the list rung: the media on its own, with no caption, followed by the numbered text.
 
-### Template Manager Methods
+## Limits to keep in mind
 
-| Method | Description | Parameters |
-|--------|-------------|------------|
-| `send_template(to:, template_name:, language:, components:)` | Send template message | named parameters |
-| `send_welcome_template(to:, name:)` | Send welcome template | phone, optional name |
-| `send_notification_template(to:, message:, button_text:)` | Send notification template | phone, message, optional button |
-| `create_template(name:, category:, language:, components:)` | Create new template | template details |
-| `list_templates()` | List all templates | none |
-| `template_status(template_id)` | Get template status | template ID |
+| Area | Behavior on WhatsApp |
+|---|---|
+| Button titles | Reply-button titles are truncated to 20 characters. |
+| List titles | List row titles are truncated to 24 characters; the full text is moved into the row description (up to 72 characters). |
+| List size | A list holds at most 10 rows in a single section; above that there is no interactive surface left, and the options go into the numbered message body instead. |
+| Media with choices | 3 or fewer: one message, buttons with a media header. 4 to 10: media sent separately, then the list. Above 10: one captioned media message when the caption fits under 1024 characters and the media type supports a caption (image, video, document), otherwise media sent separately, then the numbered text. Never more than 3 reply buttons, with or without media. |
+| 24-hour window | WhatsApp only allows free-form messages within 24 hours of the user's last message. Outside that window you must send an approved template. FlowChat does not abstract this: `send_template` exists, but you manage templates and the window yourself. |
 
-### Configuration Methods
+## Async
 
-| Method | Description | Parameters |
-|--------|-------------|------------|
-| `Configuration.from_credentials()` | Load from Rails credentials/ENV | none |
-| `Configuration.new(name)` | Create named configuration | configuration name |
-| `Configuration.register(name, config)` | Register configuration | name, config object |
-| `Configuration.get(name)` | Get configuration by name | configuration name |
-| `Configuration.exists?(name)` | Check if config exists | configuration name |
+WhatsApp supports background processing. Acknowledge the webhook immediately and run the flow in a job with `use_async`. See [factory-pattern.md](../factory-pattern.md) and [async-background-processing.md](../async-background-processing.md).
 
----
+## Related
 
-This comprehensive guide covers everything you need to build sophisticated WhatsApp integrations with FlowChat. For more examples and advanced patterns, check the [examples directory](../../examples/) in the FlowChat repository.
+- [Getting started](../getting-started.md)
+- [Configuration](../configuration.md)
+- [Instrumentation](../instrumentation.md)