whatsapp-cloud-api-ruby 1.0.0

data/Rakefile

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+desc 'Run RSpec tests'
+task :spec do
+  sh 'bundle exec rspec'
+end
+
+desc 'Run RuboCop'
+task :rubocop do
+  sh 'bundle exec rubocop'
+end
+
+desc 'Run all linting and tests'
+task test: [:rubocop, :spec]
+
+desc 'Generate YARD documentation'
+task :docs do
+  sh 'bundle exec yard doc'
+end
+
+desc 'Clean up generated files'
+task :clean do
+  sh 'rm -rf coverage/ doc/ .yardoc/'
+end
+
+desc 'Build the gem'
+task :build do
+  sh 'gem build whatsapp-cloud-api-ruby.gemspec'
+end
+
+desc 'Install the gem locally'
+task install: :build do
+  sh 'gem install whatsapp-cloud-api-ruby-*.gem'
+end
+
+desc 'Release the gem'
+task release: [:clean, :test, :build] do
+  puts 'Run `gem push whatsapp-cloud-api-ruby-*.gem` to release'
+end
+
+task default: :test

data/TEMPLATE_TOOLS_GUIDE.md

@@ -0,0 +1,121 @@
+# 📋 Kapso Template Management Tools
+
+## The 24-Hour Problem & Solution
+
+**Problem**: You're getting "24 hours have passed" errors when sending messages.  
+**Solution**: Use template messages - they work anytime, no 24-hour limit!
+
+## 🛠️ Template Tools (Simplified)
+
+### 1. `scripts/kapso_template_finder.rb` - **MAIN TOOL** ⭐
+```bash
+ruby scripts/kapso_template_finder.rb
+```
+**Purpose**: Complete template discovery and testing  
+**Features**: 
+- Fetches your actual created templates from Kapso
+
+### 2. `scripts/test.rb` - Basic Message Testing
+```bash  
+ruby scripts/test.rb
+```
+**Purpose**: Test regular message sending  
+**Use when**: Testing within 24-hour window  
+**Features**:
+- Test regular messages 
+- Shows 24h error if outside window
+
+## 📋 Setup Instructions
+
+### Step 1: Find Your Business Account ID
+
+1. **Login to Kapso Dashboard**: https://app.kapso.ai/
+2. **Navigate to WhatsApp Business section**
+3. **Look for**:
+   - "Business Account ID"
+   - "WABA ID" 
+   - Long number (15+ digits)
+4. **Add to `.env` file**:
+   ```properties
+   BUSINESS_ACCOUNT_ID=your_business_account_id_here
+   ```
+
+### Step 2: Discover Your Templates
+
+```bash
+ruby scripts/kapso_template_finder.rb
+```
+
+✅ **Current Status**: Found 1 template `reply_message (es_MX) - PENDING`  
+⏳ **Waiting for approval** - Template will work once Meta approves it
+
+### Step 3: Test Templates
+
+```bash
+ruby test_specific_template.rb
+# Enter template name when prompted
+```
+
+## 🎯 Creating Templates in Kapso
+
+### Via Kapso Dashboard:
+1. Login to https://app.kapso.ai/
+2. Find "WhatsApp Templates" or "Template Builder"
+3. Create simple text template:
+   - **Name**: `hello_world` or `welcome_message`
+   - **Language**: `en_US`  
+   - **Category**: `UTILITY` (usually fastest approval)
+   - **Content**: "Hello {{1}}, welcome to our service!"
+
+### Template Approval:
+- **Pending**: Template submitted, waiting for Meta approval
+- **Approved**: Ready to use anytime  
+- **Rejected**: Need to fix and resubmit
+- **Time**: Usually 24-48 hours for approval
+
+## 🚀 Using Templates in Code
+
+```ruby
+# Once your template is approved:
+response = client.messages.send_template(
+  phone_number_id: "your_phone_number",
+  to: "+56912345678", 
+  name: "reply_message",      # Your actual template name
+  language: "es_MX"           # Your template language
+)
+
+# Templates work 24/7 - no time restrictions!
+```
+
+## 🔄 Workflow Summary
+
+1. **Check templates**: `ruby scripts/kapso_template_finder.rb`
+2. ✅ **Template found**: `reply_message (es_MX) - PENDING`
+3. ⏳ **Wait for approval**: Meta is reviewing your template  
+4. **Once approved**: Use `reply_message` template for 24/7 messaging
+
+## ❓ Troubleshooting
+
+### "Template not found"
+- Template name is wrong
+- Template not approved yet
+- Language code incorrect
+
+### "24 hours error" (with templates)
+- This shouldn't happen with templates
+- Contact Kapso support
+
+### "Business Account ID not found"
+- Check Kapso dashboard for WABA ID
+- Add to .env file
+- Contact Kapso support if unclear
+
+## 📞 Support Resources
+
+- **Kapso Dashboard**: https://app.kapso.ai/
+- **Kapso Support**: Contact through dashboard
+- **WhatsApp Template Policies**: Check Meta Business documentation
+
+---
+
+**Remember**: Templates solve the 24-hour limitation permanently! Regular messages work within 24h of customer reply, templates work anytime. 🎯

