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:

Example:

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

chattable.initialize().then(callback)

Runs a callback function after the iframe initializes.

Example:

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.

Parameters:

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

Sends a chat message to the iframe.

Parameters:

Example:

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. Payloads are limited to 500b of data.

Example:

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

chattable.setFlair(string)

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

Example:

chattable.setFlair("flames");

chattable.setName(string)

Updates the user's name on Chattable. This will trigger a popup dialogue from the website asking permission from the user first.

Example:

chattable.setName("Andrew");

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.

Example:

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 to handle real-time events.

Example:

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

message event

The message event fires a callback function every time a new message is received in the chat. The callback function is passed an object with the following keys:

payload event

The payload event fires a callback function every time a payload is received. The callback function is passed a copy of the data that was carried in the payload. Note that this data can only contain JSON.

connection event

The connection event fires a callback function every time a user connects or disconnects from the chat. The callback function is passed an object filled with the uid & names of each connected user. Here's an example of an object that was passed to the callback function when a new user joined the chat:

Example:

{
  "824459503": "Anonymous#1355",
  "123456789": "John Doe",
  // etc...
}

load event

The load event fires a callback function once the chat is loaded & all data is initialized. This is when other saved variables like chattable.user.name become available for use.

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:

Example:

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.

Example:

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

Command Callback Parameters

Command callback functions receive two parameters:

Example:

// Remember: Define commands before initialization
chattable.commands = {
  "login": function(fullCommand, data) {
    if(data.isMod){ // if the sender is a moderator,
      // perform the task.
    }
  }
};
chattable.initialize({ stylesheet: "/style.css" });

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:

Example:

// 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.

Warning: The server is scripted to combat spammers. Be cautious not to spam the server with data using methods from this API or derivative works of this API. Doing so may cause you to temporarily lose access to all of chattable's services.