Quadrillian Integration Guide - Embed Chat in Your Website

Integration Overview

Quadrillian integration involves two main concepts: understanding the user flow and implementing the setup.

How the Chat Flow Works

Here's what happens when a visitor interacts with chat on your website:

1. Visitor Clicks Chat

A visitor on your website clicks the chat button or widget to start a conversation.

2. Your Server Generates JWT

Your server creates a JWT token containing the visitor's user information and your workspace ID, signed with your workspace secret.

3. Browser Authenticates with Quadrillian

The visitor's browser receives the JWT and passes it to Quadrillian. Quadrillian verifies the signature and automatically provisions the user if they don't exist.

4. Chat Access Granted

The visitor can now access chat functionality within your workspace, with full workspace isolation and security.

Implementation Steps

To implement this flow, you need to:

1. Set Up Backend JWT Generation

Get your workspace secret from Quadrillian, then build server-side endpoints to generate JWT tokens containing user information.

2. Add Quadrillian Widget to Your Website

Include the Quadrillian widget on your website using simple HTML attributes - no complex JavaScript required.

Key Benefits: Secure server-to-server communication, workspace isolation, no credential exposure to browsers, and simple JavaScript integration.

Step-by-Step Setup

Let's get you started with Quadrillian integration using the secure JWT-based authentication flow. We'll build up from the basics to a working chat system.

Step 1: Set Up Backend JWT Generation

First, you'll need to set up server-side endpoints to generate JWT tokens. User provisioning happens automatically when users authenticate. Here's a minimal Node.js/Express example:

📚 API Reference: For complete details on JWT authentication and automatic user provisioning, see the API Reference - Authentication section.

📁 BACKEND CODE (Your Server)

File: server.js or your main server file

// Install required packages
npm install express jsonwebtoken node-fetch

// server.js
const express = require('express');
const jwt = require('jsonwebtoken');
const fetch = require('node-fetch');

const app = express();
app.use(express.json());

// Your Quadrillian credentials (store these securely!)
const QuadrillianConfig = {
  workspace_secret: 'your-workspace-secret',
  workspace_id: 456
};

// Endpoint to generate JWT for chat authentication
// IMPORTANT: This endpoint should be protected by your existing authentication middleware
app.post('/api/chat/auth', /* your auth middleware here */ async (req, res) => {
  try {
    // Get user info from authenticated session (not from request body)
    const external_user_id = req.user.user_id; // From your auth middleware
    const email = req.user.email; // From your auth middleware
    const name = req.user.name; // From your auth middleware
    
    // Generate JWT - user provisioning happens automatically when JWT is verified
    const token = jwt.sign({
      workspace_id: QuadrillianConfig.workspace_id,
      external_user_id: external_user_id,
      email: email,
      name: name,
      iat: Math.floor(Date.now() / 1000),
      exp: Math.floor(Date.now() / 1000) + (60 * 60 * 24) // 24 hours from now
    }, QuadrillianConfig.workspace_secret, { algorithm: 'HS256' });
    
    res.json({ jwt: token });
    
  } catch (error) {
    console.error('Auth error:', error);
    res.status(500).json({ error: 'Authentication failed' });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});
                    

Security: Store your API key and workspace secret securely on your server. Never expose these credentials to client-side code.

⚠️ Critical Security: The /api/chat/auth endpoint MUST be protected by your existing authentication middleware. Never accept user credentials from the request body - always get them from the authenticated session. This prevents user impersonation attacks.

Step 2: Add Quadrillian Widget to Your Website

Add the Quadrillian widget to your website using simple HTML attributes. The widget handles authentication automatically:

⚡ Quick Start: Use our Embed Code Generator to get your custom integration code instantly, or see the complete Quadrillian JavaScript SDK documentation for all available configuration options.

🌐 FRONTEND CODE (Your Website)

File: Your HTML file (e.g., index.html) - Choose your integration pattern:

Pattern 1: Professional API (Recommended)

<!-- Load SDK asynchronously -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>
<script>
  function openSupportChat() {
    Quadrillian.createChatWindow({
      workspace_id: "456",
      topic_external_key: "support-general"
    });
  }
</script>
<button onclick="openSupportChat()">Open Support Chat</button>
                    

🔐 For Authenticated Users

For authenticated users, use the professional API to get fresh JWT tokens from your backend:

Pattern 1: Professional API with JWT

<!-- Load SDK asynchronously -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>
<script>
  async function openAuthenticatedChat() {
    // Get fresh JWT from YOUR backend
    const response = await fetch('/api/chat/auth', {
      method: 'POST',
      credentials: 'include'
    });
    const { jwt } = await response.json();
    
    // Create chat with JWT
    Quadrillian.createChatWindow({
      workspace_id: "456",
      topic_external_key: "support-general",
      jwt_token: jwt
    });
  }
</script>
<button onclick="openAuthenticatedChat()">Start Chat</button>
                

Pattern 2: Commands Pattern (Auto-Execute)

<!-- Set up commands, SDK auto-executes when loaded -->
<script>
  window.Quadrillian = window.Quadrillian || {};
  window.Quadrillian.cmds = {
    openAuthenticatedChat: async function() {
      const response = await fetch('/api/chat/auth', {
        method: 'POST',
        credentials: 'include'
      });
      const { jwt } = await response.json();
      
      Quadrillian.createChatWindow({
        workspace_id: "456",
        topic_external_key: "support-general",
        jwt_token: jwt
      });
    }
  };
</script>
<!-- SDK will auto-execute when loaded -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>
                

🔄 Complete Authentication Flow:

User clicks chat button: Triggers loadChatWidget() function
Frontend calls backend: → fetch('/api/chat/auth', {credentials: 'include'})
Backend validates session: Uses existing auth middleware to verify user identity
Backend generates JWT: and returns it to frontend
Frontend loads widget: with JWT token in data attribute
Widget authenticates automatically: JWT is verified and user is provisioned

That's it! Your chat is now live with secure JWT-based authentication. Users will be automatically provisioned on Quadrillian when they first chat, and their sessions will be secure and isolated to your workspace.

🚀 Ready to Get Started?

Use our Embed Code Generator to get your custom integration code instantly. Just enter your workspace details and copy the generated code to your website!

Generate My Embed Code

Next Steps

Now that you have basic chat working, you can:

Create topics programmatically using the API Reference
Customize the chat appearance and behavior
Add file upload capabilities
Integrate with your existing user management system
Set up automated responses and AI integration

Check out the API Reference and Topic Strategies for more advanced use cases.

Troubleshooting

Common Issues

Widget Not Appearing

Possible causes:

Missing required data attributes
Invalid workspace ID or topic external key
Network connectivity issues

Solutions:

Ensure you've provided workspace_id in your createChatWindow() call
If using external key, make sure topic_external_key is provided along with workspace_id
Check browser console for error messages

JWT Authentication Failing

Possible causes:

Invalid JWT token
Expired JWT token
Wrong workspace secret

Solutions:

Verify JWT token is valid and not expired
Check that workspace secret matches the one used to sign the JWT
Ensure JWT contains required fields: workspace_id, external_user_id, exp

File Upload Issues

Possible causes:

File size exceeds limit
File type not allowed
Virus scan failure

Solutions:

Check file size (max 10MB)
Verify file type is allowed
Try uploading a different file

Debug Mode

Open your browser's developer console to see detailed logging from the Quadrillian SDK. The widget automatically logs important events and errors.

Support

Need help? Contact our integration team:

Email: integrations@quadrillian.com
Documentation: quadrillian.com/docs
Status Page: status.quadrillian.com