data/WHATSAPP_24_HOUR_GUIDE.md

@@ -0,0 +1,134 @@
+# WhatsApp 24-Hour Window Policy - Solutions Guide
+
+## The Problem You're Experiencing
+
+**Error Message**: "Meta reported a deli### Long-term**: Design your messaging strategy around the 24h rule
+
+## Kapso.ai Specific Features
+
+Since you're using Kapso.ai, you may have access to:
+
+- **Template Library**: Pre-built approved templates
+- **Template Builder**: Easy template creation interface  
+- **Auto-Approval**: Faster template approval process
+- **Template Analytics**: Usage statistics and delivery rates
+- **Bulk Template Management**: Manage multiple templates
+
+Check your Kapso dashboard for:
+1. **Available Templates** - Already approved and ready to use
+2. **Template Status** - Pending, approved, or rejected templates
+3. **Template Builder** - Create new templates without Meta Business Manager
+
+## Why This Existsy error. Re-engagement message Message failed to send because more than 24 hours have passed since the customer last replied to this number."
+
+This is **NOT** a bug in your Ruby SDK - it's a WhatsApp Business API policy.
+
+## Understanding the 24-Hour Rule
+
+WhatsApp Business API has a **conversation window** policy:
+
+### ✅ Within 24 Hours (Free Messaging Window)
+- **Trigger**: Customer sends you a message
+- **Duration**: 24 hours from their last message
+- **Allowed**: ANY message type (text, images, audio, video, documents)
+- **No restrictions**: Send as many messages as you want
+
+### ❌ After 24 Hours (Template-Only Window)  
+- **Trigger**: 24+ hours since customer's last message
+- **Restriction**: ONLY pre-approved template messages allowed
+- **Regular messages**: Will be rejected with your error
+
+## Solutions
+
+### Option 1: Use Template Messages (Recommended)
+
+Template messages work anytime and are designed for business communications:
+
+```ruby
+# Send a template message (works 24/7)
+response = client.messages.send_template(
+  phone_number_id: phone_number_id,
+  to: "+56912345678",
+  template_name: "hello_world",  # Must be pre-approved
+  template_language: "en_US"
+)
+```
+
+### Option 2: Wait for Customer Reply
+
+- Customer sends any message → Opens 24-hour window
+- You can then send regular messages for 24 hours
+
+### Option 3: Create Templates via Kapso.ai
+
+✅ **Current Status**: You already have templates in progress!
+
+1. **Kapso Dashboard**: ✅ Connected (Business Account: `your_business_id_account`)
+2. **Template Found**: `reply_message (es_MX) - PENDING`
+3. **Status**: Waiting for Meta approval (usually 24-48 hours)
+4. **Once Approved**: Use `your_template` template for 24/7 messaging
+5. **Test Tool**: `ruby scripts/kapso_template_finder.rb`
+
+## Prevention Strategies
+
+### For Customer Service
+- Respond within 24 hours of customer messages
+- Use templates for follow-ups after 24h
+- Set up auto-responses within the window
+
+### For Marketing  
+- Always use approved template messages
+- Create templates for different campaigns
+- Schedule template sends anytime
+
+### For Notifications
+- Use templates for order updates, reminders, etc.
+- Create templates for common notifications
+- Test templates before going live
+
+## Template Message Examples
+
+### Basic Template (No Variables)
+```ruby
+client.messages.send_template(
+  phone_number_id: phone_number_id,
+  to: phone_number,
+  template_name: "hello_world",
+  template_language: "en_US"
+)
+```
+
+### Template with Variables
+```ruby
+client.messages.send_template(
+  phone_number_id: phone_number_id,
+  to: phone_number,
+  template_name: "order_confirmation",
+  template_language: "en_US",
+  components: [
+    {
+      type: "body",
+      parameters: [
+        { type: "text", text: "John" },      # Customer name
+        { type: "text", text: "12345" }     # Order number
+      ]
+    }
+  ]
+)
+```
+
+## Next Steps
+
+1. **Immediate**: Use `ruby template_test.rb` to test template messages
+2. **Short-term**: Create templates in Meta Business Manager
+3. **Long-term**: Design your messaging strategy around the 24h rule
+
+## Why This Exists
+
+WhatsApp enforces this to:
+- Prevent spam
+- Ensure quality business communications  
+- Protect user experience
+- Maintain platform integrity
+
+The Ruby SDK is working perfectly - this is just how WhatsApp Business API works! 🚀

