Embedding Chatbots

Add AI-powered chatbots that can execute workflows and answer questions using your data.

What Are Embedded Chatbots?

Overview

Embedded chatbots:

• Conversational AI interface
• Connected to your workflows
• Answers from your knowledge base
• Actions via MCP tools

Use Cases

• Customer support
• Sales assistance
• Internal help desk
• Product guidance

Creating a Chatbot

From Dashboard

1. Go to Chatbots > Create
2. Name your chatbot
3. Configure AI behavior
4. Connect knowledge and tools
5. Deploy

Basic Configuration

chatbot:
  name: Support Bot
  description: Customer support assistant

  ai:
    model: gpt-4o
    temperature: 0.7
    systemPrompt: |
      You are a helpful customer support agent.
      Always be polite and concise.
      If you don't know something, say so.

  tools:
    - check_order_status
    - submit_ticket
    - search_help_docs

AI Configuration

Model Selection

Choose AI model:

ai:
  model: gpt-4o  # or gpt-4o-mini, claude-3-5-sonnet, etc.

Personality

Define chatbot behavior:

ai:
  systemPrompt: |
    You are Alex, a friendly support agent for TechCorp.
    - Be conversational and helpful
    - Use the customer's name when known
    - Offer to connect to human support for complex issues
    - Never make up information about orders

Response Style

Control responses:

ai:
  temperature: 0.7       # Creativity (0-1)
  maxTokens: 500         # Response length
  topP: 0.9              # Response diversity

Knowledge Base

Adding Knowledge

Connect information sources:

knowledge:
  - type: documents
    source: /help-articles

  - type: website
    url: https://docs.yoursite.com
    crawl: true

  - type: faq
    items:
      - q: What are your business hours?
        a: We're available 24/7 via chat.

Document Types

Supported formats:

• PDF documents
• Markdown files
• HTML pages
• Plain text
• Notion pages

Keeping Updated

Auto-sync options:

knowledge:
  - source: /docs
    sync: daily  # hourly, daily, weekly, manual

Connecting Tools

Available Tools

Link MCP tools for actions:

tools:
  - name: check_order
    description: Look up order status

  - name: create_ticket
    description: Open support ticket

  - name: transfer_human
    description: Connect to human agent

Tool Configuration

Control when tools are used:

tools:
  - name: check_order
    autoInvoke: true  # AI decides when to call
    requireConfirm: false  # No user confirmation needed

  - name: cancel_order
    autoInvoke: false  # User must request
    requireConfirm: true  # Confirm before executing

Appearance

Theme

appearance:
  theme: light  # light, dark, auto
  primaryColor: "#3B82F6"
  position: bottom-right

Avatar & Branding

appearance:
  avatar: /bot-avatar.png
  name: Support Bot
  companyLogo: /logo.png
  showPoweredBy: false

Chat Window

appearance:
  width: 400
  height: 600
  headerStyle: gradient
  messageStyle: bubble

Embed Code

JavaScript Embed

<script src="https://chat.yourapp.com/chatbot.js"></script>
<script>
  ChatBot.init({
    botId: 'your-bot-id',
    apiKey: 'your-public-key',
  });
</script>

React Component

import { ChatBot } from '@yourapp/chatbot-react';

function App() {
  return (
    <ChatBot
      botId="your-bot-id"
      apiKey="your-public-key"
      user={{ name: 'John', email: 'john@example.com' }}
    />
  );
}

Programmatic Control

// Open chat
ChatBot.open();

// Close chat
ChatBot.close();

// Send message
ChatBot.send('I need help with my order');

// Get conversation history
const history = ChatBot.getHistory();

User Context

Anonymous Users

No identification:

ChatBot.init({
  botId: 'your-bot-id',
  apiKey: 'your-public-key',
  // No user object
});

Identified Users

Pass user info:

ChatBot.init({
  botId: 'your-bot-id',
  apiKey: 'your-public-key',
  user: {
    id: 'user-123',
    name: 'John Doe',
    email: 'john@example.com',
    plan: 'pro',  // Custom attributes
  },
});

Conversation Features

Welcome Message

conversation:
  welcome:
    message: "Hi! I'm here to help. What can I do for you?"
    suggestions:
      - "Track my order"
      - "Return an item"
      - "Billing question"

Quick Replies

Suggest responses:

conversation:
  suggestions:
    enabled: true
    after: always  # always, question, never

Human Handoff

Transfer to humans:

handoff:
  enabled: true
  trigger: user_request  # or sentiment_negative, tool_unavailable
  destination: zendesk  # or intercom, freshdesk, custom

Analytics

Conversation Metrics

Track:

• Conversations started
• Messages sent/received
• Tool usage
• Resolution rate
• User satisfaction

Viewing Analytics

1. Go to Chatbots > Your Bot > Analytics
2. See dashboard
3. Export reports

Conversation Review

Review conversations:

1. Go to Conversations
2. Filter by date, status, rating
3. Review transcript
4. See tool calls

Testing

Preview Mode

1. Click Preview
2. Test conversations
3. Check tool behavior
4. Verify responses

Test Scenarios

tests:
  - name: Order inquiry
    messages:
      - user: "Where is my order?"
      - assistant: # Should ask for order number
      - user: "Order #12345"
      - assistant: # Should call check_order tool
    assertions:
      - toolCalled: check_order
      - containsOrderStatus: true

Best Practices

1. Clear System Prompt

Define exactly how the bot should behave.

2. Comprehensive Knowledge

Add all relevant documentation.

3. Tested Tools

Verify all tools work correctly.

4. Fallback Handling

Plan for unknown questions.

5. Human Escalation

Always provide path to humans.

Troubleshooting

Bot Not Responding

• Check API key
• Verify bot is published
• Check AI model quotas

Wrong Answers

• Update knowledge base
• Improve system prompt
• Add specific FAQs

Tools Not Working

• Verify tool connections
• Check tool descriptions
• Test tools independently

Next Steps

• MCP Widgets - Build AI widgets
• Building MCPs - Create tools
• Embedding Widgets - Other embeds