BYO (Bring Your Own) Auth + Chat [V2]
This chat application is designed specifically for complex sites or apps built with JavaScript on both the client and server sides. It is ideal for products that already have built-in authentication and are looking to seamlessly integrate robust chat functionality.
Prerequisite
- Signup/Login to your account at MagicChat.
- Create a New App and be sure to select Version V2 during setup.
- Navigate to the App Details page and note your: , App Name, API Key, Tenant ID
Project setup
Client Side Integration
To integrate it into your app, Do the following.
1. Load The Scripts
Locate the main entry file, typically index.html, and insert the following code snippet into the <head> section of the HTML document.
It should ideally be placed head of the root file.
<script src="https://cdn.socket.io/4.1.2/socket.io.min.js"></script><script src="https://magicchat-core.github.io/prod-ssc-client-cdns/bundle.js">
</script>2. Decide the placement of the Magicchat chat box in your app.
Centralized Implementation:
For applications with a common root layout (e.g., main index.js or layout component that renders on every route), combine both setUp and initialize logic in a single location.
This ensures the chatbox renders consistently across all routes
and avoids code duplication across screens.
Final Implementation
For single-route applications where the chat interface should appear universally, use this centralized approach:
Step 1 + Step 2 – Show the chatbox on all pages under a specific root route.
Run the setUp function at your application's entry point (usually the landing page or root URL) to ensure it loads immediately when the application starts.
<script>
document.addEventListener("DOMContentLoaded", async () => {
const profileData = await window.profileDataPromise; // Change this line to match how your application retrieves profile data
if (!profileData) {
await window.magicchat_io.setUp(
"v2_app1",
"bGVnYWwxMTFfX1NFUFJBVE9SX192Ml9hcHAx"
);
} else {
await window.magicchat_io.initialize({
app_version: "V2",
uid: profileData.username,
});
}
});
</script>ℹ️
Parameter Details
| Parameter | Type | Description |
|---|---|---|
| app_name | string | Unique application identifier |
| api_key | string | Base64 encoded API key |
⚠️
Critical Requirement
The setUp function must execute before initialize in all cases.
Example Implementation
View complete implementation examples in our GitHub repository:
Connecting Magicchat to Your Product’s Authentication
Backend Integration
For platforms with existing authentication systems, MagicChat requires user onboarding to establish identity mapping between your platform users and MagicChat accounts.
ℹ️
Key Integration Requirement
Each new user must be onboarded with a unique identifier (UID) that serves as the proxy between your platform and MagicChat's user management system.
Onboarding API
Successfully onboarded users will appear in the MagicChat Admin Panel with their associated applications.
1
Admin Panel - Onboarded Users
2
Admin Panel - No Users
Applications without onboarded users will display an empty state:
User Onboarding Methods
REST API Endpoint
Use our onboarding API to programmatically register users:
POST https://auth.addchat.tech/dev/onboardingRequest Example
curl --location 'https://auth.addchat.tech/dev/onboarding' \
--header 'X-API-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"uid": "unique_user_identifier_123",
"app_name": "your_application_name",
"version": "V2"
}'| Parameter | Type | Description |
|---|---|---|
| uid | string | Your platform's unique user identifier |
| app_name | string | Your registered MagicChat application name |
| version | string | for BYO Auth Chat API version is `V2` |
Logout Cleanup
Since authentication is managed locally within your own platform, it is essential to also clean up the MagicChat session when a user logs out from your system.
⚠️
Important Cleanup Step
Failing to call this method may result in session persistence, causing the chatbox to remain visible after logout.
Usage
window.magicchat_io.logout?.();You should call this method immediately when your user logs out. It ensures MagicChat cleans up all user-related sessions and data.
Example Implementation
See the following GitHub example where logout cleanup is properly handled:
ℹ️
Implementation Best Practices
- Trigger onboarding immediately after user registration
- For bulk onboarding of existing users, contact our support team for batch processing options
- Don't miss to logout to perform cleanup whenever user is logging out of your platform.
Congratulations! Your integration should now be successful!
Your users can now sign up and seamlessly chat with the Admin Team, enabling two-way communication.
Please contact our Support Team if you encounter any issues. Thank you!