Assistants Module - Complete Documentation

Introduction

The Assistants Module is the core feature of the FineGuide AI platform. An Assistant is an Agentic AI agent that can be embedded on websites, integrated with messaging platforms, and customized to serve specific business needs. Unlike traditional chatbots, FineGuide Assistants use multiple AI models working together to understand intent, generate intelligent responses, and execute real actions.

Each Assistant is a self-contained AI agent with its own:

Personality and behavior settings
Knowledge base (Learning Context)
Visual appearance and branding
External integrations and actions
Conversation analytics and history

Assistants are organization-scoped, meaning each organization can have multiple assistants configured for different purposes (e.g., customer support, sales, FAQ handling).

Module Structure Overview

The Assistant configuration is organized into three main sections:

General Section

Tab	Purpose
Persona	Define the assistant's identity, personality traits, and core settings
Features	Configure behavioral features like lead collection, context restrictions, and suggested questions
Appearance	Customize the visual appearance of the chat widget

Knowledge Section

Tab	Purpose
Learning Context	Train the assistant using websites, files, FAQs, and web search
Actions	Define executable HTTP actions the assistant can perform
Conversations	View analytics and conversation history
Session Variables	Configure dynamic variables that persist during conversations

Advanced Section

Tab	Purpose
Integrations	Get embed code and integration links
Connect Apps	Connect to third-party platforms (Slack, Discord, WhatsApp, etc.)
Webhooks	Configure HTTP callbacks for conversation events

1. Assistant Persona

Purpose

The Persona tab defines the fundamental identity and personality of your AI assistant. These settings influence how the assistant communicates, what role it plays, and how it presents itself to users.

Configuration Options

Basic Information

Name: The display name of the assistant shown to users during conversations
Company/Organization: The business entity the assistant represents
Role: The functional purpose of the assistant (Customer Support, Sales Agent, Technical Support, etc.)
Avatar: The profile image displayed in the chat interface
Welcome Message: The initial greeting shown when a user opens the chat

AI Model Settings

AI System: FineGuide's agentic AI automatically orchestrates multiple models for optimal responses
Voice Model: For voice-enabled features, selects the text-to-speech voice
Conversational Model: For real-time voice conversations

Personality Settings

These sliders control the assistant's communication style:

Setting	Description	Options
Manner of Speaking	The tone and style of responses	Normal, Friendly, Formal, Concise
Persuasiveness	How assertive or suggestive the assistant is	Assertive, Neutral, Passive
Verbosity	Level of detail in responses	Normal, Verbose, Concise

Follow-up Questions

When enabled, the assistant will ask clarifying questions to better understand user needs and provide more accurate responses.

Custom Prompts

An advanced text field where you can add custom instructions that will be included in the assistant's system prompt. This allows fine-tuning behavior for specific use cases without modifying the core personality settings.

Example Use Cases:

"Always mention our 30-day money-back guarantee"
"When discussing pricing, emphasize value over cost"
"If asked about competitors, focus on our unique advantages"

Notes

An internal notes field for your team to document the assistant's purpose, deployment location, or any other relevant information. This is not visible to end users.

2. Features (Customization)

Purpose

The Features tab controls behavioral aspects that affect how the assistant interacts with users and what capabilities are enabled.

Response Limitations

Restrict to Context

When enabled, the assistant will only answer questions based on information from its Learning Context. If asked something outside its knowledge base, it will provide a configured fallback response.

Use Cases:

Prevent the assistant from answering off-topic questions
Ensure responses stay within company-approved information
Maintain accuracy by limiting speculation

Out of Context Answer: A customizable message shown when the assistant cannot answer a question (e.g., "I'm sorry, but that's outside my area of expertise. Let me connect you with our team.")

Lead Collection

Lead collection allows the assistant to intelligently gather contact information from users during natural conversation.

Settings:

Enable/Disable: Toggle lead collection
Lead Strictness: Controls how aggressively the assistant requests contact information
- Level 1 (Low): Only collects info when naturally offered
- Level 2 (Medium): Gently prompts for info at appropriate moments
- Level 3 (High): Actively requests contact information

Collected Information:

Name
Email
Phone number
Company
Custom fields based on conversation

Chat Images

When enabled, users can send images in their messages. The assistant can then analyze and respond to image content using vision capabilities.

Chat Attachments

Allows users to upload files (PDFs, documents, etc.) during conversations for the assistant to reference.

