main.min.js Library/API Docs (JavaScript)

chattable.initialize(parameters)

Initializes the chattable interface. Waits for the iframe to be present, and then applies either a custom stylesheet or a named demo (theme). Your chat waits for this to run in order to load. Your iframe must have the ID chattable for this to run.

Parameters:

• stylesheet (optional) — URL of a CSS file to load (relative or absolute)
• theme (optional) — Name of a predefined theme
• none — If no parameters are given, the chat will load with no styles applied.

chattable.initialize({ stylesheet: "styles/chat.css" });

chattable.initialize().then(callback)

Runs a callback function after the iframe initializes.

chattable.initialize().then(function(){
  let name = chattable.user.name;
});

chattable.reinitialize(parameters)

Reloads styles and resends command registry to the iframe. Use this if the iframe reloads unexpectedly or needs to re-sync.

chattable.sendMessage(text, name?, flair?, perms?)

Sends a chat message to the iframe.

Parameters:

• text — Message body (string)
• name (optional) — Sender name override
• flair (optional) — Flair for the message
• perms (optional, default: true) — Send as current user (true) or a bot (false)

chattable.sendMessage("Hello world!", "Bot", "robot", false);

chattable.sendPayload(object)

Sends custom JSON data to each connected client, usually used for triggering client-side events or features.

chattable.sendPayload({
  type: "poke",
  value: "Alice"
});

chattable.setFlair(string)

Updates the user's flair and saves it to localStorage. Read more about flairs.

chattable.setFlair("flames");

chattable.minimize()

Minimizes the iframe with a smooth animation. Useful for toggling visibility or embedding collapsible interfaces.

chattable.maximize()

Restores the iframe to its previous height and style after minimizing.

chattable.changeRoom(chat_id)

Switches to a different chatroom by updating the iframe src.

chattable.changeRoom("123");

chattable.loadStyle(source) (async)

Loads a raw CSS file and sends it to the iframe as a style string.

chattable.loadTheme(name) (async)

Loads a named theme from predefined themes (case insensitive) extracted from the demos on the demo page (e.g., retrowave red, notepad, etc.).

chattable.on(event, callback)

Registers an event listener for either message or payload.

chattable.on("message", function(data){
  console.log("New message:", data);
});

chattable.off(event, callback)

Removes an event listener that was previously added via on.

chattable.user

An object containing information about the current user. This object is automatically populated when the chat initializes.

Properties:

• name — The user's display name in the chat
• flair — The user's current flair icon (if set)
• uid — The user's unique identifier (populated after initialization)

console.log(chattable.user.name); // Displays the current user's name

The user object persists the flair in localStorage if set via chattable.setFlair().

chattable.commands

An object where each property is a command name that can be triggered from the chat using the !commandName syntax. Each command is defined as a function that receives the full command text as its parameter.

Important: Commands must be set before calling chattable.initialize() to ensure they are properly registered with the chat iframe.

// Define commands before initialization
chattable.commands = {
  "poke": function(fullCommand) {
    // Extract the name from something like "!poke Alice"
    let name = fullCommand.replace(/^\!poke\s/i, "");
    chattable.sendPayload({
      type: "poke",
      value: name
    });
  },
  "clear": function() {
    // Command implementation
  }
};

// Then initialize the chat
chattable.initialize({ theme: "notepad" });

Command Processing Flow

When users interact with commands in the chat:

1. When a user types !commandName in the chat, the iframe detects this as a command
2. The command is sent to the parent page via postMessage
3. If the command exists in chattable.commands, its function is executed
4. Commands can interact with both the local page and the chat iframe

Command-Payload Interaction Example

Commands and payloads work together to create interactive features. Here's a complete example of a "poke" feature:

// Set up command handler
chattable.commands = {
  "poke": function(fullCommand) {
    let name = fullCommand.replace(/^\!poke\s/i, "");
    chattable.sendPayload({
      type: "poke",
      value: name
    });
  }
};

// Set up payload handler
chattable.on("payload", function(data) {
  switch(data.type) {
    case "poke":
      if(data.value == chattable.user.name) {
        alert("You have been poked!");
      } else {
        alert(data.value + " got poked!");
      }
      break;
    default: 
      break;
  }
});

// Initialize chat (after setting commands)
chattable.initialize({ theme: "retrowave red" });

Important Implementation Notes

1. Command Registration Order: Always define chattable.commands before calling chattable.initialize(). Commands defined after initialization may not be properly registered until a manual reinitialize() call.
2. Iframe ID Requirement: The Chattable iframe must have the ID chattable for the library to function properly.
3. CSS Customization: For the best experience, always provide either a stylesheet or theme parameter to initialize().
4. Payload Warning: When working with payloads, validate data to prevent unexpected behavior. Remember, payloads can only transport JSON.