ModuLink AI Integration Guide

Getting Started

1. Initial Setup

Follow these steps to get ModuLink AI integrated into your project:

Create an account — Sign up at ModuLink AI and access your dashboard.
Add an AI Provider — Go to Dashboard → AI Providers and connect at least one provider (OpenAI, Anthropic, Gemini, etc.) with your API key.
Create a Project — Go to Dashboard → Connected Projects and create a project for your website or app. Configure the bot name, tone, system prompt, and knowledge base.
Generate an API Key — Go to Dashboard → API Keys and create a key linked to your project.

2. Your API Key

⚠️ REQUIRED: Every API request requires your API Key. Without it, requests will be rejected with a 401 Unauthorized error.

How to get your API Key:

Log in to your ModuLink AI Dashboard
Go to Dashboard → API Keys
Click "Generate New Key"
Give it a name (e.g., "My Website Widget")
Copy the key (starts with mlk_)

API Key Format

Your API key is the public identifier (starts with mlk_):

API Key — Public identifier (starts with mlk_). Example: mlk_Fwp7ZkJ4RjvRevZF65xC2AER4kj35jDJavLkBimi49U8jhd1

🔒 Security Note: API keys have built-in rate limiting. You can set per-minute limits and expiry dates in the dashboard. Rotate keys regularly for production use.

Chat Widget Integration

Basic Widget Embed

Add the ModuLink AI chat widget to any website with just a few lines of code. Place this before the closing </body> tag:

<!-- ModuLink AI Chat Widget -->
<script src="https://modulinkai.mas.codes/api/v1/widget.js"></script>
<script>
  ModuLinkChat.init({
    // ⚠️ REQUIRED: Your API key from Dashboard → API Keys
    apiKey: 'mlk_your_api_key_here',

    // Optional: Position - 'bottom-right' (default) or 'bottom-left'
    position: 'bottom-right',

    // Optional: Theme - 'dark' (default) or 'light'
    theme: 'dark',

    // Optional: Chat window title
    title: 'Chat with us',

    // Optional: URL to full-page chat (opens when user clicks "Full Page" button)
    fullPageUrl: 'https://yourdomain.com/ai-chat.html'
  });
</script>

That's it! A floating chat button will appear in the bottom-right corner of your page. Users can click it to open the chat window and start talking to your AI assistant.

Required Credentials

When you create an API key in the dashboard, you will receive an API Key (starts with mlk_). This is what you use in your code.

Available Configuration Options

apiKey — Required. Your ModuLink API key (starts with mlk_). Get it from Dashboard → API Keys.
position — Widget position: 'bottom-right' or 'bottom-left'. Default: 'bottom-right'.
theme — Color theme: 'dark' or 'light'. Default: 'dark'.
title — Header title text. Default: 'Chat with us'.
fullPageUrl — URL to your dedicated full-page chat. When set, a "Full Page" button appears in the widget header that opens this URL. Example: 'https://yourdomain.com/ai-chat.html'

Custom Styling

You can customize the widget's appearance by adding this CSS to your stylesheet. All selectors use !important to override the widget's inline styles:

Option 1: Include our pre-made CSS file in your HTML <head>:

<link rel="stylesheet" href="https://modulinkai.mas.codes/assets/css/widget-custom.css">

Option 2: Copy the CSS below to your own styles.css file:

/* === MAIN ELEMENTS === */
#mlk-fab { /* Floating button */
  width: 70px !important;
  height: 70px !important;
  background: linear-gradient(135deg, #e11d48, #be123c) !important;
}

#mlk-win { /* Chat window */
  width: 450px !important;
  height: 650px !important;
  border-radius: 20px !important;
}

#mlk-go { /* Send button */
  background: linear-gradient(135deg, #e11d48, #be123c) !important;
}

#mlk-in { /* Input field */
  border-radius: 12px !important;
}

/* === UTILITY CLASSES === */
.mlk-m { /* Message bubbles */
  margin-bottom: 14px !important;
}

.mlk-hb { /* Header buttons (New, Full Page, Close) */
  background: rgba(255,255,255,0.12) !important;
  border-radius: 8px !important;
}

