Quadrillian JavaScript SDK

The Quadrillian JavaScript SDK provides professional-grade chat integration with multiple patterns for different use cases. It supports both simple one-line integration and advanced programmatic control.

⚡ Quick Start: Use our Embed Code Generator to get your custom integration code instantly! No need to read through all the documentation - just enter your workspace details and copy the generated code.
Key Features:
  • Multiple integration patterns (manual control, commands auto-execution)
  • JWT-based authentication
  • Real-time messaging
  • Topic-based conversations
  • Multiple chat instances on same page
  • Professional API design
  • Automatic user provisioning
  • Async loading support

Installation

Choose the integration pattern that best fits your needs:

Professional API Integration

<!-- Professional async loading -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>
<script>
  function openSupportChat() {
    Quadrillian.createChatWindow({
      workspace_id: "456",
      topic_external_key: "support"
    });
  }
</script>
<button onclick="openSupportChat()">Open Support Chat</button>
Professional Benefits: The professional API supports multiple chat instances, async loading, and programmatic control while maintaining backward compatibility.

Integration Patterns

The SDK supports three main integration patterns for different use cases:

Pattern 1: Manual Control (Most Flexible)

<!-- Load SDK asynchronously -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>

<!-- Create chat instances programmatically -->
<script>
  function openSupportChat() {
    Quadrillian.createChatWindow({
      workspace_id: "456",
      topic_external_key: "support",
      position: "bottom-right",
      width: 400,
      height: 600
    });
  }
</script>

<button onclick="openSupportChat()">Open Support Chat</button>

Pattern 2: Commands Pattern (Auto-Execute)

<!-- Set up commands before SDK loads -->
<script>
  window.Quadrillian = window.Quadrillian || {};
  window.Quadrillian.cmds = {
    openSupportChat: function() {
      Quadrillian.createChatWindow({
        workspace_id: "456",
        topic_external_key: "support"
      });
    }
  };
</script>

<!-- SDK will auto-execute ALL commands when loaded -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>
Commands Pattern: The SDK automatically executes all functions in window.Quadrillian.cmds when it loads. This is perfect for auto-opening chat windows on page load.
⚡ Quick Start: Use our Embed Code Generator to get your custom integration code instantly!
Choose Your Pattern: Use Pattern 1 for manual control, Pattern 2 for auto-executing commands when SDK loads.

API Reference

The Quadrillian SDK provides a professional API for creating and managing chat instances:

Core Methods

Quadrillian.createChatWindow(config)
Creates a new chat window instance with the specified configuration.
config.workspace_id (string, required)
Your workspace ID
config.topic_external_key (string, optional)
External topic key for the conversation
config.jwt_token (string, optional)
JWT token for user authentication
config.ai_user_id (number, optional)
AI user ID to automatically add to the topic when created
config.position (string, optional)
Widget position: "bottom-right", "bottom-left", "top-right", "top-left" (default: "bottom-right")
config.width (number, optional)
Widget width in pixels (default: 400)
config.height (number, optional)
Widget height in pixels (default: 600)
config.autoOpen (boolean, optional)
Whether to open the chat immediately (default: true)
Quadrillian.getInstance(instanceId)
Returns a chat instance by its ID for programmatic control.
Quadrillian.closeAll()
Closes all open chat windows.
Quadrillian.isReady()
Returns true if the SDK is loaded and ready to use.

Instance Methods

Each chat instance returned by createChatWindow() provides these methods:

instance.open()
Opens the chat window
instance.close()
Closes the chat window
instance.destroy()
Removes the chat window from the DOM

Authentication

Quadrillian supports JWT-based authentication for secure user identification:

<!-- Professional API with JWT Authentication -->
<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>
Automatic User Provisioning: When a user authenticates with a JWT token, Quadrillian automatically:
  • Creates the user if they don't exist
  • Links existing users by email if found
  • Associates the user with your workspace
  • Handles all user management automatically

JWT Token Structure

Your backend should create JWT tokens with this payload:

// JWT payload structure
{
  "workspace_id": 456,
  "external_user_id": "user_123",
  "email": "user@example.com",
  "name": "John Doe",
  "exp": 1704067200
}
Security: JWT tokens must be signed with your workspace secret using the HS256 algorithm. See the API Reference for details on JWT key management.

Complete Examples

Multiple Chat Windows

<!-- Load SDK once, create multiple instances -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>

<script>
  // Support chat
  function openSupport() {
    Quadrillian.createChatWindow({
      workspace_id: "456",
      topic_external_key: "support",
      position: "bottom-right"
    });
  }
  
  // Sales chat with AI assistant
  function openSales() {
    Quadrillian.createChatWindow({
      workspace_id: "456",
      topic_external_key: "sales",
      ai_user_id: 5267, // AI assistant user ID
      position: "bottom-left"
    });
  }
</script>

<button onclick="openSupport()">Support</button>
<button onclick="openSales()">Sales</button>

Authenticated Chat with Dynamic JWT

<!-- Get JWT from your backend when user wants to chat -->
<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: "user-session",
      jwt_token: jwt
    });
  }
</script>

<button onclick="openAuthenticatedChat()">Start Chat</button>

Commands Pattern with Auto-Execution

<!-- Set up commands, SDK executes them when ready -->
<script>
  window.Quadrillian = window.Quadrillian || {};
  window.Quadrillian.cmds = {
    openSupportChat: function() {
      Quadrillian.createChatWindow({
        workspace_id: "456",
        topic_external_key: "support"
      });
    },
    openSalesChat: function() {
      Quadrillian.createChatWindow({
        workspace_id: "456",
        topic_external_key: "sales"
      });
    }
  };
</script>

<!-- SDK will auto-execute ALL commands when loaded -->
<script async src="https://quadrillian.com/js/chat/sdk.js"></script>

Programmatic Control

<script>
  let chatInstance;
  
  function createChat() {
    chatInstance = Quadrillian.createChatWindow({
      workspace_id: "456",
      topic_external_key: "support",
      autoOpen: false // Don't open immediately
    });
  }
  
  function toggleChat() {
    if (chatInstance) {
      chatInstance.open();
    }
  }
  
  function closeChat() {
    if (chatInstance) {
      chatInstance.close();
    }
  }
</script>

Troubleshooting

Common Issues

  • Widget not appearing: Check that you've provided workspace_id in your createChatWindow() call
  • External key not working: Ensure you've provided topic_external_key along with workspace_id
  • JWT authentication failing: Verify your JWT token is valid and not expired
  • Widget not loading: Check browser console for error messages
  • SDK not ready: Use Quadrillian.isReady() to check if the SDK has loaded

Debug Mode

Open your browser's developer console to see detailed logging from the Quadrillian SDK.

Support

Need help? Contact our integration team: