This comprehensive, step-by-step guide will walk you through the process of installing, configuring, and activating the BusinessChat integration for your Magento store.
📋 Checklist (Before You Start)
Ensure you or your client has these requirements ready before starting the installation:
Magento Version: Must be 2.4.x or later.
Access Levels: You will need both:
Magento Admin Panel login credentials.
Server Access (SSH, FTP/SFTP, or cPanel File Manager).
📂 Step 1: Uploading the Files
Once you unzip the BusinessChat folder, you must upload it to your Magento server.
The Goal: The final file path must look exactly like this: your-magento-root/app/code/BusinessChat/Integration/registration.php
How to Upload (Choose One Option)
Option A (Recommended for Advanced Users): Use SSH/SCP to upload the unzipped BusinessChat folder directly to the app/code/ directory.
Option B (Standard FTP): Use an FTP client (such as FileZilla) to drag and drop the BusinessChat folder into the app/code/ directory.
Option C (cPanel File Manager): Upload the compressed ZIP file directly to the app/code/ directory using your cPanel File Manager, and extract it there.
💡 Support Tip: If the code folder does not exist inside your app/ directory, simply create a new directory named code inside app/ and upload the files there!
💻 Step 2: Running the Setup Commands
Magento requires a series of terminal commands to recognize, register, and compile the new module files. Run the following commands in your server terminal, one by one, from your Magento root directory:
Enable the Module: php bin/magento module:enable BusinessChat_Integration
Upgrade the Database Schema: php bin/magento setup:upgrade
Compile Dependencies: php bin/magento setup:di:compile
Deploy Static View Assets: php bin/magento setup:static-content:deploy -f
Flush the Cache: php bin/magento cache:flush
🔑 Step 3: Connecting the Business ID
Now, navigate to your Magento Admin Panel to link your e-commerce store with your BusinessChat account.
Log into your Magento Admin Panel.
Navigate to Stores > Configuration.
In the left-hand menu, select BusinessChat > Integration Settings.
Enter your unique Business ID in the field provided and click Save Config.
⚠️ Crucial Step: You must clear the cache again. Go to System > Cache Management and click Flush Magento Cache.
🤝 Step 4: Final Activation
This step creates the secure handshake and API credentials exchange between your Magento store and BusinessChat.
In your Terminal: Run the following command to initialize the integration: php bin/magento businesschat:integration:create
In your Magento Admin Panel: Navigate to System > Integrations.
Activate the Integration: Find the row named "Business Chat Integration", click Activate, and then select Allow to grant the required permissions.
🔒 Step 5: The "Must-Do" Security Setting
⚠️ Critical Note: The integration will fail to communicate or sync any events if this final security authorization step is not completed.
In your Magento Admin Panel, go to Stores > Configuration > Services > OAuth.
Find the setting titled "Allow OAuth Access Tokens to be used as standalone Bearer tokens" and set it to Yes.
Click Save Config and perform a final Flush Cache (under System > Cache Management).
🛠️ Troubleshooting Cheat Sheet
If you encounter issues during or after installation, refer to these common solutions:
Permission Errors | Run this command to fix file ownership permissions on your server: chown -R www-data:www-data app/code/BusinessChat/ (Note: Replace www-data with your explicit web server user if different). |
Memory Errors | If compilation fails due to memory limits, append a memory limit override to the command: php -d memory_limit=2G bin/magento setup:di:compile |
Events Not Syncing | Double-check Step 5 (Bearer Tokens). Forgetting to allow standalone Bearer tokens is the #1 cause of synchronization failures. |
Status Shows "Inactive" | Go to System > Integrations in the Magento Admin, find the BusinessChat integration, and click Reauthorize. |