Skip to main content

Chatbot Overview

Embed a powerful AI chatbot widget on your website to engage visitors, answer questions, and capture leads—all powered by your custom workflows. Create unlimited chatbot configurations, customize appearance, and track every conversation.

Why Use Chatbot?​

1. 24/7 Customer Support

  • Instant responses to visitor questions
  • No waiting for human agents
  • Always available on your website
  • Automated workflow execution

2. Lead Generation

  • Capture visitor information
  • Qualify leads automatically
  • Route to sales team
  • Integrate with CRM

3. Brand Customization

  • Match your brand colors and style
  • Custom welcome messages
  • Company logo display
  • Light and dark themes

4. Smart Conversations

  • AI-powered responses via workflows
  • Suggested questions for easy navigation
  • Section-based question organization
  • Full conversation history

5. Voice Capabilities

  • Voice input for messages
  • Voice call mode (phone-like experience)
  • Voice-only widget option
  • Real-time transcription

Key Features​

Widget Customization​

Appearance Options:

  • Position: Bottom-right or bottom-left
  • Theme: Light or dark mode
  • Primary Color: Custom brand color (hex code)
  • Button Text: Customizable call-to-action
  • Header Title: Chat window title
  • Company Logo: Upload your logo
  • Welcome Message: Custom heading and subheading

Preview:

  • Live preview of widget as you configure
  • Test conversations before deployment
  • See exactly how visitors will interact
  • Mobile-responsive preview

Welcome Screen​

Customizable Elements:

Welcome Heading:

  • Default: "Hi there! 👋"
  • Personalize to match your brand voice
  • Support for emojis and text

Welcome Subheading:

  • Optional secondary message
  • Example: "How can we help you today?"
  • Additional context for visitors

Company Logo:

  • Upload image or provide URL
  • Displayed at top of chat
  • Professional branding

Suggested Questions​

What They Are:

  • Pre-defined questions visitors can click
  • Guide conversation flow
  • Reduce visitor effort
  • Improve engagement

General Questions:

  • Display immediately on welcome screen
  • Examples: "What are your pricing plans?", "How does it work?", "Contact support"
  • Unlimited questions supported

Section-Based Questions:

  • Organize questions by category
  • Expandable/collapsible sections
  • Examples: Pricing, Features, Support, Account
  • Show/hide on welcome screen (optional)

Configuration:

  • Add/remove questions anytime
  • Reorder by drag-and-drop (in preview)
  • Click to send question automatically
  • Supports emojis and formatting

Workflow Integration​

How It Works:

  1. Visitor sends message in chat widget
  2. Message triggers selected workflows
  3. Workflows execute (AI processing, database queries, etc.)
  4. Response sent back to visitor in real-time
  5. Conversation continues with context preserved

Workflow Selection:

  • Choose multiple workflows per widget
  • Workflows execute in parallel or sequence (depends on configuration)
  • Access full workflow builder capabilities
  • Test workflows directly in widget preview

Use Cases:

  • FAQ answering with AI
  • Lead qualification forms
  • Appointment booking
  • Product recommendations
  • Support ticket creation

Voice Features​

Voice Input:

  • Microphone button in chat input
  • Record voice message
  • Automatic speech-to-text conversion
  • Text appears in input field for editing before sending

Voice Call Mode:

  • Phone-like conversation experience
  • Real-time voice conversation with AI
  • Bidirectional audio streaming
  • Transcript display during call (optional)

Voice-Only Widget:

  • No text chat interface
  • Phone button only
  • Click to start voice call
  • Ideal for phone support replacement
  • Show live transcript option

Requirements:

  • Voice Agent workflow configured
  • Browser microphone permissions
  • Modern browser support (Chrome, Safari, Firefox, Edge)

API Key & Embed Code​

API Key Setup:

  1. Create API key in Settings → API Keys
  2. Grant "chat" or "workflows" scope
  3. Link API key to widget configuration
  4. API key authenticates widget requests

Embed Code:

<!-- Add to your website's HTML -->
<script src="https://api.expedify.ai/chat/chat-widget.js"></script>
<script>
  ExpedifyChat.init({
    apiKey: 'your-api-key-here',
    position: 'bottom-right',
    theme: 'light',
    primaryColor: '#ee785b',
    buttonText: 'Chat with us',
    headerTitle: 'Chat',
    welcomeHeading: 'Hi there! 👋',
    welcomeSubheading: 'How can we help you today?',
    companyLogo: 'https://your-domain.com/logo.png',
    workflows: ['workflow-id-1', 'workflow-id-2'],
    suggestedQuestions: [
      'What are your pricing plans?',
      'How does it work?',
      'Contact support'
    ],
    sectionQuestions: {
      'Pricing': ['What plans are available?', 'Is there a free trial?'],
      'Features': ['What features do you offer?', 'Can I integrate with my CRM?']
    },
    enableVoiceInput: true,
    enableVoiceCall: false,
    voiceOnlyMode: false
  });
</script>

Installation:

  • Copy embed code
  • Paste before closing </body> tag
  • Widget loads automatically on page load
  • No additional setup required

Conversation Management​

Widget Inbox:

  • View all chat widget conversations
  • Unified inbox with email, WhatsApp, etc.
  • Real-time message notifications
  • Conversation history per visitor

Visitor Tracking:

  • Unique visitor ID per browser
  • Track return visitors
  • Conversation history persistence
  • Visitor identification (email, name)

Conversation Features:

  • AI agent mode (automated responses)
  • Human agent mode (manual takeover)
  • Assign to team members
  • Internal notes
  • Tags and status

Analytics & Monitoring​

Conversation Metrics:

  • Total conversations
  • Messages per conversation
  • Response time
  • Resolution rate
  • Visitor engagement

Widget Performance:

  • Active widgets list
  • Conversations per widget
  • Most used workflows
  • Popular suggested questions

Per-Widget Stats:

  • Conversation count
  • Last active timestamp
  • API key usage
  • Configuration history

Getting Started​

Prerequisites​

Before creating a chatbot widget:

  1. Workflow Created

    • Build workflow in Workflow Builder
    • Test workflow execution
    • Publish workflow
    • Note workflow ID

  2. API Key Generated

    • Go to Settings → API Keys
    • Click "Create API Key"
    • Grant "chat" or "workflows" scope
    • Copy API key (shown once)

  3. Website Access

    • Access to your website's HTML
    • Ability to add script tags
    • No special server requirements

Quick Start​

Step 1: Navigate to Chatbot Settings

  1. Go to Automation → Chat Widget (or Settings → Chat Widget)
  2. See list of existing widgets (if any)
  3. Click Create New Widget button

Step 2: Configure Widget Appearance

Basic Settings:

  1. Widget Name: Internal name for identification (e.g., "Homepage Widget")
  2. API Key: Select from dropdown (or create new)
  3. Position: Bottom-right or bottom-left
  4. Theme: Light or dark
  5. Primary Color: Click color picker to choose brand color

Text & Branding:

  1. Button Text: What text shows on chat button (e.g., "Chat with us", "Need help?")
  2. Header Title: Title in chat window header (e.g., "Chat", "Support")
  3. Welcome Heading: First message visitor sees (e.g., "Hi there! 👋")
  4. Welcome Subheading: Optional secondary message
  5. Company Logo URL: Upload or paste logo image URL

Step 3: Add Suggested Questions

General Questions:

  1. Click Add Question under General Questions
  2. Type question text (e.g., "What are your hours?")
  3. Add more questions (recommended: 3-5)
  4. Questions appear immediately on welcome screen

Section Questions (Optional):

  1. Click Add Section
  2. Name section (e.g., "Pricing", "Features")
  3. Add questions to section
  4. Create multiple sections for organization
  5. Toggle "Show on Welcome" to display immediately

Step 4: Select Workflows

  1. Click Add Workflow button
  2. Search or browse workflows
  3. Select workflow(s) to execute when visitors send messages
  4. Multiple workflows execute together
  5. Remove workflows by clicking X icon

Step 5: Configure Voice (Optional)

Voice Input:

  • Toggle Enable Voice Input
  • Visitors can speak instead of typing
  • Automatic speech-to-text conversion