Ticket Permissions

Configure when support tickets can be created:

Setting	Description
User Can Create Tickets	Allows users to manually request human support
Assistant Can Create Tickets	Enables the assistant to automatically escalate conversations

Tickets appear in the Tickets section of the platform for your team to handle.

3. Appearance

Purpose

The Appearance tab controls the visual presentation of the chat widget embedded on websites. These settings ensure the assistant matches your brand identity.

Theme Settings

Customize colors for both light and dark modes:

Element	Description
Primary Color	Main accent color for buttons and highlights
Background Color	Chat window background
Text Color	Message and UI text
User Message Background	Color of user message bubbles
Assistant Message Background	Color of assistant message bubbles

Language & Template

Language: Sets the UI language for the chat widget (English, Spanish, French, German, etc.)
Template: Visual layout style
- Modern: Rounded corners, contemporary design
- Traditional: Classic chat interface with subtle rounding
- Minimalist: Clean, no-border design

Header Settings

Close Button: Show/hide the close button in the chat header
Full Screen Button: Allow users to expand the chat to full screen

Premium Features

Hide Widget Footer: Remove the "Powered by FineGuide" branding (requires premium subscription)

The icon displayed in the chat bubble button. Options:

Use the assistant's avatar
Upload a custom image
Select from preset icons

Visual effects applied to the chat bubble:

Default: Static button
Pulse: Gentle pulsing animation
Bounce: Subtle bounce effect
Glow: Glowing effect to attract attention

Adjust the size of the chat bubble button (60px to 100px diameter).

Right: Chat bubble in bottom-right corner (default)
Left: Chat bubble in bottom-left corner

Optional text label displayed next to the chat bubble (e.g., "Chat with us!")

4. Learning Context

Purpose

The Learning Context is the knowledge base that powers the assistant's responses. By training the assistant on your content, it can provide accurate, contextual answers specific to your business.

Context Types

Website Links

Train the assistant by crawling web pages:

Configuration:

URL: The starting URL to crawl
Include Subpaths: Crawl all pages under the URL path
Follow Links: Discover and crawl linked pages
Sync Frequency: How often to re-crawl for updates
- Off: One-time crawl
- Daily: Re-crawl every 24 hours
- Weekly: Re-crawl every 7 days

Processing:

URLs are added to a crawl queue
Pages are fetched and processed
Content is chunked and indexed
Status updates show progress (Scheduled → In Progress → Completed)

Best Practices:

Start with key pages rather than entire sites
Use sync frequency for content that updates regularly
Monitor the size limit to avoid exceeding your plan's context quota

Files

Upload documents to add to the knowledge base:

Supported Formats:

PDF documents
Word documents (.doc, .docx)
Text files (.txt)
Markdown files (.md)
CSV/Excel spreadsheets
PowerPoint presentations

Features:

Drag-and-drop upload
Folder organization
Bulk upload/delete
Enable/disable individual files
Re-sync to reprocess files

Web Search

Enable real-time web search capabilities:

Settings:

Enable Web Search: Allow the assistant to search the internet
Search Providers: Configure which search engines to use
Include Domains: Limit search to specific domains
Exclude Domains: Block certain domains from results

Use Cases:

Answer questions about recent events
Provide up-to-date information
Supplement static knowledge base

FAQ (Custom Answers)

Define specific question-answer pairs for guaranteed consistent responses:

Structure:

Question: The user query to match
Answer: The exact response to provide

Benefits:

Override AI-generated responses for specific topics
Ensure compliance with legal or regulatory requirements
Provide consistent answers to frequently asked questions

Example:

Q: "What are your business hours?"
A: "We're open Monday-Friday, 9 AM to 6 PM EST. Weekend support is available via email."

Test Context

Evaluate the assistant's knowledge with test questions:

Features:

Add test questions
See the assistant's actual responses
Track evaluation status
Batch re-evaluate after context updates

Workflow:

Add questions you expect users to ask
Run evaluation to see responses
Review and adjust context as needed
Re-evaluate to verify improvements

Import (Notion)

Import pages directly from Notion workspaces:

Setup:

Connect your Notion account
Select pages to import
Enable auto-sync to keep content updated

5. Actions

Purpose

Actions are executable HTTP requests that the AI assistant can trigger during conversations. This transforms the assistant from a passive Q&A bot into an active agent that can interact with external systems.

What is an Action?

