whatsapp-cloud-api-ruby 1.0.0

data/examples/template_management.rb

@@ -0,0 +1,391 @@
+# frozen_string_literal: true
+
+require 'whatsapp_cloud_api'
+
+puts "=== Template Management Examples ==="
+
+# Initialize client
+client = WhatsAppCloudApi::Client.new(
+  access_token: ENV['WHATSAPP_ACCESS_TOKEN']
+)
+
+business_account_id = ENV['BUSINESS_ACCOUNT_ID']
+
+# Example 1: List Existing Templates
+puts "\n--- List Existing Templates ---"
+
+begin
+  templates = client.templates.list(business_account_id: business_account_id)
+  
+  puts "Found #{templates.data.length} templates:"
+  templates.data.each do |template|
+    puts "- #{template.name} (#{template.language}) - Status: #{template.status}"
+  end
+  
+  # Handle pagination if there are more results
+  if templates.paging.after
+    puts "\nMore templates available. Next cursor: #{templates.paging.after}"
+  end
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Error listing templates: #{e.message}"
+end
+
+# Example 2: Create Marketing Template
+puts "\n--- Create Marketing Template ---"
+
+begin
+  # Build a marketing template with the helper method
+  template_data = client.templates.build_marketing_template(
+    name: 'ruby_sdk_promo',
+    language: 'en_US',
+    header: {
+      type: 'HEADER',
+      format: 'TEXT',
+      text: 'Special Offer for {{1}}!'
+    },
+    body: 'Hi {{1}}, we have a special {{2}} discount just for you! Use code {{3}} to get {{4}} off your next purchase.',
+    footer: 'This offer expires in 24 hours',
+    buttons: [
+      {
+        type: 'URL',
+        text: 'Shop Now',
+        url: 'https://example.com/shop?code={{1}}'
+      },
+      {
+        type: 'QUICK_REPLY',
+        text: 'More Info'
+      }
+    ],
+    body_example: {
+      body_text: [['John', 'exclusive', 'SAVE20', '20%']]
+    }
+  )
+  
+  # Create the template
+  response = client.templates.create(
+    business_account_id: business_account_id,
+    **template_data
+  )
+  
+  puts "Marketing template created!"
+  puts "Template ID: #{response.id}"
+  puts "Status: #{response.status}"
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Error creating marketing template: #{e.message}"
+  
+  if e.template_error?
+    puts "Template-specific error - check template format and content"
+  end
+end
+
+# Example 3: Create Authentication Template
+puts "\n--- Create Authentication Template ---"
+
+begin
+  # Build authentication template using helper
+  auth_template = client.templates.build_authentication_template(
+    name: 'ruby_sdk_auth',
+    language: 'en_US',
+    ttl_seconds: 300, # 5 minutes
+    code_expiration_minutes: 5,
+    otp_type: 'COPY_CODE'
+  )
+  
+  response = client.templates.create(
+    business_account_id: business_account_id,
+    **auth_template
+  )
+  
+  puts "Authentication template created!"
+  puts "Template ID: #{response.id}"
+  puts "Status: #{response.status}"
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Error creating auth template: #{e.message}"
+end
+
+# Example 4: Create Utility Template
+puts "\n--- Create Utility Template ---"
+
+begin
+  utility_template = client.templates.build_utility_template(
+    name: 'ruby_sdk_notification',
+    language: 'en_US',
+    header: {
+      type: 'HEADER',
+      format: 'TEXT',
+      text: 'Order Update'
+    },
+    body: 'Your order #{{1}} has been {{2}}. Estimated delivery: {{3}}.',
+    footer: 'Thank you for choosing our service',
+    buttons: [
+      {
+        type: 'URL',
+        text: 'Track Order',
+        url: 'https://example.com/track/{{1}}'
+      }
+    ],
+    body_example: {
+      body_text: [['12345', 'shipped', 'Tomorrow 2-4 PM']]
+    }
+  )
+  
+  response = client.templates.create(
+    business_account_id: business_account_id,
+    **utility_template
+  )
+  
+  puts "Utility template created!"
+  puts "Template ID: #{response.id}"
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Error creating utility template: #{e.message}"
+end
+
+# Example 5: Create Complex Template with All Components
+puts "\n--- Create Complex Template ---"
+
+begin
+  components = [
+    # Header with image
+    {
+      type: 'HEADER',
+      format: 'IMAGE',
+      example: {
+        header_handle: ['https://example.com/header-image.jpg']
+      }
+    },
+    # Body with variables
+    {
+      type: 'BODY',
+      text: 'Hello {{1}}! Your {{2}} order totaling {{3}} is ready for pickup. ' \
+            'Please bring your ID and order confirmation {{4}}.',
+      example: {
+        body_text: [['John Doe', 'premium', '$125.99', '#ORD12345']]
+      }
+    },
+    # Footer
+    {
+      type: 'FOOTER',
+      text: 'Reply STOP to unsubscribe'
+    },
+    # Multiple buttons
+    {
+      type: 'BUTTONS',
+      buttons: [
+        {
+          type: 'URL',
+          text: 'View Order',
+          url: 'https://example.com/orders/{{1}}'
+        },
+        {
+          type: 'PHONE_NUMBER',
+          text: 'Call Store',
+          phone_number: '+1234567890'
+        },
+        {
+          type: 'QUICK_REPLY',
+          text: 'Reschedule'
+        }
+      ]
+    }
+  ]
+  
+  response = client.templates.create(
+    business_account_id: business_account_id,
+    name: 'ruby_sdk_complex',
+    language: 'en_US',
+    category: 'UTILITY',
+    components: components
+  )
+  
+  puts "Complex template created!"
+  puts "Template ID: #{response.id}"
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Error creating complex template: #{e.message}"
+end
+
+# Example 6: Send Template Messages
+puts "\n--- Send Template Messages ---"
+
+begin
+  # Send simple template without variables
+  response1 = client.messages.send_template(
+    phone_number_id: ENV['PHONE_NUMBER_ID'],
+    to: '+1234567890',
+    name: 'hello_world', # Meta's sample template
+    language: 'en_US'
+  )
+  
+  puts "Simple template sent: #{response1.messages.first.id}"
+  
+  # Send template with parameters
+  response2 = client.messages.send_template(
+    phone_number_id: ENV['PHONE_NUMBER_ID'],
+    to: '+1234567890',
+    name: 'ruby_sdk_promo', # Our created template
+    language: 'en_US',
+    components: [
+      {
+        type: 'header',
+        parameters: [
+          { type: 'text', text: 'John Doe' }
+        ]
+      },
+      {
+        type: 'body',
+        parameters: [
+          { type: 'text', text: 'John' },
+          { type: 'text', text: 'exclusive' },
+          { type: 'text', text: 'RUBY20' },
+          { type: 'text', text: '20%' }
+        ]
+      },
+      {
+        type: 'button',
+        sub_type: 'url',
+        index: '0',
+        parameters: [
+          { type: 'text', text: 'RUBY20' }
+        ]
+      }
+    ]
+  )
+  
+  puts "Parameterized template sent: #{response2.messages.first.id}"
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Error sending template: #{e.message}"
+  
+  case e.category
+  when :template
+    puts "Template error - check template name, language, and parameters"
+  when :parameter
+    puts "Parameter error - check component parameters format"
+  end
+end
+
+# Example 7: Template Management Operations
+puts "\n--- Template Management Operations ---"
+
+begin
+  # Get specific template details
+  template_id = 'your_template_id' # Replace with actual template ID
+  
+  template = client.templates.get(
+    business_account_id: business_account_id,
+    template_id: template_id
+  )
+  
+  puts "Template Details:"
+  puts "Name: #{template.name}"
+  puts "Status: #{template.status}"
+  puts "Category: #{template.category}"
+  puts "Quality Score: #{template.quality_score_category}"
+  
+  # Update template (if allowed)
+  if template.status == 'REJECTED'
+    puts "Attempting to update rejected template..."
+    
+    client.templates.update(
+      business_account_id: business_account_id,
+      template_id: template_id,
+      category: 'UTILITY' # Change category if needed
+    )
+    
+    puts "Template updated successfully"
+  end
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Template management error: #{e.message}"
+end
+
+# Example 8: Delete Templates
+puts "\n--- Delete Templates ---"
+
+begin
+  # Delete by template ID
+  client.templates.delete(
+    business_account_id: business_account_id,
+    template_id: 'template_id_to_delete'
+  )
+  
+  puts "Template deleted by ID"
+  
+  # Delete by name and language
+  client.templates.delete(
+    business_account_id: business_account_id,
+    name: 'ruby_sdk_test',
+    language: 'en_US'
+  )
+  
+  puts "Template deleted by name"
+  
+rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  puts "Delete error: #{e.message}"
+  
+  if e.http_status == 404
+    puts "Template not found - may already be deleted"
+  end
+end
+
+# Example 9: Template Validation and Best Practices
+puts "\n--- Template Validation Examples ---"
+
+# Good template example
+def create_good_template(client, business_account_id)
+  client.templates.create(
+    business_account_id: business_account_id,
+    name: 'good_template_example',
+    language: 'en_US',
+    category: 'UTILITY',
+    components: [
+      {
+        type: 'BODY',
+        text: 'Your appointment with {{1}} is confirmed for {{2}} at {{3}}.',
+        example: {
+          body_text: [['Dr. Smith', 'tomorrow', '2:00 PM']]
+        }
+      },
+      {
+        type: 'FOOTER',
+        text: 'Reply CANCEL to cancel this appointment'
+      }
+    ]
+  )
+end
+
+# Bad template example (this will likely be rejected)
+def create_bad_template_example(client, business_account_id)
+  begin
+    client.templates.create(
+      business_account_id: business_account_id,
+      name: 'bad_template_example',
+      language: 'en_US',
+      category: 'MARKETING',
+      components: [
+        {
+          type: 'BODY',
+          text: 'URGENT!!! Buy now or MISS OUT!!! Limited time offer!!!'
+          # No example provided, excessive caps, promotional language
+        }
+      ]
+    )
+  rescue WhatsAppCloudApi::Errors::GraphApiError => e
+    puts "Bad template rejected (expected): #{e.message}"
+  end
+end
+
+begin
+  good_response = create_good_template(client, business_account_id)
+  puts "Good template created: #{good_response.id}"
+rescue => e
+  puts "Error with good template: #{e.message}"
+end
+
+create_bad_template_example(client, business_account_id)
+
+puts "\n=== Template Management Examples Completed ==="