Voice Call:

  • Toggle Enable Voice Call
  • Requires Voice Agent workflow
  • Phone-like conversation experience
  • Choose "Show Transcript" to display during call

Voice-Only Mode:

  • Toggle Voice-Only Mode
  • No text chat interface
  • Phone button only
  • Requires Voice Call enabled

Step 6: Preview Widget

  1. Live preview updates as you configure
  2. Test sending messages
  3. Click suggested questions to test
  4. Try voice features (if enabled)
  5. Verify appearance matches brand

Step 7: Save & Get Embed Code

  1. Click Save Widget button
  2. Widget saved to database
  3. Copy Embed Code button appears
  4. Click to copy to clipboard
  5. Paste code into your website's HTML (before </body> tag)
  6. Widget goes live immediately

Step 8: Test on Your Website

  1. Open your website in browser
  2. Chat button appears in configured position
  3. Click to open chat window
  4. Send test message
  5. Verify workflow executes correctly
  6. Check conversation appears in Widget Inbox

Widget Configuration in Detail​

Position Options​

Bottom-Right:

  • Default position
  • Most common placement
  • Doesn't obstruct main content
  • Familiar to users

Bottom-Left:

  • Alternative placement
  • Useful if right side has other widgets
  • Same functionality as bottom-right

Theme & Colors​

Light Theme:

  • White background
  • Dark text
  • Clean, professional look
  • Best for most websites

Dark Theme:

  • Dark background
  • Light text
  • Modern aesthetic
  • Reduces eye strain
  • Good for dark-themed websites

Primary Color:

  • Used for: Chat button, send button, user message bubbles
  • Choose brand color for consistency
  • Hex code format: #ee785b
  • Color picker for easy selection

Welcome Screen Strategy​

Best Practices:

Welcome Heading:

  • Keep it friendly and conversational
  • Use visitor's name if identified
  • Examples: "Hi there! 👋", "Welcome to Acme!", "Need help?"

Welcome Subheading:

  • Optional but recommended
  • Set expectations (e.g., "Our AI assistant is here 24/7")
  • Call-to-action (e.g., "Ask me anything!")

Company Logo:

  • Professional branding
  • Builds trust
  • Recommended size: 200x50px
  • PNG with transparent background works best

Suggested Questions Strategy​

General Questions (Always Visible):

  • Top 3-5 most common questions
  • Broad topics (pricing, features, support)
  • Action-oriented (book demo, contact sales)

Section Questions (Organized):

  • Group related questions
  • Examples:
    • Pricing: "Plans available?", "Free trial?", "Volume discounts?"
    • Features: "What can it do?", "Integrations?", "Mobile app?"
    • Support: "Contact support", "Knowledge base", "Report issue"
    • Account: "Sign up", "Login help", "Reset password"

Writing Good Questions:

  • Use natural language
  • Keep it short (5-8 words max)
  • Answer what visitors actually ask
  • Test with real users

Workflow Selection Strategy​

Single Workflow:

  • Simple use case
  • One AI agent handles everything
  • Easy to manage
  • Good for FAQs

Multiple Workflows:

  • Complex use cases
  • Different workflows for different intents
  • Example: FAQ workflow + Lead capture workflow + Support ticket workflow
  • Workflows can execute in sequence or parallel

Best Practices:

  • Start with one workflow
  • Add more as needs grow
  • Test each workflow individually first
  • Monitor which workflows are triggered most

Voice Configuration​

When to Enable Voice Input:

  • Accessibility for users who can't type
  • Mobile users (easier than typing on phone)
  • Hands-free use cases
  • Speech-to-text convenience

When to Enable Voice Call:

  • Replacing phone support
  • Complex conversations better suited for voice
  • Personal touch needed
  • Voice Agent workflow configured

Voice-Only Mode Use Cases:

  • Phone support replacement
  • Call center alternative
  • Voice-first experience
  • Minimal interface preferred

Managing Multiple Widgets​

Why Multiple Widgets:

  • Different widgets for different pages
  • A/B testing configurations
  • Separate widgets per product
  • Different workflows per audience

