README

An AI-powered console interface for Mautic with voice input, intelligent assistance, and tool integration. Chat with your Mautic instance using natural language!

Overview

The Mautic AI Console Bundle provides an intelligent assistant that helps users interact with their Mautic instance through natural language. Ask questions about your data, get help with configuration, or execute actions - all through a conversational interface.

Features

Game-Like Console Toggle - Instant access via keyboard (console key ` or § key) - just like Counter-Strike or Minecraft!
Natural Language Interface - Chat with Mautic in plain language
Voice Input Support - Speak to the AI using speech-to-text (Whisper integration)
Context-Aware - Knows your name, language, and Mautic version
Conversation History - Maintains context across multiple messages
Tool Integration - Can execute actions in Mautic (contacts, segments, cache, etc.)
Customizable AI Model - Choose from available models (GPT-4, Claude, etc.)
Custom Instructions - Define system prompts to control AI behavior
Multi-language Support - Responds in the user's preferred language

Requirements

Mautic 4.0+ or Mautic 5.0+
PHP 7.4 or 8.0+
Mautic AI Connection Bundle (required dependency)
A configured LiteLLM instance or OpenAI API access

Installation

Via Composer

composer require mautic/ai-console-bundle

This will automatically install the required mautic/ai-connection-bundle dependency.

Manual Installation

First, install the Mautic AI Connection Bundle (required)
Download or clone this repository
Place the MauticAiConsoleBundle folder in docroot/plugins/
Clear Mautic cache:
```
php bin/console cache:clear
```
Go to Mautic Settings → Plugins
Click "Install/Upgrade Plugins"
Find "Mautic AI Console" and publish it

Dependencies

Mautic AI Connection Bundle (Required)

This plugin requires the Mautic AI Connection Bundle to function. The AI Connection Bundle provides:

LiteLLM service integration
Centralized AI configuration (endpoint and API keys)
Model management

Important: Configure the AI Connection Bundle first before using the AI Console!

Configuration

Navigate to Mautic Settings → Plugins → Mautic AI Console to configure the plugin.

Basic Settings

1. AI Console Enabled

Enable or disable the AI Console interface.

2. AI Model

Select which AI model to use for the console:

GPT-4 (most capable, slower)
GPT-3.5 Turbo (fast, cost-effective)
Claude 3 Sonnet/Haiku/Opus
Other models available in your LiteLLM instance

Note: The AI Console and AI Reports can use different models independently.

3. Pre-prompt (System Instructions)

The pre-prompt is critical for controlling the AI's behavior. This is where you define:

The AI's personality and role
Output format (HTML, markdown, plain text)
Language preferences
Available context (user info, Mautic version)
Behavioral guidelines

Default Pre-prompt Example:

CONTEXT:
--------------
Your name is Mattias. You are the Mautic helper and you run inside the Mautic AI console.

You are helping the following user:
User firstname: {account_firstname}
User Lastname: {account_lastname}
User Email: {account_email}

OUTPUT
------------
You may use the following HTML tags: <a>, <i>, <b>, <ul>, <li>, <p>
You don't return Markdown, you return HTML.
If you link to a URL (e.g., /s/dashboard), link to it like this: <a href="/s/dashboard">/s/dashboard</a>

You always try to answer in short sentences or limited paragraphs, only elaborate when explicitly asked.

You answer in {language}

Instructions:
-----------------
You are a professional helpful Mautic assistant. You help users with their marketing automation tasks.
You answer in a professional manner, without repeating the question and in a brief manner.

You can help with:
1. Answering questions based on Mautic documentation
2. Triggering tool calls when needed

If you are asked commands or things you cannot do, just say: "This feature is not supported. I'm sorry."

Available Tokens in Pre-prompt

{language} - User's interface language (e.g., "English", "French")
{account_firstname} - User's first name
{account_lastname} - User's last name
{account_email} - User's email address
{mautic_version} - Current Mautic version

Importance of a Good Pre-prompt

The pre-prompt is the most important configuration for the AI Console. A well-crafted pre-prompt will:

✅ Define personality - Is the AI formal, friendly, technical, or casual? ✅ Control output format - HTML vs Markdown vs plain text ✅ Set boundaries - What the AI can and cannot do ✅ Provide context - User info, system capabilities, documentation ✅ Ensure consistency - Same behavior across all users ✅ Improve accuracy - Clear instructions = better responses

Tips for Writing Good Pre-prompts:

Be specific about output format

❌ Bad: "Answer questions"
✅ Good: "Answer in 2-3 sentences using HTML tags only. No markdown."

Define the AI's role clearly

❌ Bad: "You are helpful"
✅ Good: "You are a Mautic technical expert who helps with marketing automation"

Set response length expectations

❌ Bad: "Answer questions"
✅ Good: "Keep answers under 100 words unless the user asks for more detail"

Include relevant documentation or context

✅ Good: Include key Mautic paths like /s/contacts, /s/campaigns, etc.

Handle edge cases

✅ Good: "If asked about features you're unsure about, direct users to the official documentation"

Speech-to-Text Settings

Enable Speech-to-Text

Toggle voice input functionality.

Speech-to-Text Model

Select the model for speech recognition:

whisper-1 (OpenAI Whisper)
Other speech models available in your LiteLLM instance

Note: Speech-to-text requires audio transcription support in your LiteLLM configuration.

Tool Configuration

Enable or disable specific tools that the AI can execute:

Clear Cache Tool - Allow AI to clear Mautic cache
Create Contact Tool - Allow AI to create contacts
Create Segment Tool - Allow AI to create segments

Security Note: Only enable tools you want the AI to have access to. Disabled tools won't be available to the AI.

Usage

Accessing the Console

The AI Console can be accessed in two ways:

Keyboard Toggle (Recommended) - Press the console key (` or ~ key, depending on your keyboard layout) or the paragraph key (§) to instantly toggle the AI Console on/off. This provides quick, game-like access similar to consoles in Counter-Strike or Minecraft.
Toolbar Button - Click the AI Console button in the Mautic toolbar (top right).