data/lib/whatsapp_cloud_api/client.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/multipart'
+require 'json'
+require 'logger'
+
+module WhatsAppCloudApi
+  class Client
+    DEFAULT_BASE_URL = 'https://graph.facebook.com'
+    DEFAULT_GRAPH_VERSION = 'v24.0'
+    KAPSO_PROXY_PATTERN = /kapso\.ai/
+
+    attr_reader :access_token, :kapso_api_key, :base_url, :graph_version, 
+                :logger, :debug, :timeout, :open_timeout, :max_retries, :retry_delay
+
+    def initialize(access_token: nil, kapso_api_key: nil, base_url: nil, 
+                   graph_version: nil, logger: nil, debug: nil, timeout: nil, 
+                   open_timeout: nil, max_retries: nil, retry_delay: nil)
+      
+      # Validation
+      unless access_token || kapso_api_key
+        raise Errors::ConfigurationError, 'Must provide either access_token or kapso_api_key'
+      end
+
+      @access_token = access_token
+      @kapso_api_key = kapso_api_key
+      @base_url = normalize_base_url(base_url || DEFAULT_BASE_URL)
+      @graph_version = graph_version || DEFAULT_GRAPH_VERSION
+      @kapso_proxy = detect_kapso_proxy(@base_url)
+      
+      # Configuration with defaults
+      config = WhatsAppCloudApi.configuration
+      @logger = logger || WhatsAppCloudApi.logger
+      @debug = debug.nil? ? config.debug : debug
+      @timeout = timeout || config.timeout
+      @open_timeout = open_timeout || config.open_timeout
+      @max_retries = max_retries || config.max_retries
+      @retry_delay = retry_delay || config.retry_delay
+
+      # Initialize HTTP client
+      @http_client = build_http_client
+
+      # Initialize resource endpoints
+      @messages = nil
+      @media = nil
+      @templates = nil
+      @phone_numbers = nil
+      @calls = nil
+      @conversations = nil
+      @contacts = nil
+    end
+
+    # Resource accessors with lazy initialization
+    def messages
+      @messages ||= Resources::Messages.new(self)
+    end
+
+    def media
+      @media ||= Resources::Media.new(self)
+    end
+
+    def templates
+      @templates ||= Resources::Templates.new(self)
+    end
+
+    def phone_numbers
+      @phone_numbers ||= Resources::PhoneNumbers.new(self)
+    end
+
+    def calls
+      @calls ||= Resources::Calls.new(self)
+    end
+
+    def conversations
+      @conversations ||= Resources::Conversations.new(self)
+    end
+
+    def contacts
+      @contacts ||= Resources::Contacts.new(self)
+    end
+
+    def kapso_proxy?
+      @kapso_proxy
+    end
+
+    # Main request method with retry logic and error handling
+    def request(method, path, options = {})
+      method = method.to_s.upcase
+      body = options[:body]
+      query = options[:query]
+      custom_headers = options[:headers] || {}
+      response_type = options[:response_type] || :auto
+
+      url = build_url(path, query)
+      headers = build_headers(custom_headers)
+      
+      # Log request if debugging
+      log_request(method, url, headers, body) if debug
+
+      retries = 0
+      begin
+        response = @http_client.run_request(method.downcase.to_sym, url, body, headers)
+        
+        # Log response if debugging
+        log_response(response) if debug
+
+        # Handle response based on type requested
+        handle_response(response, response_type)
+      rescue Faraday::Error => e
+        retries += 1
+        if retries <= max_retries && retryable_error?(e)
+          sleep(retry_delay * retries)
+          retry
+        else
+          raise Errors::GraphApiError.new(
+            message: "Network error: #{e.message}",
+            http_status: 0,
+            category: :server
+          )
+        end
+      end
+    end
+
+    # Raw HTTP method without automatic error handling (for media downloads, etc.)
+    def raw_request(method, url, options = {})
+      headers = build_headers(options[:headers] || {})
+      
+      log_request(method, url, headers, options[:body]) if debug
+      
+      response = @http_client.run_request(method.to_sym, url, options[:body], headers)
+      
+      log_response(response) if debug
+      
+      response
+    end
+
+    # Fetch with automatic auth headers (for absolute URLs)
+    def fetch(url, options = {})
+      headers = build_headers(options[:headers] || {})
+      method = options[:method] || 'GET'
+      
+      log_request(method, url, headers, options[:body]) if debug
+      
+      response = @http_client.run_request(method.downcase.to_sym, url, options[:body], headers)
+      
+      log_response(response) if debug
+      
+      if response.success?
+        response
+      else
+        handle_error_response(response)
+      end
+    end
+
+    private
+
+    def build_http_client
+      Faraday.new do |f|
+        f.options.timeout = timeout
+        f.options.open_timeout = open_timeout
+        f.request :multipart
+        f.request :url_encoded
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def build_headers(custom_headers = {})
+      headers = {}
+      
+      # Authentication headers
+      if access_token
+        headers['Authorization'] = "Bearer #{access_token}"
+      end
+      
+      if kapso_api_key
+        headers['X-API-Key'] = kapso_api_key
+      end
+      
+      # Default content type for JSON requests
+      headers['Content-Type'] = 'application/json' unless custom_headers.key?('Content-Type')
+      
+      headers.merge(custom_headers.compact)
+    end
+
+    def build_url(path, query = nil)
+      # Remove leading slash from path
+      clean_path = path.to_s.sub(%r{^/}, '')
+      
+      # Build base URL with version
+      base = "#{base_url}/#{graph_version}/"
+      full_url = URI.join(base, clean_path).to_s
+      
+      # Add query parameters if present
+      if query && !query.empty?
+        # Convert to snake_case for API (Meta expects snake_case)
+        snake_query = Types.deep_snake_case_keys(query)
+        query_string = URI.encode_www_form(flatten_query(snake_query))
+        separator = full_url.include?('?') ? '&' : '?'
+        full_url += "#{separator}#{query_string}"
+      end
+      
+      full_url
+    end
+
+    def flatten_query(query, prefix = nil)
+      result = []
+      query.each do |key, value|
+        param_key = prefix ? "#{prefix}[#{key}]" : key.to_s
+        
+        case value
+        when Hash
+          result.concat(flatten_query(value, param_key))
+        when Array
+          value.each { |v| result << [param_key, v] }
+        else
+          result << [param_key, value] unless value.nil?
+        end
+      end
+      result
+    end
+
+    def handle_response(response, response_type)
+      unless response.success?
+        handle_error_response(response)
+      end
+
+      case response_type
+      when :json
+        parse_json_response(response)
+      when :raw
+        response
+      when :auto
+        content_type = response.headers['content-type'] || ''
+        if content_type.include?('application/json')
+          parse_json_response(response)
+        elsif response.status == 204
+          Types::GraphSuccessResponse.new
+        else
+          response.body
+        end
+      else
+        response.body
+      end
+    end
+
+    def parse_json_response(response)
+      return Types::GraphSuccessResponse.new if response.body.nil? || response.body.strip.empty?
+      
+      begin
+        json = JSON.parse(response.body)
+        # Convert camelCase keys to snake_case for Ruby conventions
+        Types.deep_snake_case_keys(json)
+      rescue JSON::ParserError => e
+        raise Errors::GraphApiError.new(
+          message: "Invalid JSON response: #{e.message}",
+          http_status: response.status,
+          raw_response: response.body
+        )
+      end
+    end
+
+    def handle_error_response(response)
+      body = response.body
+      
+      # Try to parse JSON error
+      begin
+        json_body = JSON.parse(body) if body && !body.strip.empty?
+      rescue JSON::ParserError
+        json_body = nil
+      end
+      
+      # Create error with proper parameters
+      raise Errors::GraphApiError.from_response(response, json_body || {}, body)
+    end
+
+    def retryable_error?(error)
+      # Only retry on network errors, not HTTP errors
+      error.is_a?(Faraday::TimeoutError) ||
+        error.is_a?(Faraday::ConnectionFailed) ||
+        error.is_a?(Faraday::ServerError)
+    end
+
+    def normalize_base_url(url)
+      url = url.to_s
+      url = "https://#{url}" unless url.match?(%r{^https?://})
+      url.chomp('/')
+    end
+
+    def detect_kapso_proxy(url)
+      url.match?(KAPSO_PROXY_PATTERN)
+    end
+
+    def log_request(method, url, headers, body)
+      logger.debug "WhatsApp API Request: #{method} #{url}"
+      logger.debug "Headers: #{headers.inspect}" if headers.any?
+      
+      if body
+        if body.is_a?(String)
+          logger.debug "Body: #{body.length > 1000 ? "#{body[0..1000]}..." : body}"
+        else
+          logger.debug "Body: #{body.inspect}"
+        end
+      end
+    end
+
+    def log_response(response)
+      logger.debug "WhatsApp API Response: #{response.status}"
+      logger.debug "Response Headers: #{response.headers.to_h.inspect}"
+      
+      if response.body
+        body_preview = response.body.length > 1000 ? "#{response.body[0..1000]}..." : response.body
+        logger.debug "Response Body: #{body_preview}"
+      end
+    end
+  end
+end