Instagram Widget - Setup & User Guide

Platform: Web (FastAPI backend, Instagram DM)

Audience: Business owners, customer support teams, and implementation partners

Purpose: End‑to‑end guide for using the Insta‑Chatbot backend to power AI assistants on your website and Instagram, manage tenants, and understand how chats and plans are handled.

1. Overview

Insta‑Chatbot is the backend service that powers SubscriptionFlow’s AI assistant on your website and Instagram Direct Messages (DMs). The backend connects your SubscriptionFlow workspace, Instagram business accounts, and AI providers into a unified assistant. Once configured, customers can ask about pricing, browse real subscription plans, and request support.

The system is multi‑tenant, allowing a single deployment to serve multiple SubscriptionFlow tenants with isolated data, branding, and credentials.

2. Key Features

• Subscription Plan Browsing: Real-time fetching of plans from your SubscriptionFlow tenant.
• Instagram DM Bot: Handles user onboarding, answers questions, and shares booking links.
• Multi‑Tenant Support: Ensures tenant data isolation for plans, customers, and messages.
• Chat Logging: All messages are recorded for diagnostics and analytics.

3. Getting Started

Prerequisites

• A SubscriptionFlow workspace with OAuth credentials (Client ID & Secret).
• A MySQL database for storing tenant records and chat logs.
• An Instagram Business account with messaging enabled.
• A server environment (Linux, Docker) to run the FastAPI backend.

4. Onboarding – Tenant & Account Setup

4.1 What a Tenant Stores

• SubscriptionFlow: Subdomain, Client ID, and Client Secret.
• Instagram: instagram_business_id, and page_access_token or login_access_token.
• Integrations: Calendly URL for meeting bookings.

4.2 Tenant Onboarding Flow

1. Collect Info: Gather all SubscriptionFlow and Meta credentials.
2. Create Record: Use the Insta Chatbot Tenant Dashboard to register a new tenant.
3. Verify Webhook: Configure the Meta webhook URL to point to your backend.
4. Test: Send a message to the bot to confirm tenant resolution and plan fetching.

5. Instagram Bot – DM Assistant

5.1 Onboarding New Users

When a new user messages the account, the bot:

1. Welcomes them and asks for their First Name, Last Name, and Email.
2. Creates a corresponding Customer Record in SubscriptionFlow.
3. Opens a session to allow the user to use plan-browsing tools.

5.2 Normal Conversation

Once onboarded, users can ask about specific plans or request support. The bot provides direct subscribe links and business contact details.

6. Multi‑Tenant Behaviour

The backend resolves the correct tenant based on the instagram_business_id. This ensures that plan data and customer records remain strictly within the correct SubscriptionFlow workspace.

7. Chat Logging & Analytics

The backend records the tenant_client_id, instagram_sender_id, session_id, and message content. Merchants can use these logs to audit conversations, monitor support quality, and track which plans are most frequently discussed.

8. Setup Guide (Step‑by‑Step Summary)

Insta-Chatbot Setup Guide: Instagram Integration & Tenant Onboarding

This guide provides a professional, step-by-step walkthrough for configuring your Insta-Chatbot backend, connecting it to Meta's developer platform, and onboarding new tenants.

Phase 1: Meta Developer Portal Configuration

To enable the chatbot on Instagram, you must first configure your application within the Meta for Developers portal.

1. Access Your Application: Log in to the portal 
   
   
   Select your primary application (e.g., SubscriptionFlow). Connect the facebook page with your app 
   

    

2. Configure Use Case:

Navigate to the Use cases section in the left-hand sidebar.

Select Customize use case and then click on API setup with Instagram login

3. Generate Access Tokens:

Navigate to Step 2: Generate access tokens.

Click Add Instagram account and select Continue to assign a tester role or connect a professional account.

Enter Credentials: Log in to the target Instagram account 

4. Activate Webhooks:

• Once the account is connected, ensure the Webhook Subscription toggle is set to On

Finalize Token Acquisition:

• Click Generate token for the connected account
  

Copy and securely save the generated Login Access Token.

Note: You must also generate a Page Access Token separately using the Graph API Explorer.

Phase 2: Tenant Onboarding

Once your Meta credentials are ready, use the Insta-Chatbot Tenant Dashboard to register the new business entity.


Initiate Registration: Open the dashboard and click Go to new tenant form.

Enter Tenant Details: Input the following required information:

• SubscriptionFlow Credentials: Subdomain, Client ID, and Client Secret.
• Instagram Configuration: Business ID, Page Access Token, and Login Access Token.
• Integrations : Calendly URL for automated meeting bookings.

Activate: Ensure the Tenant is active checkbox is selected and click Save tenant.

Phase 3: Bot Capabilities & User Experience

Once onboarded, the bot is immediately active for new Direct Messages (DMs).

• Automated Onboarding: When a new user messages the account, the bot automatically collects their First Name, Last Name, and Email to create a matching Customer Record in SubscriptionFlow.
• Plan Browsing: Utilizing MCP tools, the bot fetches real-time subscription plans from the tenant's workspace and displays them directly in the DM.
• Direct Conversions: Users can access direct Checkout Pages or book Demo Meetings via Calendly without leaving Instagram.
• Support & Info: The bot provides comprehensive business information and a direct line to the support team

9. Support & Troubleshooting

9.1 Common Issues

• Token Expired: (Code 190) Generate a new token in the Meta Developer portal and update the tenant dashboard.
• Tenant Not Recognized: Ensure the instagram_business_id in the database matches your Meta setup.
• Incorrect Plans: Check that the sf_subdomain and OAuth keys point to the correct workspace.