An Action is essentially a configurable HTTP request that the assistant can decide to execute based on the conversation context. When a user's request requires real-time data or an external operation, the assistant can invoke the appropriate action.

Core Components:

Name: Unique identifier (snake_case, e.g., check_order_status)
Description: Explains what the action does (helps the AI decide when to use it)
Method: HTTP method (GET, POST, PUT, DELETE, PATCH)
URL: The API endpoint to call
Headers: Request headers (authentication, content-type)
Parameters: Dynamic values the AI extracts from conversation
Body: Request payload for POST/PUT requests

Action Schema

json

{
  "name": "get_order_status",
  "description": "Retrieves the current status of a customer order using their order number",
  "method": "get",
  "url": "https://api.yourstore.com/orders/{{order_id}}",
  "headers": {
    "Authorization": "Bearer {{api_key}}",
    "Content-Type": "application/json"
  },
  "content-type": "application/json",
  "parameters": [
    {
      "name": "order_id",
      "type": "string",
      "required": true,
      "location": "path",
      "description": "The order ID provided by the customer"
    }
  ],
  "body": []
}

Parameter Locations

Location	Description	Example
path	Embedded in URL	`/orders/`
query	URL query string	`?status=`
body	Request body	`{"email": ""}`
headers	Request headers	`Authorization:`

Creating Actions

Manual Creation

Click "Create Action"
Enter action name and description
Configure method, URL, and headers
Define parameters with descriptions
Set up request body if needed
Save and test

Import from cURL

Paste a cURL command and automatically generate an action:

bash

curl -X POST https://api.example.com/send-email \
  -H "Authorization: Bearer token123" \
  -d '{"to": "[email protected]", "subject": "Hello"}'

Import from n8n

Connect your n8n instance to import workflows as actions:

Configure n8n connection in Settings
Browse available workflows
Import selected workflows as actions

Action Templates

Pre-built templates for popular services:

Service	Actions
Shopify	Search products, check availability, order status, product recommendations
WooCommerce	Get products, order lookup
AfterShip	Track package across 700+ carriers
Mailgun	Send emails
Twilio	Send SMS messages
HubSpot	Create CRM contacts
Trello	Create cards

Testing Actions

Select an action from the list
Click the "Test" button
Enter test values for parameters
Execute and view the response
Verify the output matches expectations

Best Practices

Write Clear Descriptions: The AI uses descriptions to decide when to invoke actions
Handle Errors Gracefully: The AI will communicate failures to users
Limit Scope: Create focused actions rather than complex multi-purpose ones
Secure Credentials: Use environment variables for API keys
Test Thoroughly: Verify actions work before enabling them

6. Session Variables

Purpose

Session Variables provide contextual memory for conversations. They are dynamic key-value pairs that the assistant maintains throughout a session, allowing it to track important details, preferences, and decisions made during the discussion.

How Session Variables Work

During a conversation, the assistant can:

Detect relevant information from user messages
Store it as session variables
Reference variables in subsequent responses
Update values as the conversation progresses

Benefits

Benefit	Description
Personalization	Remember user-specific data (name, preferences, goals)
Continuity	Maintain conversation state across messages
Efficiency	Avoid asking the same questions repeatedly
Conditional Logic	Trigger specific workflows based on variable values

Configuration

Variable Schema

Define what variables the assistant should track:

json

{
  "user_name": {
    "type": "string",
    "description": "The user's name"
  },
  "product_interest": {
    "type": "string",
    "description": "The product the user is interested in"
  },
  "budget": {
    "type": "number",
    "description": "The user's budget in USD"
  },
  "is_returning_customer": {
    "type": "boolean",
    "description": "Whether the user has purchased before"
  }
}

Example Conversation Flow

User: "Hi, I'm looking for a laptop for video editing"
Assistant detects: product_interest = "laptop", use_case = "video editing"
User: "My budget is around $1500"
Assistant updates: budget = 1500
Assistant responds: Using the stored context to recommend specific laptops

Webhook Integration

Session variables can trigger webhooks when updated, allowing external systems to react to conversation progress. See the Webhooks section for VARIABLE_UPDATE events.

7. Integrations

Purpose

The Integrations tab provides everything needed to embed the assistant on websites and share direct links.

Embed Code

Copy-paste JavaScript code to add the chat widget to any website:

html

<script
  src="https://client.fineguide.ai/widget.js"
  data-bot-id="YOUR_BOT_ID"
  async