Widgets List View:

  • All widgets in one table
  • Name, API key, conversation count
  • Active/inactive status
  • Quick actions: Edit, Copy code, Delete

Widget Operations:

  • Edit: Update configuration anytime
  • Duplicate: Clone widget with new API key
  • Deactivate: Hide widget without deleting
  • Delete: Permanently remove (conversations preserved)

Embed Code Management:

  • Each widget has unique embed code
  • Update config without changing embed code
  • Copy code from any widget anytime
  • Same API key across multiple widgets (optional)

Advanced Features​

Custom CSS (Coming Soon)​

  • Override default widget styles
  • Full CSS customization
  • Target specific elements
  • Advanced branding

Metadata Field​

  • Store custom configuration
  • JSON format
  • Use in workflows
  • Extend widget capabilities

Multiple API Keys​

  • Separate API keys per widget
  • Different rate limits
  • Security isolation
  • Usage tracking per key

Conversation Context​

  • Widget remembers conversation history
  • Context passed to workflows
  • Visitor identification
  • Returning visitor detection

Widget Inbox​

Access Widget Conversations:

  1. Go to Channel → Inbox (or Widget Inbox)
  2. See all widget conversations
  3. Filter by status, agent mode, visitor
  4. Click conversation to view details

Conversation Details:

  • All messages in conversation
  • Visitor information
  • Timestamps
  • Workflow executions
  • Agent mode (AI or Human)

Agent Mode Toggle:

  • AI Mode: Automated responses via workflows
  • Human Mode: Manual replies from team member
  • Switch anytime during conversation
  • Workflow pauses in Human mode

Reply to Visitors:

  • Type message in input field
  • Click Send
  • Message appears in visitor's chat widget
  • Real-time delivery via WebSocket

Visitor Identification​

Anonymous Visitors:

  • Unique visitor ID generated per browser
  • Stored in localStorage
  • Persistent across page reloads
  • Conversation history maintained

Identified Visitors:

  • Link visitor to CRM contact
  • Use /chat/widget/identify API
  • Provide email, name, custom fields
  • Show personalized welcome messages

Identification Methods:

  • Manual: Call identify API from your backend
  • Automatic: User logs into your website → widget identifies them
  • Workflow: Use workflow node to identify based on conversation

Best Practices​

Widget Placement​

Positioning:

  • Bottom-right is standard (85% of sites use it)
  • Don't hide behind other elements
  • Ensure it's visible on all pages
  • Consider mobile responsiveness

Timing:

  • Show immediately on page load? Or delayed?
  • Current implementation: Always visible
  • Future: Trigger rules (time on page, scroll depth, exit intent)

Conversation Design​

AI Responses:

  • Keep responses concise and helpful
  • Use formatting (bold, lists, links)
  • Provide next steps
  • Offer to escalate to human if needed

Workflow Design:

  • Handle common questions in one workflow
  • Separate workflows for complex tasks
  • Include error handling
  • Test edge cases

Suggested Questions:

  • Update based on analytics
  • Remove unused questions
  • Add seasonal questions
  • Test question wording

Performance​

