MxChat Assistant API
Connect your custom OpenAI Assistant directly to MxChat. Your Assistant handles all conversations while seamlessly integrating with MxChat’s powerful action system – including forms, image generation, product cards, and more.
Requirements
- MxChat Core Plugin (installed and activated)
- MxChat Pro License (active)
- OpenAI API key
- OpenAI Assistant (created in your OpenAI dashboard)
Quick Setup
- Install the Plugin: Upload and activate MxChat Assistant API through your WordPress plugins page
- Configure API Key: Add your OpenAI API key in
MxChat → Settings - Create Assistant: Visit OpenAI Assistants and create a new Assistant
- Copy Assistant ID: Copy your Assistant ID (starts with “asst_”)
- Enable Integration: Navigate to
MxChat → Assistant API, paste your Assistant ID, and enable the integration - Test Connection: Use the test button to verify everything works
Key Features
Conversation Management
Your Assistant handles all chat conversations with full context preservation. Threads persist for 24 hours, maintaining conversation history across sessions.
Action Integration
MxChat automatically detects when users trigger actions and seamlessly routes them to the appropriate handler. Your Assistant continues the conversation while actions execute in the background.
Currently Supported Actions
- Image Generation: Create images from text descriptions
- Brave Image Search: Search and display web images
- Product Cards: Show WooCommerce product information
- Order History: Display customer order details
- MxChat Forms: Collect user information
- Loops Integration: Send data to Loops email platform
Auto-save Transcripts
All conversations are automatically saved to MxChat’s transcript system with full message history and user information.
How to Use
- Create Your Assistant: In OpenAI dashboard, create an Assistant with your custom instructions and desired model (GPT-4, GPT-4 Turbo, etc.)
- Configure Instructions: Add your business logic, personality, and guidelines to your Assistant’s instructions
- Enter Assistant ID: Copy the ID from OpenAI and paste it into
MxChat → Assistant API - Enable Integration: Check “Enable Assistant API” and save
- Test Chat: Open your chat widget and verify responses come from your Assistant
- Monitor Transcripts: View all conversations in
MxChat → Transcripts
Action System
How Actions Work
MxChat analyzes every user message for action triggers before sending it to your Assistant. When an action is detected, it executes immediately while your Assistant continues the conversation flow.
Action Detection
The system uses similarity scoring to match user messages with available actions. You can view these scores in the Admin Debugger panel when testing.
Coming Soon
- Smart Recommender: AI-powered product recommendations
- WooCommerce Recommender: Advanced product matching
- Chat with PDF: Upload and query PDF documents
- Transfer to Slack: Route conversations to support team
- Streaming Responses: Real-time message streaming
Assistant Configuration Tips
Effective Instructions Include:
- Role: Define who your Assistant is (customer support agent, sales rep, etc.)
- Tone: Specify the personality and communication style
- Boundaries: What topics to handle or avoid
- Actions: Mention available actions users can request
- Fallbacks: How to handle unsupported requests
Example Instructions:
“You are a helpful customer support agent for [Your Company]. Be friendly and professional. You can help users with: product information, order status, and image generation. If users want to see products, tell them you’ll show product cards. Always maintain a conversational tone and offer assistance proactively.”
Model Selection:
- GPT-4 Turbo: Best for complex conversations and reasoning
- GPT-4: Excellent quality with strong instruction following
- GPT-3.5 Turbo: Faster and more cost-effective for simple queries
Troubleshooting
Error: “OpenAI Assistant is enabled but not properly configured”
- Verify your OpenAI API key is set in
MxChat → Settings - Ensure your Assistant ID is correct and starts with “asst_”
- Check that your Assistant still exists in the OpenAI dashboard
Error: “Assistant not found”
- Double-check your Assistant ID for typos
- Verify the Assistant wasn’t deleted from OpenAI dashboard
- Ensure you’re using the correct OpenAI account
Error: “Invalid API key”
- Regenerate your API key in the OpenAI dashboard
- Update the key in
MxChat → Settings - Verify your OpenAI account has active billing
Responses are slow or timeout
- Maximum response time is 60 seconds
- Complex Assistant instructions can slow processing
- Try simplifying your Assistant’s system instructions
- Check OpenAI’s status page for outages
Actions not triggering
- View similarity scores in Admin Debugger panel
- User messages must clearly indicate action intent
- Some actions require specific MxChat add-ons to be installed
Thread/conversation context lost
- Threads persist for 24 hours – context clears after this period
- Use “Clear Session” in settings to manually reset for testing
- Each chat session maintains its own separate thread
Frequently Asked Questions
Do I need MxChat Pro?
Yes, this add-on requires an active MxChat Pro license to function.
Can I use multiple Assistants?
Currently only one Assistant can be active at a time. You can switch between Assistants by changing the Assistant ID in settings.
What happens to MxChat’s knowledge base?
Your Assistant handles all conversations, but MxChat actions still work. The knowledge base is not consulted when Assistant API is enabled.
How long is conversation history kept?
Threads persist for 24 hours. Transcripts are stored permanently in your WordPress database until manually deleted.
Can I see what actions are available?
Yes, use the Admin Debugger panel to see all available actions and their similarity scores when testing messages.
Does this work with file uploads?
If your Assistant has file search or code interpreter enabled in OpenAI, it can work with files uploaded there. Direct file uploads through the chat widget are not currently supported.
What are the costs?
You pay OpenAI directly for Assistant API usage based on your selected model and usage. Check OpenAI pricing for current rates.
Can my Assistant call external APIs?
Function calling is not currently supported. Your Assistant can only use built-in OpenAI tools (code interpreter, file search) and MxChat actions.
Common API Errors
HTTP 401: Unauthorized
Your API key is invalid or expired. Regenerate it in the OpenAI dashboard and update in MxChat settings.
HTTP 404: Assistant Not Found
The Assistant ID doesn’t exist or was deleted. Verify the ID in your OpenAI Assistants dashboard.
HTTP 429: Rate Limit Exceeded
You’ve exceeded OpenAI’s rate limits. Wait a few minutes or upgrade your OpenAI plan for higher limits.
HTTP 500: Internal Server Error
OpenAI’s servers are having issues. Check OpenAI status and try again later.
Timeout Error
Response took longer than 60 seconds. Simplify your Assistant’s instructions or try again during off-peak hours.
Technical Details
API Specifications
- OpenAI Version: Assistants v2
- Thread Persistence: 24 hours per session
- Maximum Timeout: 60 seconds for responses
- Polling Interval: 1 second for status checks
- HTTP Timeout: 30 seconds for API calls
Multisite Support
The plugin fully supports WordPress multisite installations with network-level configuration options and site-specific Assistant assignments.
Session Management
Each chat session creates a unique OpenAI thread. Threads are stored as WordPress transients and automatically expire after 24 hours to manage storage.
Rate Limiting
The plugin inherits MxChat’s rate limiting system and respects OpenAI’s API rate limits based on your account tier.
Recent Updates
Version 1.0.0
Initial release with OpenAI Assistants v2 integration, thread management, action integration, and full transcript logging.
Need Help?
If you’re experiencing issues not covered here:
- Visit MxChat.ai for additional resources
- Check the MxChat YouTube channel for tutorials
- Review OpenAI Assistants documentation
- Contact MxChat support with your license key and error details