></script>

Customization Options:

Auto-open on page load
Custom theme override
Position adjustment
Event callbacks

Direct Link

A shareable URL that opens the assistant in a full-page chat interface:

https://client.fineguide.ai/{bot_id}

Use for:

Email signatures
QR codes
Social media links
Customer support portals

Iframe Embed

Embed the chat as an iframe within your application:

html

<iframe
  src="https://client.fineguide.ai/{bot_id}"
  width="400"
  height="600"
  frameborder="0"
></iframe>

8. Connect Apps

Purpose

Connect Apps allows the assistant to communicate through third-party messaging platforms, extending its reach beyond your website.

Supported Platforms

Slack

Deploy your assistant as a Slack bot:

Features: Respond to DMs, participate in channels
Setup: OAuth connection through Slack App Directory
Use Cases: Internal helpdesk, team Q&A, employee onboarding

Discord

Add your assistant to Discord servers:

Features: Respond to mentions, DM support
Setup: Discord bot token connection
Use Cases: Community support, gaming support, server moderation

Enable WhatsApp Business conversations:

Features: Two-way messaging, template messages, media support
Setup: WhatsApp Business API connection
Requirements: Verified business, approved phone number
Template Manager: Create and manage WhatsApp message templates

Deploy a Telegram bot:

Features: Direct messages, group chat support
Setup: BotFather token configuration
Use Cases: Customer support, notifications, community engagement

Facebook Messenger

Respond to Facebook page messages:

Features: Page inbox integration, automated responses
Setup: Facebook page connection via OAuth
Requirements: Facebook Business page

Instagram

Handle Instagram DMs and comments:

Features: Direct message responses, comment replies
Setup: Instagram Business account + Facebook page connection
Requirements: Professional Instagram account linked to Facebook

AmoCRM

Sync conversations with AmoCRM:

Features: Lead creation, conversation logging, CRM integration
Setup: OAuth connection to AmoCRM account
Use Cases: Sales pipeline integration, lead management

Kommo

Connect with Kommo CRM:

Features: Similar to AmoCRM integration
Setup: OAuth authentication
Use Cases: CRM synchronization, sales tracking

Integration Rules

Configure conditional behaviors for connected apps:

Trigger actions based on conversation events
Route conversations to specific pipelines
Update CRM records automatically
Send notifications on specific conditions

9. Webhooks

Purpose

Webhooks allow external systems to receive real-time notifications when events occur in conversations. This enables integration with CRMs, analytics platforms, custom applications, and automation tools.

How Webhooks Work

Configure a webhook URL endpoint
Select which events to subscribe to
When events occur, FineGuide sends HTTP POST requests to your URL
Your system processes the event data

Available Events

Event	Description	Payload Includes
`MESSAGE`	New message sent or received	Message content, sender, timestamp
`SESSION_OPEN`	Conversation started	Session ID, user info, channel
`SESSION_CLOSED`	Conversation ended	Session summary, duration
`TICKET`	Support ticket created	Ticket details, conversation context
`CREATE_LEAD`	Lead information captured	Lead data, source conversation
`RATE_MESSAGE`	User rated a message	Rating value, message ID
`VARIABLE_UPDATE`	Session variable changed	Variable name, old/new values

Webhook Configuration

Endpoint Settings

URL: Your HTTPS endpoint that will receive events
Events: Select which events to send
Custom Header: Optional authentication header (name and value)

Request Format

Webhook requests are sent as HTTP POST with JSON body:

json

{
  "event": "MESSAGE",
  "timestamp": "2024-01-15T10:30:00Z",
  "botId": "abc123",
  "sessionId": "session_xyz",
  "data": {
    "content": "Hello, I need help with my order",
    "role": "user",
    "metadata": {}
  }
}

Security

Use HTTPS endpoints only
Add custom authentication headers
Validate webhook signatures
Implement idempotency for duplicate handling

Use Cases

CRM Integration: Create leads in Salesforce when contact info is collected
Analytics: Send conversation data to analytics platforms
Alerting: Notify team when tickets are created
Automation: Trigger workflows in Zapier or Make
Custom Applications: Sync conversation data with internal systems

10. Conversations Analytics

Purpose

The Conversations section within an Assistant provides detailed analytics and access to conversation history, helping you understand how the assistant is performing and how users interact with it.

Performance Analytics

Key Metrics

