instagram_connect 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '00201119165343bb2f5ab1e16f2894f4944fb452b241068691fe0f0ef2858c0e'
+  data.tar.gz: 6ad13294368d8130252ada941018415855fc935ce32349be419064ab458aa718
+SHA512:
+  metadata.gz: 38c055d770365ef01e4571105a2846bb727bb5f7f7d83ca7dd867ea6cdfadc8c9b70cae2d2005ae68e148aeafbb5799a3be1704d81474ec82979b8464766af2e
+  data.tar.gz: cb99273b4e2e03d40a3f07e75494ced6de868a94a1c99468f7b85d04b981718a6de2aeae734f2b9ce5ccbd308c0aa76442a17529dce63f2ce25b6020892f8d07

data/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [ main ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+
+      - name: Lint code for consistent style
+        run: bundle exec rubocop -f github
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [ "3.2", "3.3", "3.4" ]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run tests
+        run: bundle exec rspec --format progress

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — Unreleased
+
+Initial release. A mountable Rails engine for Instagram over the official Meta Graph API.
+
+### Added
+- Mountable `InstagramConnect::Engine` + `Railtie`, `Configuration` (with `.configure`
+  / `validate!`), `Result` value object, and error hierarchy.
+- Both Meta auth paths as pluggable strategies (`:instagram_login`, `:facebook_login`)
+  with config-symbol dispatch.
+- Graph API `Client` (DMs, comments, publishing, reads, media) returning `Result`.
+- OAuth connect flow (`Connect` service) → encrypted-token `Account`; scheduled
+  `RefreshTokensJob`.
+- HMAC (`X-Hub-Signature-256`) webhook verification + `Ingest` (DMs incl. echoes,
+  comments, postbacks) with an `InboundMessage` dedupe ledger and host hooks
+  (`on_message` / `on_comment` / `on_postback`).
+- `MessagingWindow` (24h standard / 7d human-agent / closed) and an at-most-once
+  `SendMessageJob` that enforces it.
+- Mounted inbox UI: DM inbox + window-aware composer, comment moderation, image
+  publishing; engine layout + overridable views.
+- Generators: `install` (initializer + engine mount + migrations), `views`,
+  `controllers`.
+- `instagram_connect doctor` CLI + configuration preflight.
+- RSpec suite (in-memory sqlite, WebMock-stubbed Graph API, mounted-engine request
+  specs) at 100% line + branch coverage; `rubocop-rails-omakase`; CI on Ruby 3.2–3.4.

data/Gemfile

@@ -0,0 +1,16 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in instagram_connect.gemspec.
+gemspec
+
+gem "puma"
+
+gem "sqlite3"
+gem "rack-test"
+gem "webmock"
+gem "rspec-rails", "~> 8.0"
+gem "factory_bot"
+gem "simplecov", require: false
+
+# Omakase Ruby styling [https://github.com/rails/rubocop-rails-omakase/]
+gem "rubocop-rails-omakase", require: false

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Kshitiz Sinha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2026 Kshitiz Sinha
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,145 @@
+# instagram_connect
+
+A mountable Rails engine that connects your app to **Instagram** over the official
+**Meta Graph API** — receive and reply to DMs and comments in real time via
+HMAC-verified webhooks, publish posts, and manage OAuth tokens. Official API only:
+no reverse-engineered automation, no browser bots, so your account stays safe.
+
+[![CI](https://github.com/kshtzkr/instagram_connect/actions/workflows/ci.yml/badge.svg)](https://github.com/kshtzkr/instagram_connect/actions/workflows/ci.yml)
+
+## Why official-only
+
+Instagram permanently disables real accounts that use reverse-engineered/private-API
+automation, and appeals rarely succeed — you lose the handle, followers, and DM
+history at once. Unlike WhatsApp (where a ban costs a replaceable phone number), an
+Instagram ban costs the whole brand account. This gem only ever speaks the sanctioned
+Graph API.
+
+## Features
+
+- **DMs** — receive inbound messages in real time (webhooks), reply with text within
+  Meta's 24-hour window (extended to 7 days via the human-agent tag).
+- **Comments** — read, reply to, hide/unhide, and delete comments on your posts.
+- **Publishing** — publish image posts (Reels/video/carousel are on the roadmap).
+- **Two auth paths** — `:instagram_login` (no Facebook Page) or `:facebook_login`
+  (linked Page + durable tokens), selected by config. See
+  [docs/auth_paths.md](docs/auth_paths.md).
+- **Mounted inbox UI** — a ready inbox, comment moderation, and publish screens you
+  can restyle to your own design system.
+- **Secure by default** — encrypted tokens at rest, HMAC-verified webhooks.
+
+## Requirements
+
+- Rails ≥ 7.1, Ruby ≥ 3.1
+- Active Storage (media attachments — roadmap) and an Active Job backend
+  (Solid Queue, Sidekiq, …) for webhook ingestion + token refresh
+- Active Record Encryption configured for token storage
+  (`bin/rails db:encryption:init`), or set `config.encrypt_tokens = false`
+- An Instagram **professional** account (Business or Creator)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "instagram_connect"
+```
+
+```bash
+bundle install
+bin/rails g instagram_connect:install   # initializer + engine mount + migrations
+bin/rails db:migrate
+```
+
+The install generator writes `config/initializers/instagram_connect.rb`, mounts the
+engine at `/instagram`, and copies migrations for all five tables.
+
+## Configuration
+
+```ruby
+# config/initializers/instagram_connect.rb
+InstagramConnect.configure do |config|
+  config.auth_path    = :facebook_login   # or :instagram_login
+  config.app_id       = Rails.application.credentials.dig(:instagram_connect, :app_id)
+  config.app_secret   = Rails.application.credentials.dig(:instagram_connect, :app_secret)
+  config.verify_token = Rails.application.credentials.dig(:instagram_connect, :verify_token)
+  config.graph_version = "v21.0"
+
+  # Rails integration
+  config.parent_controller = "ApplicationController"
+  config.authenticate_with = -> { authenticate_user! }          # runs in controller context
+  config.current_user_id_resolver = -> { current_user&.id }     # attributes replies
+  config.after_connect_redirect = "/instagram"
+
+  # Optional host hooks
+  config.on_message = ->(message) { NotifyOpsJob.perform_later(message.id) }
+  config.on_comment = ->(comment) { }
+end
+```
+
+## Connecting an account
+
+Send an operator to `GET /instagram/oauth/start`. They authorize with Meta and are
+redirected back to `config.after_connect_redirect` with a stored, encrypted
+`InstagramConnect::Account`. Schedule the refresh job daily so tokens stay fresh:
+
+```ruby
+# config/recurring.yml (Solid Queue), or your scheduler of choice
+instagram_connect_token_refresh:
+  class: InstagramConnect::RefreshTokensJob
+  schedule: every day at 3am
+```
+
+## Webhooks
+
+Point your Meta app's webhook at `https://<your-host>/instagram/webhooks` and use the
+same `verify_token` you configured. Subscribe the fields you need: `messages`,
+`messaging_postbacks`, `comments`, `mentions`. The engine verifies the
+`X-Hub-Signature-256` HMAC on every delivery and ingests off the request path.
+
+## The inbox UI
+
+Mounted at `/instagram`: a DM inbox with a window-aware reply composer, a comment
+moderation screen, and a publish screen. To restyle to your app's design system:
+
+```bash
+bin/rails g instagram_connect:views        # copies views into app/views/instagram_connect
+bin/rails g instagram_connect:controllers  # (optional) copies controllers to override
+```
+
+## CLI
+
+```bash
+bundle exec instagram_connect doctor   # preflight your configuration
+```
+
+## Meta App Review
+
+Messaging real customers requires Advanced Access, which requires **App Review** and
+**Business Verification**. Until approved, you can only message accounts added as
+testers on your Meta app. The full checklist — permissions per auth path, privacy
+policy, screencasts, common rejection reasons — is in
+[docs/app_review_guide.md](docs/app_review_guide.md).
+
+## Constraints (Meta rules, not the gem's)
+
+- **24-hour window**: you can only reply within 24h of the customer's last message
+  (7 days with the human-agent tag). The gem enforces this and blocks illegal sends.
+- **No cold DMs**: you can't message someone who never messaged you.
+- **Publishing**: 100 API-published posts per rolling 24h; media must be at a public
+  HTTPS URL.
+
+## Testing
+
+```bash
+bundle exec rspec      # in-memory sqlite, WebMock-stubbed Graph API, 100% coverage
+bundle exec rubocop
+```
+
+## Roadmap
+
+See [docs/roadmap.md](docs/roadmap.md) — next up: Turbo realtime broadcasting and
+Active Storage media (inbound fetch + outbound file send).
+
+## License
+
+Released under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/controllers/instagram_connect/application_controller.rb

@@ -0,0 +1,30 @@
+module InstagramConnect
+  # Base controller for the engine's UI (OAuth, inbox, comments, publishing).
+  # Inherits from the host's configured parent controller so it picks up the
+  # host layout, auth helpers, and CSRF handling, then runs the configured
+  # authentication hook. The webhook controller deliberately does NOT inherit
+  # from this — it authenticates by HMAC, not by host session.
+  class ApplicationController < InstagramConnect.configuration.parent_controller.constantize
+    before_action :authenticate_instagram_connect!
+    layout :instagram_connect_layout
+
+    private
+
+    # Use the host's application layout by default (so the inbox looks native),
+    # or the engine's own bundled layout when the host opts out.
+    def instagram_connect_layout
+      InstagramConnect.configuration.inherit_host_layout ? "application" : "instagram_connect/application"
+    end
+
+    def authenticate_instagram_connect!
+      handler = InstagramConnect.configuration.authenticate_with
+      instance_exec(&handler) if handler.respond_to?(:call)
+    end
+
+    def instagram_connect_user_id
+      resolver = InstagramConnect.configuration.current_user_id_resolver
+      resolver.respond_to?(:call) ? instance_exec(&resolver) : nil
+    end
+    helper_method :instagram_connect_user_id
+  end
+end

data/app/controllers/instagram_connect/comments_controller.rb

@@ -0,0 +1,59 @@
+module InstagramConnect
+  # Moderate comments on the account's media: list, reply, hide/unhide, delete.
+  # Moderation calls the Graph API synchronously (fast, operator-facing) and only
+  # updates local state on success.
+  class CommentsController < ApplicationController
+    before_action :set_comment, only: %i[reply hide unhide destroy]
+
+    def index
+      per = InstagramConnect.configuration.default_per_page
+      @page = [ params[:page].to_i, 1 ].max
+      @comments = Comment.order(created_at: :desc).limit(per).offset((@page - 1) * per)
+    end
+
+    def reply
+      moderate(notice: "Reply posted.",
+               call: ->(client) { client.reply_comment(comment_id: @comment.comment_id, text: params[:text].to_s) },
+               on_success: -> { @comment.update!(replied_at: Time.current) })
+    end
+
+    def hide
+      moderate(notice: "Comment hidden.",
+               call: ->(client) { client.hide_comment(comment_id: @comment.comment_id, hidden: true) },
+               on_success: -> { @comment.update!(hidden_at: Time.current) })
+    end
+
+    def unhide
+      moderate(notice: "Comment unhidden.",
+               call: ->(client) { client.hide_comment(comment_id: @comment.comment_id, hidden: false) },
+               on_success: -> { @comment.update!(hidden_at: nil) })
+    end
+
+    def destroy
+      moderate(notice: "Comment deleted.",
+               call: ->(client) { client.delete_comment(comment_id: @comment.comment_id) },
+               on_success: -> { @comment.destroy! })
+    end
+
+    private
+
+    def set_comment
+      @comment = Comment.find(params[:id])
+    end
+
+    def moderate(notice:, call:, on_success:)
+      result = call.call(client_for(@comment))
+      if result.success?
+        on_success.call
+        redirect_to comments_path, notice: notice
+      else
+        redirect_to comments_path, alert: result.error_message
+      end
+    end
+
+    def client_for(comment)
+      account = comment.account
+      Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
+    end
+  end
+end

data/app/controllers/instagram_connect/conversations_controller.rb

@@ -0,0 +1,17 @@
+module InstagramConnect
+  # The DM inbox: a paginated list of threads and a single thread view.
+  class ConversationsController < ApplicationController
+    def index
+      per = InstagramConnect.configuration.default_per_page
+      @page = [ params[:page].to_i, 1 ].max
+      @conversations = Conversation.recent.limit(per).offset((@page - 1) * per)
+    end
+
+    def show
+      @conversation = Conversation.find(params[:id])
+      @messages = @conversation.messages.chronological
+      @conversation.update!(unread_count: 0) if @conversation.unread_count.positive?
+      @window = MessagingWindow.new(last_inbound_at: @conversation.last_inbound_at)
+    end
+  end
+end

data/app/controllers/instagram_connect/messages_controller.rb

@@ -0,0 +1,19 @@
+module InstagramConnect
+  # Composes an outbound reply in a thread and hands it to the send job.
+  class MessagesController < ApplicationController
+    def create
+      conversation = Conversation.find(params[:conversation_id])
+
+      if params[:body].to_s.strip.empty?
+        return redirect_to conversation_path(conversation), alert: "Message can't be blank."
+      end
+
+      message = conversation.messages.create!(
+        direction: "outbound", status: "pending", kind: "dm", source: "manual",
+        body: params[:body], sent_by_id: instagram_connect_user_id
+      )
+      SendMessageJob.perform_later(message.id)
+      redirect_to conversation_path(conversation), notice: "Reply queued."
+    end
+  end
+end

data/app/controllers/instagram_connect/oauth_controller.rb

@@ -0,0 +1,43 @@
+module InstagramConnect
+  # Drives the "Connect Instagram" OAuth flow: redirect to Meta's login dialog,
+  # then exchange the returned code for a stored Account.
+  class OauthController < ApplicationController
+    def start
+      state = SecureRandom.urlsafe_base64(16)
+      session[:instagram_connect_oauth_state] = state
+      url = Auth.for(InstagramConnect.configuration).authorize_url(redirect_uri: callback_url, state: state)
+      redirect_to url, allow_other_host: true
+    end
+
+    def callback
+      return redirect_with("Instagram authorization was declined: #{params[:error]}") if params[:error].present?
+      return redirect_with("OAuth state mismatch — please try connecting again.") if invalid_state?
+
+      Connect.call(code: params[:code], redirect_uri: callback_url, connected_by_id: instagram_connect_user_id)
+      session.delete(:instagram_connect_oauth_state)
+      redirect_to after_connect_path, notice: "Instagram account connected."
+    rescue InstagramConnect::Error => e
+      redirect_with("Could not connect Instagram: #{e.message}")
+    end
+
+    private
+
+    def invalid_state?
+      params[:state].to_s != session[:instagram_connect_oauth_state].to_s
+    end
+
+    def redirect_with(alert)
+      redirect_to after_connect_path, alert: alert
+    end
+
+    # Meta enforces an exact-match redirect URI. Hosts can pin it via
+    # config.redirect_uri; otherwise the engine's own callback URL is used.
+    def callback_url
+      InstagramConnect.configuration.redirect_uri.presence || url_for(action: :callback, only_path: false)
+    end
+
+    def after_connect_path
+      InstagramConnect.configuration.after_connect_redirect
+    end
+  end
+end

data/app/controllers/instagram_connect/posts_controller.rb

@@ -0,0 +1,40 @@
+module InstagramConnect
+  # Publishing: list the account's own media and publish a new image post
+  # (container -> publish). Reels/video/carousel are a documented follow-on.
+  class PostsController < ApplicationController
+    before_action :require_account
+
+    def index
+      client = client_for(@account)
+      @media = Array(client.list_media.data["data"])
+      @quota_usage = client.publishing_limit.data.dig("data", 0, "quota_usage")
+    end
+
+    def new
+    end
+
+    def create
+      client = client_for(@account)
+      container = client.create_media_container(image_url: params[:image_url], caption: params[:caption])
+      return redirect_to new_post_path, alert: container.error_message if container.failure?
+
+      published = client.publish_media(creation_id: container.id)
+      if published.success?
+        redirect_to posts_path, notice: "Published to Instagram."
+      else
+        redirect_to new_post_path, alert: published.error_message
+      end
+    end
+
+    private
+
+    def require_account
+      @account = Account.active.first
+      redirect_to conversations_path, alert: "Connect an Instagram account first." if @account.nil?
+    end
+
+    def client_for(account)
+      Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
+    end
+  end
+end

data/app/controllers/instagram_connect/webhooks_controller.rb

@@ -0,0 +1,54 @@
+module InstagramConnect
+  # Receives Meta webhooks. Inherits ActionController::Base directly (not the
+  # engine ApplicationController) so it bypasses the host's session auth and
+  # CSRF, and instead authenticates the GET handshake by verify_token and the
+  # POST body by HMAC signature. ACKs fast and hands persistence to a job.
+  class WebhooksController < ActionController::Base
+    skip_forgery_protection
+
+    # Rails 8 ships `rate_limit`; on 7.1 it's absent, so guard it. The false
+    # branch can't execute under a Rails 8 test run.
+    # simplecov:disable
+    if respond_to?(:rate_limit)
+      rate_limit to: 300, within: 1.minute, by: -> { request.remote_ip }, name: "instagram_connect_webhook"
+    end
+    # simplecov:enable
+
+    # GET — Meta's subscription verification handshake.
+    def verify
+      if valid_verification?
+        render plain: params["hub.challenge"].to_s
+      else
+        head :forbidden
+      end
+    end
+
+    # POST — a batch of events. Verify the signature, then enqueue ingestion.
+    def receive
+      unless SignatureVerifier.valid?(raw_body: request.raw_post, signature: request.headers["X-Hub-Signature-256"])
+        return head :unauthorized
+      end
+
+      payload = parse_json(request.raw_post)
+      return head :bad_request if payload.nil?
+
+      IngestJob.perform_later(payload)
+      head :ok
+    end
+
+    private
+
+    def valid_verification?
+      token = InstagramConnect.configuration.verify_token.to_s
+      return false if token.empty?
+
+      params["hub.mode"] == "subscribe" && params["hub.verify_token"].to_s == token
+    end
+
+    def parse_json(raw)
+      JSON.parse(raw.to_s)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/app/jobs/instagram_connect/application_job.rb

@@ -0,0 +1,4 @@
+module InstagramConnect
+  class ApplicationJob < ActiveJob::Base
+  end
+end

data/app/jobs/instagram_connect/ingest_job.rb

@@ -0,0 +1,11 @@
+module InstagramConnect
+  # Persists a verified webhook payload off the request path so the controller
+  # can ACK Meta immediately.
+  class IngestJob < ApplicationJob
+    queue_as :default
+
+    def perform(payload)
+      Ingest.call(payload: payload)
+    end
+  end
+end

data/app/jobs/instagram_connect/refresh_tokens_job.rb

@@ -0,0 +1,22 @@
+module InstagramConnect
+  # Refreshes access tokens for active accounts before they expire. Schedule it
+  # daily (e.g. via Solid Queue recurring tasks). One account's failure never
+  # aborts the batch. Accounts on a non-expiring path (Facebook-Login) simply
+  # keep their token — refresh_token there is a no-op.
+  class RefreshTokensJob < ApplicationJob
+    queue_as :default
+
+    DEFAULT_WINDOW = 7 * 24 * 60 * 60 # seconds
+
+    def perform(within: DEFAULT_WINDOW)
+      threshold = Time.current + within
+      Account.active.token_expiring_before(threshold).find_each do |account|
+        account.refresh_access_token!
+      rescue StandardError => e
+        InstagramConnect.configuration.logger&.error(
+          "[instagram_connect] token refresh failed for account #{account.id}: #{e.message}"
+        )
+      end
+    end
+  end
+end

data/app/jobs/instagram_connect/send_message_job.rb

@@ -0,0 +1,44 @@
+module InstagramConnect
+  # Sends one pending outbound Message via the Graph API, exactly once. Claims
+  # the row (pending -> sending) with an atomic UPDATE so a duplicate enqueue
+  # can't double-send, then enforces Meta's messaging window — auto-applying the
+  # HUMAN_AGENT tag once the standard 24h window has passed.
+  class SendMessageJob < ApplicationJob
+    queue_as :default
+
+    def perform(message_id)
+      claimed = Message.where(id: message_id, status: "pending")
+                       .update_all(status: "sending", updated_at: Time.current)
+      return unless claimed == 1
+
+      message = Message.find(message_id)
+      tag = MessagingWindow.new(last_inbound_at: message.conversation.last_inbound_at).send_tag
+
+      if tag == :blocked
+        return fail_message(message, "outside_messaging_window",
+                            "The reply window has closed; the customer must message again.")
+      end
+
+      deliver(message, tag)
+    end
+
+    private
+
+    def deliver(message, tag)
+      conversation = message.conversation
+      account = conversation.account
+      client = Client.new(access_token: account.access_token, ig_user_id: account.ig_user_id)
+      result = client.send_text(recipient_id: conversation.igsid, text: message.body.to_s, tag: tag)
+
+      if result.success?
+        message.update!(status: "sent", ig_message_id: result.id, message_tag: tag)
+      else
+        fail_message(message, result.error_code&.to_s, result.error_message)
+      end
+    end
+
+    def fail_message(message, reason, error)
+      message.update!(status: "failed", failure_reason: reason, error_message: error)
+    end
+  end
+end