Pro Tip: The keyboard toggle is the fastest way to access the AI while working in Mautic!

Asking Questions

Examples:

"How many contacts do I have?"
"Show me recent campaigns"
"How do I create a segment?"
"What's the difference between a segment and a tag?"
"Navigate to the email builder"

Using Voice Input

Click the microphone icon in the AI Console
Speak your question
The AI will transcribe and respond

Using Tools

When enabled, the AI can execute actions:

Example:

User: "Create a contact named John Doe with email john@example.com"
AI: Executes the Create Contact tool
AI: "✅ Contact created successfully: John Doe (john@example.com)"

Architecture

┌─────────────────────────────────────┐
│     Mautic AI Console Bundle        │
│                                     │
│  ┌─────────────────────────────┐   │
│  │  Console Controller         │   │
│  │  - Process messages         │   │
│  │  - Handle voice input       │   │
│  │  - Tool execution           │   │
│  │  - Conversation history     │   │
│  └─────────────────────────────┘   │
└─────────────────────────────────────┘
              ↓ depends on
┌─────────────────────────────────────┐
│   Mautic AI Connection Bundle       │
│  ┌───────────────────────────────┐  │
│  │   LiteLLM Service             │  │
│  │  - Chat API                   │  │
│  │  - Speech-to-text API         │  │
│  └───────────────────────────────┘  │
└─────────────────────────────────────┘
              ↓ connects to
┌─────────────────────────────────────┐
│       LiteLLM Proxy Server          │
│  (Routes to OpenAI, Claude, etc.)   │
└─────────────────────────────────────┘

Advanced Configuration

Custom Tools

Create custom tools by extending the tool system:

Create a new tool class in Tools/ directory:

<?php
namespace MauticPlugin\MauticAiConsoleBundle\Tools;

class MyCustomTool
{
    public function getTitle(): string
    {
        return 'My Custom Tool';
    }

    public function getDescription(): string
    {
        return 'Description of what this tool does';
    }

    public function getParameters(): array
    {
        return [
            'param1' => [
                'type' => 'string',
                'description' => 'Parameter description',
                'required' => true,
            ],
        ];
    }

    public function execute(array $arguments): array
    {
        // Tool logic here
        return [
            'success' => true,
            'message' => 'Tool executed successfully',
        ];
    }
}

The tool will automatically appear in plugin settings
Enable it to make it available to the AI

Conversation Context

The AI Console maintains the last 7 conversation turns for context. This allows:

Follow-up questions
Contextual understanding
Multi-turn conversations

Example conversation:

User: "How many contacts do I have?"
AI: "You have 1,234 contacts in your database."
User: "How many are subscribed?"  ← AI remembers we're talking about contacts
AI: "892 contacts are subscribed to your emails."

Troubleshooting

Console button not appearing

Solution:

Ensure plugin is published
Enable "AI Console Enabled" in settings
Clear cache

"LiteLLM endpoint must be configured" error

Solution: Configure the Mautic AI Connection Bundle first with your LiteLLM endpoint and credentials.

AI responses are in the wrong language

Solution:

Check your Mautic user profile language - Go to your user profile settings and verify the language is set correctly. This language preference is automatically passed to the AI via the {language} token in the pre-prompt.
Verify the pre-prompt uses the {language} token - Ensure your pre-prompt includes instructions like You answer in {language} so the AI knows which language to respond in.
Example: If your profile is set to French, the {language} token will be replaced with "French" in the instructions sent to the AI.

Speech-to-text not working

Solution:

Enable "Speech-to-Text Enabled" in settings
Ensure your LiteLLM instance supports audio transcription
Check browser microphone permissions

AI gives incorrect answers

Solution: Improve your pre-prompt:

Add more specific instructions
Include relevant Mautic documentation snippets
Define output format more clearly
Set behavior boundaries

Tools not executing

Solution:

Ensure tools are enabled in plugin settings
Check that the AI's pre-prompt mentions tool capabilities
Verify user has necessary permissions in Mautic

Development

Adding Documentation to Pre-prompt

You can include Mautic documentation in the pre-prompt to improve accuracy:

DOCUMENTATION
---------------------
Contacts: /s/contacts - View all contacts
Segments: /s/segments - Create and manage segments
Campaigns: /s/campaigns - Marketing automation campaigns
...

Testing Tools

Test tool execution:

$tool = new CreateContactTool($leadModel, $translator);
$result = $tool->execute([
    'firstname' => 'Test',
    'lastname' => 'User',
    'email' => 'test@example.com',
]);

Best Practices

Start with a detailed pre-prompt - Spend time crafting clear instructions
Test with different models - GPT-4 vs GPT-3.5 behave differently
Enable only needed tools - Limit AI capabilities for security
Include user context - Use tokens like {account_firstname} for personalization
Monitor conversations - Check AI logs to improve prompts
Keep responses concise - Configure AI to be brief by default
Use HTML formatting - Makes responses more readable in the console

Security Considerations

API keys are encrypted and stored securely via AI Connection Bundle
Tools execute with the current user's permissions
Conversation history is user-specific
Only enabled tools are available to the AI
All AI requests include Mautic instance fingerprint for tracking

Support

GitHub Issues: Report an issue
Mautic Community: community.mautic.org
AI Connection Bundle: See documentation

License

GPL-3.0-or-later

Credits

Created by Frederik Wouters and the Mautic Community

Version

1.0.0

Changelog

1.0.0 (2024)

Initial release
Natural language interface
Voice input support (Speech-to-text)
Conversation history
Tool integration (contacts, segments, cache)
Customizable AI models
Multi-language support
Custom pre-prompt configuration
User context tokens

woutersf / ai-console-bundle

Maintainers

Details

README

Overview

Features

Requirements

Installation

Via Composer

Manual Installation

Dependencies

Mautic AI Connection Bundle (Required)

Configuration

Basic Settings

1. AI Console Enabled

2. AI Model

3. Pre-prompt (System Instructions)

Available Tokens in Pre-prompt

Importance of a Good Pre-prompt

Speech-to-Text Settings

Enable Speech-to-Text

Speech-to-Text Model

Tool Configuration

Usage

Accessing the Console

Asking Questions

Using Voice Input

Using Tools

Architecture

Advanced Configuration

Custom Tools

Conversation Context

Troubleshooting

Console button not appearing

"LiteLLM endpoint must be configured" error

AI responses are in the wrong language

Speech-to-text not working

AI gives incorrect answers

Tools not executing

Development

Adding Documentation to Pre-prompt

Testing Tools

Best Practices

Security Considerations

Support

License

Credits

Version

Changelog

1.0.0 (2024)