Total Conversations: Number of chat sessions
Total Messages: Messages exchanged
Average Session Duration: How long users engage
Resolution Rate: Conversations resolved without escalation
User Satisfaction: Based on message ratings

Charts and Visualizations

Conversation volume over time
Peak usage hours
Message distribution (user vs assistant)
Topic categorization

Conversation History

Browse and search past conversations:

Features:

Search by content or user info
Filter by date range
Filter by channel (web, WhatsApp, etc.)
View full conversation transcripts
See session variables captured
Export conversation data

Conversation Details:

Complete message history
Timestamps for each message
Actions executed during conversation
Lead information collected
Session duration and outcome

Summary

The Assistants Module is a comprehensive toolkit for creating, training, and deploying Agentic AI assistants. By leveraging the various configuration options across Persona, Features, Appearance, Learning Context, Actions, Session Variables, Integrations, Connect Apps, and Webhooks, you can build intelligent assistants that:

Represent your brand with customized personality and appearance
Answer accurately using your own knowledge base
Take action by executing external API calls
Integrate seamlessly with messaging platforms and business tools
Provide insights through detailed analytics and conversation history

For specific implementation details, refer to the individual documentation pages for each tab and feature.

Assistants Module - Complete Documentation ​

Introduction ​

Module Structure Overview ​

General Section ​

Knowledge Section ​

Advanced Section ​

1. Assistant Persona ​

Purpose ​

Configuration Options ​

Basic Information ​

AI Model Settings ​

Personality Settings ​

Follow-up Questions ​

Custom Prompts ​

Notes ​

2. Features (Customization) ​

Purpose ​

Suggested Questions ​

Response Limitations ​

Restrict to Context ​

Lead Collection ​

Chat Images ​

Chat Attachments ​

Ticket Permissions ​

3. Appearance ​

Purpose ​

Theme Settings ​

Language & Template ​

Header Settings ​

Premium Features ​

Widget Appearance ​

Widget Image ​

Widget Effects ​

Widget Size ​

Widget Position ​

Widget Bubble Label ​

4. Learning Context ​

Purpose ​

Context Types ​

Website Links ​

Files ​

Web Search ​

FAQ (Custom Answers) ​

Test Context ​

Import (Notion) ​

5. Actions ​

Purpose ​

What is an Action? ​

Action Schema ​

Parameter Locations ​

Creating Actions ​

Manual Creation ​

Import from cURL ​

Import from n8n ​

Action Templates ​

Testing Actions ​

Best Practices ​

6. Session Variables ​

Purpose ​

How Session Variables Work ​

Benefits ​

Configuration ​

Variable Schema ​

Example Conversation Flow ​

Webhook Integration ​

7. Integrations ​

Purpose ​

Embed Code ​

Direct Link ​

Iframe Embed ​

8. Connect Apps ​

Purpose ​

Supported Platforms ​

Slack ​

Discord ​

WhatsApp ​

Telegram ​

Facebook Messenger ​

Instagram ​

AmoCRM ​

Assistants Module - Complete Documentation

Introduction

Module Structure Overview

General Section

Knowledge Section

Advanced Section

1. Assistant Persona

Purpose

Configuration Options

Basic Information

AI Model Settings

Personality Settings

Follow-up Questions

Custom Prompts

Notes

2. Features (Customization)

Purpose

Suggested Questions

Response Limitations

Restrict to Context

Lead Collection

Chat Images

Chat Attachments

Ticket Permissions

3. Appearance

Purpose

Theme Settings

Language & Template

Header Settings

Premium Features

Widget Appearance

Widget Image

Widget Effects

Widget Size

Widget Position

Widget Bubble Label

4. Learning Context

Purpose

Context Types

Website Links

Files

Web Search

FAQ (Custom Answers)

Test Context

Import (Notion)

5. Actions

Purpose

What is an Action?

Action Schema

Parameter Locations

Creating Actions

Manual Creation

Import from cURL

Import from n8n

Action Templates

Testing Actions

Best Practices

6. Session Variables

Purpose

How Session Variables Work

Benefits

Configuration

Variable Schema

Example Conversation Flow

Webhook Integration

7. Integrations

Purpose

Embed Code

Direct Link

Iframe Embed

8. Connect Apps

Purpose

Supported Platforms

Slack

Discord

WhatsApp

Telegram

Facebook Messenger

Instagram

AmoCRM