.mlk-cd { /* Product cards */
  border-radius: 14px !important;
}

.mlk-ab { /* Action buttons */
  padding: 8px 14px !important;
  border-radius: 8px !important;
}

/* === MOBILE === */
@media (max-width: 500px) {
  #mlk-win {
    width: 100% !important;
    height: 100% !important;
    border-radius: 0 !important;
  }
}

Full CSS file: Download widget-custom.css for all available selectors including animations, scrollbars, and mobile styles.

Dedicated AI Page

Full Page Chat Interface

Some projects need a full-page AI chat experience instead of a floating widget. Here's a complete, copy-paste HTML page you can host on your site:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>AI Assistant</title>
  <style>
    * { margin:0; padding:0; box-sizing:border-box; }
    body { font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
           background:#0f0f23; color:#e0e0e0; height:100vh; display:flex; flex-direction:column; }
    .header { background:linear-gradient(135deg,#6366f1,#8b5cf6); padding:16px 24px; color:#fff; }
    .header h1 { font-size:18px; font-weight:600; }
    .header p { font-size:12px; opacity:0.8; }
    .messages { flex:1; overflow-y:auto; padding:20px 24px; }
    .msg { display:flex; gap:12px; margin-bottom:16px; max-width:80%; }
    .msg.user { margin-left:auto; flex-direction:row-reverse; }
    .msg .avatar { width:32px; height:32px; border-radius:50%; display:flex;
                   align-items:center; justify-content:center; font-size:14px; flex-shrink:0; }
    .msg.user .avatar { background:#6366f1; color:#fff; }
    .msg.ai .avatar { background:#10b981; color:#fff; }
    .msg .bubble { padding:12px 16px; border-radius:12px; line-height:1.6; font-size:14px; }
    .msg.user .bubble { background:#6366f1; color:#fff; border-bottom-right-radius:4px; }
    .msg.ai .bubble { background:#1e1e3a; border:1px solid #2a2a4a; border-bottom-left-radius:4px; }
    .input-area { padding:16px 24px; border-top:1px solid #2a2a4a; display:flex; gap:10px; }
    .input-area input { flex:1; padding:12px 16px; border-radius:12px; border:1px solid #2a2a4a;
                        background:#1e1e3a; color:#e0e0e0; font-size:14px; outline:none; }
    .input-area input:focus { border-color:#6366f1; }
    .input-area button { padding:12px 24px; border-radius:12px; border:none;
                         background:linear-gradient(135deg,#6366f1,#8b5cf6); color:#fff;
                         cursor:pointer; font-size:14px; font-weight:600; }
  </style>
</head>
<body>
  <div class="header">
    <h1>AI Assistant</h1>
    <p>Powered by ModuLink AI</p>
  </div>
  <div class="messages" id="messages"></div>
  <div class="input-area">
    <input type="text" id="input" placeholder="Type a message..." autocomplete="off">
    <button onclick="sendMessage()">Send</button>
  </div>

  <script>
    // ⚠️ REQUIRED: Your API Key from Dashboard → API Keys
    var API_KEY = 'mlk_your_api_key_here';
    var BASE_URL = 'https://modulinkai.mas.codes';
    var conversationId = null;

    // Start or resume conversation
    function startChat() {
      var sessionId = sessionStorage.getItem('mlk_session_id');
      apiCall('/api/v1/chat/start', 'POST', { session_id: sessionId }, function(data) {
        conversationId = data.conversation_id;
        sessionStorage.setItem('mlk_session_id', data.session_id);
        if (data.resumed) {
          apiCall('/api/v1/chat/messages?conversation_id=' + data.conversation_id, 'GET', null, function(hist) {
            if (hist.messages) hist.messages.forEach(function(m) { addMsg(m.role, m.content); });
          });
        } else {
          addMsg('ai', 'Hello! How can I help you today?');
        }
      });
    }

    function sendMessage() {
      var input = document.getElementById('input');
      var msg = input.value.trim();
      if (!msg || !conversationId) return;
      input.value = '';
      addMsg('user', msg);

      apiCall('/api/v1/chat/message', 'POST', {
        conversation_id: conversationId, message: msg
      }, function(data) {
        if (data.message) addMsg('ai', data.message.content);
      });
    }

    function addMsg(role, text) {
      var el = document.getElementById('messages');
      var cls = role === 'user' ? 'user' : 'ai';
      var icon = role === 'user' ? '👤' : '🤖';
      el.innerHTML += '<div class="msg ' + cls + '">' +
        '<div class="avatar">' + icon + '</div>' +
        '<div class="bubble">' + escapeHtml(text) + '</div></div>';
      el.scrollTop = el.scrollHeight;
    }

    function apiCall(path, method, body, cb) {
      var opts = { method: method, headers: {
        'Content-Type':'application/json','Accept':'application/json',
        'X-API-Key': API_KEY }};
      if (body) opts.body = JSON.stringify(body);
      fetch(BASE_URL + path, opts).then(function(r){return r.json()}).then(cb);
    }

    function escapeHtml(s) { var d=document.createElement('div'); d.textContent=s; return d.innerHTML; }

    document.getElementById('input').onkeydown = function(e) {
      if (e.key === 'Enter') sendMessage();
    };

    startChat();
  </script>
</body>
</html>

Iframe Embed

If you prefer to embed the AI page inside an existing page using an iframe, save the above HTML as a separate file (e.g., ai-chat.html) and embed it:

<iframe
  src="/ai-chat.html"
  style="width:100%; height:600px; border:none; border-radius:12px;"
  allow="clipboard-write"
></iframe>

Session Handling

How Sessions Work

ModuLink AI uses session-based conversation management to maintain chat history:

Session ID — Each conversation gets a unique session_id (UUID). This is stored in the browser's sessionStorage.
Automatic Resume — When a user returns, the widget sends the stored session_id to the /api/v1/chat/start endpoint. If a matching conversation exists, it resumes with full message history.
New Session — When sessionStorage is cleared (browser close, new tab), a new session and conversation are created automatically.
Per-User Isolation — Sessions are scoped to your API key and user account. Different API keys create separate conversation pools.

Supabase Persistence

For cross-device persistence, connect Supabase in your dashboard. All conversations and messages are automatically synced to your Supabase project, giving you full data ownership and the ability to query chat history from your own backend.

Custom Session Management

// Generate your own session ID for logged-in users
var sessionId = 'user_' + yourUserId + '_' + Date.now();

// Pass it when starting a conversation
fetch('https://modulinkai.mas.codes/api/v1/chat/start', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    // ⚠️ REQUIRED: Your API Key
    'X-API-Key': 'mlk_your_api_key_here'
  },
  body: JSON.stringify({
    session_id: sessionId
  })
});

API Reference

REST API Endpoints

⚠️ Authentication Required: All API endpoints require the X-API-Key header with your ModuLink API key. Requests without a valid API key will return a 401 Unauthorized error.

Request Headers

Content-Type: application/json
Accept: application/json
X-API-Key: mlk_your_api_key_here  // ⚠️ REQUIRED - Get from Dashboard → API Keys

POST /api/v1/chat/start

Start or resume a conversation.

// Request
{ "session_id": "optional-session-uuid" }

// Response
{
  "conversation_id": 1,
  "session_id": "uuid-string",
  "title": "Widget Chat",
  "provider": "OpenAI",
  "model": "gpt-4",
  "project": "My Website",
  "resumed": false
}

POST /api/v1/chat/message

Send a message and receive an AI response.

// Request
{
  "conversation_id": 1,
  "message": "What products do you have?"
}

// Response
{
  "message": {
    "role": "assistant",
    "content": "Here are our products...",
    "content_type": "text",
    "tokens": 150
  }
}

GET /api/v1/chat/messages

Retrieve message history for a conversation.

// Request: GET /api/v1/chat/messages?conversation_id=1

// Response
{
  "conversation_id": 1,
  "title": "Widget Chat",
  "messages": [
    { "role": "user", "content": "Hello", "content_type": "text", "tokens": 0 },
    { "role": "assistant", "content": "Hi! How can I help?", "content_type": "text", "tokens": 12 }
  ]
}