Skip to main content
Loading…

AI Website Widget — Setup & User Guide

  • Updated

SubscriptionFlow IQ Widget — Setup & User Guide

The SubscriptionFlow IQ Widget is an AI-powered chat assistant that you can embed on your website to help visitors explore your subscription plans, book demos, contact support, and more — all in a branded, conversational interface.

This guide walks you through the full setup process, admin panel configuration, and end-user features.

Table of Contents

  1. Overview
  2. Prerequisites
  3. Step 1: Register Your Tenant
  4. Step 2: Embed the Widget on Your Website
  5. Admin Panel
  6. Widget Features for Visitors
  7. FAQ & Troubleshooting

Overview

SubscriptionFlow IQ adds a floating chat widget to your website. When a visitor opens it, they see a branded home screen with your greeting message and quick-action buttons. Clicking Send us a message opens a full AI chat where the assistant can:

  • Show your subscription plans with real pricing from SubscriptionFlow
  • Help visitors filter and compare plans
  • Redirect to your SubscriptionFlow hosted checkout page
  • Display a contact form that emails your support team (via SendGrid)
  • Let visitors book a demo through Calendly
  • Show your company information, business hours, and social links
  • Search your Zendesk Help Center or support page for answers
  • Perform a web search (with the visitor's permission) when no other source has the answer

All conversations, visitor details, and locations are tracked in the Admin Panel, where you can review transcripts, correct AI responses, manage settings, and view reports.

Prerequisites

Before you begin, make sure you have:

  • A SubscriptionFlow account with API credentials (Client ID and Client Secret). You can find these under Administration > API Keys in your SubscriptionFlow dashboard.
  • At least one active Product with one or more Plans configured in SubscriptionFlow.
  • (Optional) A SendGrid account and API key, if you want the contact form feature.
  • (Optional) A Calendly scheduling link, if you want the demo booking feature.

Step 1: Register Your Tenant

Navigate to the widget registration page at:

https://customwidget.subscriptionflow.com/static/register.html

The registration form has the following sections:

1.1 — SubscriptionFlow Credentials

  1. Enter your Subdomain (e.g., acme if your SubscriptionFlow URL is acme.subscriptionflow.com).
  2. Enter your Client ID (UUID format).
  3. Enter your Client Secret.
  4. Click Verify Credentials.

The system will validate your credentials against the SubscriptionFlow API. You will see a green "Verified!" message on success. You must verify before proceeding.

Note: If a tenant with these credentials already exists, the form will pre-populate with your existing configuration so you can update it.

1.2 — Plan Selection

After verification, your plans are automatically fetched from SubscriptionFlow.

  1. Use the search bar to filter plans by name or product.
  2. Check the boxes next to the plans you want visible in the widget.
  3. Use Select All or Clear All for bulk actions.

Tip: If you leave all plans unchecked, the widget will display all active plans from your SubscriptionFlow account.

1.3 — SendGrid Email Configuration (Optional)

If you want the AI to show a contact form that emails your support team:

  1. Enter your SendGrid API Key (starts with SG.).
  2. Enter the From Email address (the sender).
  3. Enter the Recipient Email address (where contact form submissions are delivered).

Note: If you skip this section, the contact form feature will not be available in the widget.

1.4 — Calendly Integration (Optional)

If you want visitors to be able to book a demo directly from the widget:

  1. Enter your Calendly URL (e.g., https://calendly.com/your-name/30min).

1.5 — Widget Branding

  1. Enter a Widget Title (e.g., "Acme Support"). This appears in the chat header.
  2. Enter a Welcome Message (e.g., "Hi there! How can we help?"). This is the greeting visitors see on the home screen.
  3. (Optional) Enter a Logo URL pointing to your company logo image.
  4. Choose a Primary Color and Secondary Color using the color pickers or by entering hex values. These colors are used throughout the widget for buttons, headers, accents, and the chat bubble.

1.6 — Quick Prompts (Optional)

Quick prompts are shortcut buttons that appear on the widget home screen and in the chat view. They help visitors get started quickly.

The form includes four default prompts:

Button Label Message Sent
Show Plans What plans do you offer?
Book a Demo I'd like to book a demo
Contact Support I need to contact support
Business Info Tell me about your company

You can add, remove, or edit prompts as needed. Each prompt has:

  • Button Label — the text the visitor sees.
  • Message Sent on Click — the message that gets sent to the AI when the visitor clicks.

1.7 — Business Information (Optional)

Fill in your company details to enable the Business Info feature in the chat:

  • Company Name and Description
  • Phone, Support Email, Address, Business Hours
  • Website URL and Support/Help Page URL
  • Social Media Links — add platform and URL pairs (e.g., Twitter, LinkedIn)
  • Custom Info Sections — add title and content pairs for any additional information

Tip: The Support/Help Page URL is especially useful. If a visitor asks a question the AI cannot answer from its built-in tools, it will search your support page for relevant articles before falling back to a web search.

1.8 — Submit Registration

Click Register / Update Tenant. On success, you will see a green confirmation message and your embed code.

Step 2: Embed the Widget on Your Website

After registration, copy the generated embed code. It looks like this:

<script
  src="https://customwidget.subscriptionflow.com/static/widget.js"
  data-tenant="your-subdomain"
  data-client-id="your-client-id"
  data-api-url="https://customwidget.subscriptionflow.com"
  data-position="bottom-right">
</script>

Paste this code into your website's HTML, ideally just before the closing </body> tag or inside the <head> section. The widget will appear as a floating chat bubble in the bottom-right (or bottom-left) corner of every page where the script is included.

Configuration Attributes

Attribute Required Description
data-tenant Yes Your SubscriptionFlow subdomain
data-client-id Yes Your API Client ID
data-api-url Yes Widget backend URL
data-position No bottom-right (default) or bottom-left

Note: The widget uses Shadow DOM for style isolation, so it will not conflict with your website's existing CSS.

Admin Panel

The Admin Panel lets you monitor conversations, correct AI responses, manage settings, and view analytics. Access it at:

https://customwidget.subscriptionflow.com/admin

Logging In

  1. Enter your Instance Name (SubscriptionFlow subdomain).
  2. Enter your Client ID.
  3. Enter your Client Secret.
  4. Click Sign in.

You will be authenticated using your SubscriptionFlow API credentials. The session lasts 8 hours.

Dashboard

The Dashboard provides a high-level overview of your widget activity:

Metric Description
Total Conversations All-time conversation count
Today Conversations started today
This Week Conversations started in the last 7 days
Unique Emails Number of distinct visitors who provided their email
New Customers (30d) New SubscriptionFlow customers created via the widget in the last 30 days
Total Messages Total messages exchanged across all conversations
Pending Feedback Number of AI response corrections awaiting guideline synthesis

Conversations

The Conversations page lists all widget conversations with search and pagination.

Table columns:

  • Email — visitor's email address
  • Name — visitor's name (if provided)
  • Location — city and country (detected from IP address)
  • Started — date and time the conversation began
  • Messages — total message count
  • Status — Active or Deleted

Use the search bar to filter conversations by email or name. Click any row to view the full transcript.

Conversation Detail & Feedback

Clicking a conversation opens the detail view, which includes:

Metadata:

  • Visitor email, name, IP address, and location
  • SF Customer ID — a clickable link that opens the customer profile in your SubscriptionFlow dashboard
  • Conversation start time

AI Summary: For conversations with more than 10 messages, the system can generate an AI-powered summary. Click to generate it on demand — summaries are cached after the first generation.

Transcript: The full message history is displayed with:

  • User messages on the right
  • AI responses on the left
  • Widget components (plan cards, contact forms, etc.) shown as labeled preview boxes

Correcting AI Responses:

If the AI gave an incorrect or suboptimal response, you can correct it:

  1. Click "Correct this" on any AI message.
  2. Enter the corrected response — what the AI should have said.
  3. (Optional) Add notes explaining what was wrong.
  4. Click Save feedback.

These corrections are stored and can be used to automatically improve AI behavior via the Guidelines page.

Deleting a Conversation:

Click the Delete button at the top of the conversation detail. This performs a soft delete — the conversation is marked as deleted but retained in the database.

AI Guidelines

Guidelines are custom instructions that control how the AI behaves in your widget. They are injected into every new chat session.

Writing Guidelines:

  1. Enter your instructions in the text editor. For example:
    • "Always recommend the Pro plan for teams larger than 10 people."
    • "Do not discuss competitor pricing."
    • "When asked about refunds, direct the user to the support team."
  2. Click Save Guidelines.

Guidelines take effect immediately for all new chat sessions. Existing active sessions are not affected.

Character limit: 5,000 characters maximum.

Auto-Synthesize from Feedback:

If you have corrected AI responses on the Conversations page, you can use AI to automatically synthesize those corrections into guidelines:

  1. The page shows the number of available feedback items.
  2. Click Auto-synthesize from X feedback item(s).
  3. Confirm the action in the dialog.
  4. The AI will analyze all corrections and generate updated guidelines.

Note: Auto-synthesis rewrites the entire guidelines text. Review the output before relying on it. You can always manually edit after synthesis.

Settings

The Settings page has four tabs:

Widget Branding

  • Widget Title — shown in the chat window header
  • Welcome Message — the greeting on the home screen
  • Primary Color / Secondary Color — used for buttons, headers, accents
  • Logo URL — your company logo
  • Quick Prompts — add, edit, or remove shortcut buttons

Integrations

  • SendGrid API Key — for contact form emails (masked with ******** if already set; leave as-is to keep the existing key)
  • SendGrid From Email — sender address
  • SendGrid Recipient Email — where form submissions go
  • Calendly URL — for demo booking

Business Info

  • Company name, description, phone, support email, address, business hours
  • Website URL and Support Page URL
  • Social media links (platform + URL pairs)
  • Custom info sections (title + content pairs)

Plans

  • Click Fetch Plans from SF to load your current plans from SubscriptionFlow.
  • Use checkboxes to select which plans are visible in the widget.
  • Use the search bar to filter by plan or product name.
  • Use Select All / Clear All for bulk operations.

Tip: If no plans are selected, all active plans will be shown in the widget.

Click Save Settings at the bottom to apply changes. Settings take effect immediately for new chat sessions.

Reports

The Reports page provides 30-day analytics:

Summary Cards:

  • Total Conversations
  • Total Messages
  • Unique Customers
  • New Customers (30d)

Daily Conversations Chart: A horizontal bar chart showing the number of conversations started each day over the last 14 days.

Top Countries: A table showing where your widget visitors are located, sorted by session count.

Widget Features for Visitors

This section describes what your website visitors see and can do with the widget.

Home Screen

When a visitor clicks the chat bubble, they see the home screen:

  • Gradient header — uses your primary and secondary brand colors, displays your welcome message and logo.
  • "Send us a message" card — clicking this opens the chat interface.
  • Quick action links — each quick prompt you configured appears as a clickable link. Clicking one opens the chat and sends the corresponding message immediately.

Chat Interface

The chat interface is where visitors interact with the AI assistant.

Header:

  • Your logo and widget title
  • Expand/collapse button (fullscreen mode)
  • Close button

Messages Area:

  • AI responses appear on the left with a light background
  • Visitor messages appear on the right with your primary color
  • While the AI is thinking, an animated indicator shows rotating status messages (e.g., "Searching relevant information...", "Preparing a detailed response...")

Quick Prompts: If the visitor has no messages yet, quick prompt chips appear in the message area. Clicking one sends that message.

Input Area:

  • Home button — returns to the home screen
  • New conversation button — starts a fresh session
  • Text input — type a message and press Enter (or click send)
  • Send button — sends the typed message

Email Capture: On the visitor's first message, a form appears asking for their name and email address. This is required before the message is sent. The email is used to:

  • Create a customer record in SubscriptionFlow (if one doesn't already exist)
  • Link the conversation to the customer for admin tracking
  • Pre-fill contact forms and booking forms later in the conversation

Note: Returning visitors (same browser session) are not asked again.

Subscription Plans & Checkout

When a visitor asks about plans, pricing, or subscriptions, the AI fetches your real plan data from SubscriptionFlow and displays it in the chat.

Plan Filter: If you have multiple plans, a filter card appears with:

  • Billing frequency chips (e.g., Monthly, Yearly)
  • Price range chips (e.g., Under $25, $25–$50, $50–$100, $100+)
  • A Show Plans button to apply the selected filters

Plan Cards: Each plan card shows:

  • Plan name and description
  • Plan image (if configured)
  • Price with billing interval
  • Feature list
  • Subscribe Now button — opens your SubscriptionFlow hosted checkout page in a new tab

Note: The widget does not process payments directly. Visitors complete their purchase on the SubscriptionFlow hosted checkout page.

Contact Form

When a visitor asks to contact support or send a message, the AI displays a contact form with:

  • Name and Email (pre-filled if already captured)
  • Company and Phone (optional)
  • Message (required)

On submission, the form sends an email to your configured recipient via SendGrid. The visitor sees a success confirmation.

Requirement: This feature requires a valid SendGrid configuration in Settings.

Demo Booking (Calendly)

When a visitor asks to book a demo or schedule a meeting, the AI displays a booking form with:

  • Name, Email, and Company fields (pre-filled if available)
  • A Book Demo button

Clicking the button creates a customer record in SubscriptionFlow (if not already existing) and opens your Calendly scheduling page in a new tab with the visitor's details pre-filled.

Requirement: This feature requires a Calendly URL in Settings.

Business Information

When a visitor asks about your company, services, or contact details, the AI displays a business info card showing the information you configured:

  • Company name, description, and website
  • Phone, email, address, and business hours
  • Social media links
  • Custom info sections

Only fields that have been filled in will appear.

Support Page Search

When a visitor asks a question the AI cannot answer with its built-in tools, it will automatically search your support page or Zendesk Help Center for relevant articles.

  • If your support URL points to a Zendesk Help Center (contains /hc/ in the URL), the widget uses the Zendesk search API to find the top matching articles.
  • For other URLs, it fetches and searches the page content directly.

The AI then synthesizes a natural-language answer from the search results and cites the source.

Requirement: This feature requires a Support/Help Page URL in Settings or Registration.

Web Search

If the AI cannot find an answer from its tools or your support page, it will offer to search the web:

  1. A prompt appears explaining that the AI couldn't find a specific answer.
  2. The visitor must click Search the web to confirm.
  3. Results are fetched and the AI synthesizes an answer.

Important: Web search is never performed silently. It always requires explicit visitor permission. A disclaimer is shown that web results may not be fully accurate.

FAQ & Troubleshooting

Q: The widget isn't appearing on my website.

  • Verify the embed code is placed correctly (before </body> or in <head>).
  • Check that data-tenant and data-client-id match your registration.
  • Open your browser's developer console and look for errors.
  • Ensure the data-api-url points to the correct backend URL.

Q: The AI doesn't show my plans.

  • Make sure you have active plans in your SubscriptionFlow account.
  • Go to Settings > Plans in the Admin Panel and click Fetch Plans from SF to refresh.
  • If you selected specific plans, verify they are still active in SubscriptionFlow.

Q: The contact form isn't available.

  • Ensure you have entered a valid SendGrid API Key, From Email, and Recipient Email in Settings.

Q: The demo booking feature isn't available.

  • Ensure you have entered a valid Calendly URL in Settings.

Q: The AI isn't following my guidelines.

  • Guidelines apply to new sessions only. Active conversations continue with the guidelines they started with.
  • Verify your guidelines were saved successfully on the Guidelines page.
  • Check that your guidelines are within the 5,000-character limit.

Q: Conversations aren't appearing in the Admin Panel.

  • Conversations are only saved after the visitor provides their email. If a visitor opens the widget but never sends a message (and thus never submits the email form), no conversation is recorded.

Q: How do I update my widget branding or settings?

  • Use the Admin Panel > Settings page for ongoing changes.
  • Alternatively, revisit the registration page — existing tenants can re-register to update their configuration.

Q: Can the widget process payments?

  • No. The widget displays plan information and directs visitors to the SubscriptionFlow hosted checkout page where they complete their purchase.

Q: Does the widget work on mobile?

  • Yes. The widget is fully responsive and adapts to mobile screens, expanding to full-screen on smaller devices.

Q: How is visitor location detected?

  • The widget uses IP-based geolocation (via ipinfo.io) to detect the visitor's city and country. This information appears in the Admin Panel on conversation records.

Related articles

Comments

0 comments

Please sign in to leave a comment.