Widget Load Time:

  • Widget script is lightweight (~50KB)
  • Loads asynchronously (doesn't block page)
  • No jQuery or heavy dependencies
  • Cached by browsers

Response Time:

  • Workflow execution speed depends on complexity
  • Typical: 0.5-2 seconds for AI responses
  • Use typing indicator to show activity
  • Set timeout for slow workflows

Privacy & Security​

API Key Security:

  • API keys are public (safe to embed in HTML)
  • Scoped permissions (chat/workflows only)
  • Rate limiting prevents abuse
  • Revoke compromised keys immediately

Visitor Data:

  • No personal data collected by default
  • Only store conversation messages
  • GDPR compliant
  • Visitor can request data deletion

Conversation Security:

  • Conversations isolated per visitor ID
  • No cross-visitor data leakage
  • Encrypted in transit (HTTPS)
  • Stored securely in database

Troubleshooting​

Widget Not Appearing​

Problem: Embed code added but widget doesn't show on website

Causes:

  • Embed code not properly placed
  • JavaScript errors blocking execution
  • Widget deactivated
  • API key invalid

Solutions:

  1. Verify embed code is before </body> tag
  2. Check browser console for JavaScript errors
  3. Confirm widget is "Active" in settings
  4. Verify API key is valid and has "chat" scope
  5. Check browser doesn't block scripts from external domains
  6. Ensure no Content Security Policy blocking the script

Widget Button Shows But Doesn't Open​

Problem: Click chat button but nothing happens

Causes:

  • JavaScript error during initialization
  • CSS conflict hiding chat window
  • Browser compatibility issue

Solutions:

  1. Check browser console for errors
  2. Try different browser
  3. Inspect element to see if chat window exists but hidden
  4. Verify no CSS on your site is overriding widget styles
  5. Update widget configuration and re-deploy

Messages Not Getting Responses​

Problem: Visitor sends message but no response from AI

Causes:

  • No workflows selected
  • Workflow not published
  • Workflow execution error
  • API key missing workflow scope

Solutions:

  1. Verify at least one workflow is selected in widget config
  2. Ensure workflows are published (not draft)
  3. Test workflow execution in Workflow Builder
  4. Check API key has "workflows" scope
  5. Check workflow execution logs for errors

Voice Input Not Working​

Problem: Microphone button doesn't work or shows error

Causes:

  • Browser microphone permissions denied
  • HTTPS required (voice doesn't work on HTTP)
  • Browser doesn't support MediaRecorder API
  • Voice input not enabled in config

Solutions:

  1. Grant microphone permission when prompted
  2. Ensure website is HTTPS (required for microphone access)
  3. Use modern browser (Chrome, Safari, Firefox, Edge)
  4. Verify "Enable Voice Input" is toggled ON in widget settings
  5. Check browser console for permission errors

Voice Call Not Connecting​

Problem: Click voice call button but call doesn't start

Causes:

  • Voice Agent workflow not configured
  • No Voice integration (VAPI, Vobiz, etc.)
  • Voice Agent not published
  • Microphone permissions denied

Solutions:

  1. Create and publish Voice Agent workflow
  2. Configure voice integration in Settings → Integrations
  3. Select Voice Agent workflow in widget config
  4. Grant microphone and audio permissions
  5. Check Voice Agent workflow settings
  6. Test voice call in Voice Agent directly first

Suggested Questions Not Showing​

Problem: Configured suggested questions don't appear

Causes:

  • "Show on Welcome" toggled off for section questions
  • No questions configured
  • Welcome screen disabled
  • CSS hiding questions

Solutions:

  1. Add general questions (always visible)
  2. For section questions, toggle "Show on Welcome"
  3. Save widget configuration after adding questions
  4. Refresh website to see changes
  5. Check preview in widget settings

Conversations Not Appearing in Inbox​

Problem: Visitors send messages but conversations don't show in Widget Inbox

Causes:

  • Different organization context
  • Conversations in different tab/filter
  • API key linked to different org
  • Database sync issue

Solutions:

  1. Check all tabs: All, Active, Unread, Assigned
  2. Clear filters
  3. Refresh inbox page
  4. Verify API key belongs to correct organization
  5. Check conversation was actually created (check API logs)

Embed Code Not Working After Update​

Problem: Updated widget config but website still shows old configuration

Causes:

  • Browser cache
  • CDN cache
  • No-cache headers not working
  • Embed code needs updating

Solutions:

  1. Hard refresh browser (Ctrl+Shift+R or Cmd+Shift+R)
  2. Clear browser cache
  3. Wait 5-10 minutes for CDN cache to expire
  4. Embed code doesn't need updating (config is server-side)
  5. Verify widget was saved successfully

Integration Status​

Check Widget Status:

In Widget Settings:

  • 🟢 Active: Widget is live and working
  • 🔴 Inactive: Widget is hidden (not deleted)
  • ⚫ Deleted: Widget removed

Check API Key Status:

  • ✅ Valid: API key is active and has permissions
  • ❌ Invalid: API key revoked or missing scopes
  • ⚠️ Expiring: API key approaching expiration date

Conversation Health:

  • Successfully creating conversations = healthy
  • Workflow execution errors = check workflows
  • No responses = check workflow selection
Last updated on