data/examples/advanced_features.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require 'whatsapp_cloud_api'
+
+puts "=== Advanced Features with Kapso Proxy ==="
+
+# Initialize Kapso client
+kapso_client = WhatsAppCloudApi::Client.new(
+  kapso_api_key: ENV['KAPSO_API_KEY'],
+  base_url: 'https://app.kapso.ai/api/meta',
+  debug: true
+)
+
+phone_number_id = ENV['PHONE_NUMBER_ID']
+
+# Example 1: Message History and Analytics
+puts "\n--- Message History ---"
+
+begin
+  # Query message history
+  messages = kapso_client.messages.query(
+    phone_number_id: phone_number_id,
+    direction: 'inbound',
+    since: '2024-01-01T00:00:00Z',
+    limit: 10
+  )
+  
+  puts "Found #{messages.data.length} messages:"
+  messages.data.each do |message|
+    puts "- #{message['id']}: #{message['type']} from #{message['from']}"
+  end
+  
+  # Get messages by conversation
+  if messages.data.any? && messages.data.first['conversation_id']
+    conv_messages = kapso_client.messages.list_by_conversation(
+      phone_number_id: phone_number_id,
+      conversation_id: messages.data.first['conversation_id'],
+      limit: 5
+    )
+    
+    puts "\nConversation messages: #{conv_messages.data.length}"
+  end
+  
+rescue WhatsAppCloudApi::Errors::KapsoProxyRequiredError => e
+  puts "Kapso Proxy required: #{e.message}"
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Message history error: #{e.message}"
+end
+
+# Example 2: Conversation Management
+puts "\n--- Conversation Management ---"
+
+begin
+  # List active conversations
+  conversations = kapso_client.conversations.list(
+    phone_number_id: phone_number_id,
+    status: 'active',
+    limit: 10
+  )
+  
+  puts "Active conversations: #{conversations.data.length}"
+  
+  conversations.data.each do |conv|
+    puts "Conversation #{conv.id}:"
+    puts "  Phone: #{conv.phone_number}"
+    puts "  Status: #{conv.status}"
+    puts "  Last Active: #{conv.last_active_at}"
+    
+    if conv.kapso
+      puts "  Contact Name: #{conv.kapso['contact_name']}"
+      puts "  Messages Count: #{conv.kapso['messages_count']}"
+      puts "  Last Message: #{conv.kapso['last_message_text']}"
+    end
+  end
+  
+  # Get specific conversation details
+  if conversations.data.any?
+    conversation_id = conversations.data.first.id
+    
+    conv_details = kapso_client.conversations.get(
+      conversation_id: conversation_id
+    )
+    
+    puts "\nDetailed conversation info:"
+    puts "ID: #{conv_details.id}"
+    puts "Status: #{conv_details.status}"
+    puts "Metadata: #{conv_details.metadata}"
+    
+    # Update conversation status
+    kapso_client.conversations.update_status(
+      conversation_id: conversation_id,
+      status: 'archived'
+    )
+    
+    puts "Conversation archived successfully"
+    
+    # Unarchive it
+    kapso_client.conversations.unarchive(conversation_id: conversation_id)
+    puts "Conversation unarchived"
+  end
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Conversation management error: #{e.message}"
+end
+
+# Example 3: Contact Management
+puts "\n--- Contact Management ---"
+
+begin
+  # List contacts
+  contacts = kapso_client.contacts.list(
+    phone_number_id: phone_number_id,
+    limit: 10
+  )
+  
+  puts "Found #{contacts.data.length} contacts:"
+  
+  contacts.data.each do |contact|
+    puts "Contact #{contact.wa_id}:"
+    puts "  Phone: #{contact.phone_number}"
+    puts "  Profile Name: #{contact.profile_name}"
+    puts "  Metadata: #{contact.metadata}"
+  end
+  
+  # Get specific contact
+  if contacts.data.any?
+    wa_id = contacts.data.first.wa_id
+    
+    contact_details = kapso_client.contacts.get(
+      phone_number_id: phone_number_id,
+      wa_id: wa_id
+    )
+    
+    puts "\nContact details for #{wa_id}:"
+    puts "Profile Name: #{contact_details.profile_name}"
+    
+    # Update contact metadata
+    kapso_client.contacts.update(
+      phone_number_id: phone_number_id,
+      wa_id: wa_id,
+      metadata: {
+        tags: ['ruby_sdk', 'test_contact'],
+        source: 'api_example',
+        notes: 'Updated via Ruby SDK'
+      }
+    )
+    
+    puts "Contact metadata updated"
+    
+    # Add tags
+    kapso_client.contacts.add_tags(
+      phone_number_id: phone_number_id,
+      wa_id: wa_id,
+      tags: ['premium_customer']
+    )
+    
+    puts "Tags added to contact"
+    
+    # Search contacts
+    search_results = kapso_client.contacts.search(
+      phone_number_id: phone_number_id,
+      query: 'john',
+      search_in: ['profile_name', 'phone_number']
+    )
+    
+    puts "Search results: #{search_results.data.length} contacts"
+  end
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Contact management error: #{e.message}"
+end
+
+# Example 4: Call Management
+puts "\n--- Call Management ---"
+
+begin
+  # List recent calls
+  calls = kapso_client.calls.list(
+    phone_number_id: phone_number_id,
+    direction: 'INBOUND',
+    limit: 5
+  )
+  
+  puts "Recent calls: #{calls.data.length}"
+  
+  calls.data.each do |call|
+    puts "Call #{call.id}:"
+    puts "  Direction: #{call.direction}"
+    puts "  Status: #{call.status}"
+    puts "  Duration: #{call.duration_seconds} seconds"
+    puts "  Started: #{call.started_at}"
+  end
+  
+  # Initiate a call (example - requires proper setup)
+  begin
+    call_response = kapso_client.calls.connect(
+      phone_number_id: phone_number_id,
+      to: '+1234567890',
+      session: {
+        sdp_type: 'offer',
+        sdp: 'v=0\r\no=- 123456789 123456789 IN IP4 127.0.0.1\r\n...'
+      }
+    )
+    
+    puts "Call initiated: #{call_response.calls.first['id']}"
+  rescue WhatsAppCloudApi::Errors::GraphApiError => e
+    puts "Call initiation error (expected in example): #{e.message}"
+  end
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Call management error: #{e.message}"
+end
+
+# Example 5: Advanced Error Handling and Monitoring
+puts "\n--- Advanced Error Handling ---"
+
+class WhatsAppMonitor
+  def initialize(client)
+    @client = client
+    @error_counts = Hash.new(0)
+    @last_errors = []
+  end
+  
+  def send_with_monitoring(method, *args, **kwargs)
+    start_time = Time.now
+    
+    begin
+      result = @client.messages.public_send(method, **kwargs)
+      
+      duration = Time.now - start_time
+      puts "✓ #{method} succeeded in #{duration.round(2)}s"
+      
+      result
+    rescue WhatsAppCloudApi::Errors::GraphApiError => e
+      duration = Time.now - start_time
+      @error_counts[e.category] += 1
+      @last_errors << {
+        timestamp: Time.now,
+        method: method,
+        error: e,
+        duration: duration
+      }
+      
+      puts "✗ #{method} failed in #{duration.round(2)}s"
+      puts "  Category: #{e.category}"
+      puts "  Message: #{e.message}"
+      puts "  Retry: #{e.retry_hint[:action]}"
+      
+      # Automatic retry logic
+      case e.retry_hint[:action]
+      when :retry
+        if kwargs[:_retry_count].to_i < 3
+          retry_count = kwargs[:_retry_count].to_i + 1
+          puts "  Auto-retrying (#{retry_count}/3)..."
+          sleep(retry_count)
+          return send_with_monitoring(method, **kwargs.merge(_retry_count: retry_count))
+        end
+      when :retry_after
+        if e.retry_hint[:retry_after_ms] && e.retry_hint[:retry_after_ms] < 30000
+          delay = e.retry_hint[:retry_after_ms] / 1000.0
+          puts "  Waiting #{delay}s for rate limit..."
+          sleep(delay)
+          return send_with_monitoring(method, **kwargs)
+        end
+      end
+      
+      raise
+    end
+  end
+  
+  def print_statistics
+    puts "\n--- Error Statistics ---"
+    puts "Total error categories: #{@error_counts.keys.length}"
+    @error_counts.each do |category, count|
+      puts "  #{category}: #{count} errors"
+    end
+    
+    if @last_errors.any?
+      puts "\nRecent errors:"
+      @last_errors.last(3).each do |error_info|
+        puts "  #{error_info[:timestamp]}: #{error_info[:method]} -> #{error_info[:error].category}"
+      end
+    end
+  end
+end
+
+# Test the monitoring system
+monitor = WhatsAppMonitor.new(kapso_client)
+
+# Test various operations with monitoring
+test_operations = [
+  [:send_text, {
+    phone_number_id: phone_number_id,
+    to: '+1234567890',
+    body: 'Test message from monitoring system'
+  }],
+  [:send_template, {
+    phone_number_id: phone_number_id,
+    to: '+1234567890',
+    name: 'nonexistent_template',
+    language: 'en_US'
+  }],
+  [:send_image, {
+    phone_number_id: phone_number_id,
+    to: '+1234567890',
+    image: { link: 'https://invalid-url.example/image.jpg' }
+  }]
+]
+
+test_operations.each do |method, kwargs|
+  begin
+    monitor.send_with_monitoring(method, **kwargs)
+  rescue => e
+    puts "Final error for #{method}: #{e.message}"
+  end
+  
+  sleep(1) # Rate limiting prevention
+end
+
+monitor.print_statistics
+
+# Example 6: Webhook Signature Verification (helper function)
+puts "\n--- Webhook Signature Verification ---"
+
+def verify_webhook_signature(payload, signature, app_secret)
+  require 'openssl'
+  
+  # Extract signature from header (format: "sha256=...")
+  sig_hash = signature.sub('sha256=', '')
+  
+  # Calculate expected signature
+  expected_sig = OpenSSL::HMAC.hexdigest('sha256', app_secret, payload)
+  
+  # Secure comparison
+  sig_hash == expected_sig
+end
+
+# Example webhook payload verification
+webhook_payload = '{"object":"whatsapp_business_account","entry":[...]}'
+webhook_signature = 'sha256=abcdef123456...' # From X-Hub-Signature-256 header
+app_secret = ENV['WHATSAPP_APP_SECRET']
+
+if app_secret
+  is_valid = verify_webhook_signature(webhook_payload, webhook_signature, app_secret)
+  puts "Webhook signature valid: #{is_valid}"
+else
+  puts "Set WHATSAPP_APP_SECRET to test webhook verification"
+end
+
+puts "\n=== Advanced Features Examples Completed ==="