feat: Added the ability to create Instagram channel (#11182)

This PR is part of https://github.com/chatwoot/chatwoot/pull/11054 to
make the review cycle easier.

app/controllers/api/v1/accounts/instagram/authorizations_controller.rb

@@ -0,0 +1,30 @@
+class Api::V1::Accounts::Instagram::AuthorizationsController < Api::V1::Accounts::BaseController
+  include InstagramConcern
+  include Instagram::IntegrationHelper
+  before_action :check_authorization
+
+  def create
+    # https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login#step-1--get-authorization
+    redirect_url = instagram_client.auth_code.authorize_url(
+      {
+        redirect_uri: "#{base_url}/instagram/callback",
+        scope: REQUIRED_SCOPES.join(','),
+        enable_fb_login: '0',
+        force_authentication: '1',
+        response_type: 'code',
+        state: generate_instagram_token(Current.account.id)
+      }
+    )
+    if redirect_url
+      render json: { success: true, url: redirect_url }
+    else
+      render json: { success: false }, status: :unprocessable_entity
+    end
+  end
+
+  private
+
+  def check_authorization
+    raise Pundit::NotAuthorizedError unless Current.account_user.administrator?
+  end
+end

app/controllers/concerns/instagram_concern.rb

@@ -0,0 +1,75 @@
+module InstagramConcern
+  extend ActiveSupport::Concern
+  include HTTParty
+
+  def instagram_client
+    ::OAuth2::Client.new(
+      client_id,
+      client_secret,
+      {
+        site: 'https://api.instagram.com',
+        authorize_url: 'https://api.instagram.com/oauth/authorize',
+        token_url: 'https://api.instagram.com/oauth/access_token',
+        auth_scheme: :request_body,
+        token_method: :post
+      }
+    )
+  end
+
+  private
+
+  def client_id
+    GlobalConfigService.load('INSTAGRAM_APP_ID', nil)
+  end
+
+  def client_secret
+    GlobalConfigService.load('INSTAGRAM_APP_SECRET', nil)
+  end
+
+  def exchange_for_long_lived_token(short_lived_token)
+    endpoint = 'https://graph.instagram.com/access_token'
+    params = {
+      grant_type: 'ig_exchange_token',
+      client_secret: client_secret,
+      access_token: short_lived_token,
+      client_id: client_id
+    }
+
+    make_api_request(endpoint, params, 'Failed to exchange token')
+  end
+
+  def fetch_instagram_user_details(access_token)
+    endpoint = 'https://graph.instagram.com/v22.0/me'
+    params = {
+      fields: 'id,username,user_id,name,profile_picture_url,account_type',
+      access_token: access_token
+    }
+
+    make_api_request(endpoint, params, 'Failed to fetch Instagram user details')
+  end
+
+  def make_api_request(endpoint, params, error_prefix)
+    response = HTTParty.get(
+      endpoint,
+      query: params,
+      headers: { 'Accept' => 'application/json' }
+    )
+
+    unless response.success?
+      Rails.logger.error "#{error_prefix}. Status: #{response.code}, Body: #{response.body}"
+      raise "#{error_prefix}: #{response.body}"
+    end
+
+    begin
+      JSON.parse(response.body)
+    rescue JSON::ParserError => e
+      ChatwootExceptionTracker.new(e).capture_exception
+      Rails.logger.error "Invalid JSON response: #{response.body}"
+      raise e
+    end
+  end
+
+  def base_url
+    ENV.fetch('FRONTEND_URL', 'http://localhost:3000')
+  end
+end

app/controllers/instagram/callbacks_controller.rb

@@ -0,0 +1,123 @@
+class Instagram::CallbacksController < ApplicationController
+  include InstagramConcern
+  include Instagram::IntegrationHelper
+
+  def show
+    # Check if Instagram redirected with an error (user canceled authorization)
+    # See: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login#canceled-authorization
+    if params[:error].present?
+      handle_authorization_error
+      return
+    end
+
+    process_successful_authorization
+  rescue StandardError => e
+    handle_error(e)
+  end
+
+  private
+
+  # Process the authorization code and create inbox
+  def process_successful_authorization
+    @response = instagram_client.auth_code.get_token(
+      oauth_code,
+      redirect_uri: "#{base_url}/#{provider_name}/callback",
+      grant_type: 'authorization_code'
+    )
+
+    @long_lived_token_response = exchange_for_long_lived_token(@response.token)
+    inbox, = create_channel_with_inbox
+    redirect_to app_instagram_inbox_agents_url(account_id: account_id, inbox_id: inbox.id)
+  end
+
+  # Handle all errors that might occur during authorization
+  # https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login#sample-rejected-response
+  def handle_error(error)
+    Rails.logger.error("Instagram Channel creation Error: #{error.message}")
+    ChatwootExceptionTracker.new(error).capture_exception
+
+    error_info = extract_error_info(error)
+    redirect_to_error_page(error_info)
+  end
+
+  # Extract error details from the exception
+  def extract_error_info(error)
+    if error.is_a?(OAuth2::Error)
+      begin
+        # Instagram returns JSON error response which we parse to extract error details
+        JSON.parse(error.message)
+      rescue JSON::ParseError
+        # Fall back to a generic OAuth error if JSON parsing fails
+        { 'error_type' => 'OAuthException', 'code' => 400, 'error_message' => error.message }
+      end
+    else
+      # For other unexpected errors
+      { 'error_type' => error.class.name, 'code' => 500, 'error_message' => error.message }
+    end
+  end
+
+  # Handles the case when a user denies permissions or cancels the authorization flow
+  # Error parameters are documented at:
+  # https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login/business-login#canceled-authorization
+  def handle_authorization_error
+    error_info = {
+      'error_type' => params[:error] || 'authorization_error',
+      'code' => 400,
+      'error_message' => params[:error_description] || 'Authorization was denied'
+    }
+
+    Rails.logger.error("Instagram Authorization Error: #{error_info['error_message']}")
+    redirect_to_error_page(error_info)
+  end
+
+  # Centralized method to redirect to error page with appropriate parameters
+  # This ensures consistent error handling across different error scenarios
+  # Frontend will handle the error page based on the error_type
+  def redirect_to_error_page(error_info)
+    redirect_to app_new_instagram_inbox_url(
+      account_id: account_id,
+      error_type: error_info['error_type'],
+      code: error_info['code'],
+      error_message: error_info['error_message']
+    )
+  end
+
+  def create_channel_with_inbox
+    ActiveRecord::Base.transaction do
+      expires_at = Time.current + @long_lived_token_response['expires_in'].seconds
+
+      user_details = fetch_instagram_user_details(@long_lived_token_response['access_token'])
+
+      channel_instagram = Channel::Instagram.create!(
+        access_token: @long_lived_token_response['access_token'],
+        instagram_id: user_details['user_id'].to_s,
+        account: account,
+        expires_at: expires_at
+      )
+
+      account.inboxes.create!(
+        account: account,
+        channel: channel_instagram,
+        name: user_details['username']
+      )
+    end
+  end
+
+  def account_id
+    return unless params[:state]
+
+    verify_instagram_token(params[:state])
+  end
+
+  def oauth_code
+    params[:code]
+  end
+
+  def account
+    @account ||= Account.find(account_id)
+  end
+
+  def provider_name
+    'instagram'
+  end
+end

app/controllers/super_admin/app_configs_controller.rb

@@ -43,6 +43,8 @@ class SuperAdmin::AppConfigsController < SuperAdmin::ApplicationController
                          ['MAILER_INBOUND_EMAIL_DOMAIN']
                        when 'linear'
                          %w[LINEAR_CLIENT_ID LINEAR_CLIENT_SECRET]
+                       when 'instagram'
+                         %w[INSTAGRAM_APP_ID INSTAGRAM_APP_SECRET INSTAGRAM_VERIFY_TOKEN INSTAGRAM_API_VERSION ENABLE_INSTAGRAM_CHANNEL_HUMAN_AGENT]
                        else
                          %w[ENABLE_ACCOUNT_SIGNUP FIREBASE_PROJECT_ID FIREBASE_CREDENTIALS]
                        end

app/controllers/webhooks/instagram_controller.rb

@@ -15,6 +15,9 @@ class Webhooks::InstagramController < ActionController::API
   private
 
   def valid_token?(token)
-    token == GlobalConfigService.load('IG_VERIFY_TOKEN', '')
+    # Validates against both IG_VERIFY_TOKEN (Instagram channel via Facebook page) and
+    # INSTAGRAM_VERIFY_TOKEN (Instagram channel via direct Instagram login)
+    token == GlobalConfigService.load('IG_VERIFY_TOKEN', '') ||
+      token == GlobalConfigService.load('INSTAGRAM_VERIFY_TOKEN', '')
   end
 end