Chattable Documentation

How do I style my chat?

Ensure your iframe element which hosts the chat has the ID set to chattable in your HTML. This is critical the Chattable JS Library to locate and finish loading the chat. Alternatively, you can use the postMessage method to style & skip loading without the library.

Add the Chattable Library to your site by including this in your <head> element:

<script src="https://iframe.chat/scripts/main.min.js"></script>

Initialize your chat (required for loading):

<script>
  chattable.initialize({
    stylesheet: "chattable.css",
  });
</script>

Ensure chattable.css is in the same folder as your HTML file. The CSS is sent to the iframe to style the chat before rendering. Without initialization, the chat won't load. Use our pre-built themes or a blank CSS file for an unstyled chat.

Using Prebuilt Themes

Choose a theme from our demos and initialize like this:

<script src="https://iframe.chat/scripts/main.min.js"></script>
<script>
  chattable.initialize({
    theme: "Retrowave Red"
  });
</script>

Replace Retrowave Red with your preferred demo theme. Play around and customize a theme's CSS on the demo page.

Styling Tips

Recommended iframe height & width: 250px or greater.
Do not adjust #background, #top_banner, or input area dimensions to maintain user experience.
JavaScript resizes #background and #input based on banner visibility. Disable with:

:root {
  --advanced-layout: true;
}

Use display: none; to hide #top_banner or other elements.
Use the background CSS property for the #top_banner instead of background-color (default is a gradient).
Adjust chat size via iframe's height & width values.

Custom User Flairs

Introduced in March 2025, custom user flairs enhance chat personalization. Learn more here.

Custom Fonts

For web hosts with CORS restrictions, use:

A file hosting service like catbox.moe for resource URLs.
Data URIs (convert files using admin booster's tool). Note: Data URIs increase load times due to their size.

CORS Errors? (postMessage Method)

For CORS issues (e.g., local editing), style your chat using JavaScript:

<script>
  window.addEventListener("load", function(){
    document.getElementById("chattable").contentWindow.postMessage(`
      body {
        /* Your CSS here */
      }
    `, "*");
  });
</script>

Most sites don't face CORS/CSP issues when using Chattable as intended.

Changing Your Notification Sound

Customize notification sound via CSS variable --notification-sfx:

:root {
  --notification-sfx: https://example.com/path/to/audio.mp3;
}

Note: You can also use the keyword none instead of a URL to disable the default notification sound. All URLs must be absolute URLs and not relative paths since the CSS is rendered on iframe.chat

Predefined CSS Classes & IDs

Chattable's structured layout uses intuitive classes and IDs for easy styling. See the full list here.

Message Markdown

Chats support markdown for text formatting. Examples:

Syntax	Result
`Hello World`	Hello World
`Hello World`	Hello World
`~~Hello World~~`	~~Hello World~~
`Hello World`	`Hello World`
`>Hello World`	Hello World
`[Link](https://iframe.chat/help/)`	Link
`![Alt Text](https://iframe.chat/c.png)`	(Image)

Chat Commands

Commands are categorized into 2 subcategories: custom and default commands. Custom commands are commands created by you and are unique to your chat, and default commands are built into every chat and can not be removed or customized. These subcategories are futher explained below.

Default Commands

Syntax	Description	Roles
`!connect`	Disconnects & reconnects to another chat.	All Users
`!online`	Shows current online users.	All Users
`!tutorial`	Runs tutorial for name changes, settings, etc.	All Users
`!help`	Runs tutorial command.	All Users
`!clear`	Clears the chat.	Owner & Moderators
`!attach [src]`	Attaches a document or file to a new message.	Owner & Moderators
`!lock`	Locks chat to Moderators & Owner.	Owner
`!unlock`	Unlocks chat for all.	Owner
`!reset`	Resets permissions, kicked/banned users, moderators.	Owner

Custom Commands

Introduced in March 2025, custom commands are declared client side JavaScript and must be declared before you initialize your chat. It is important to note that all custom commands are executed on your site, not iframe.chat. This allows you to perform actions on your site when a command is called in-chat. These custom commands are localized to the user who called the command, meaning calling any custom command won't execute code on any device other than the one that called the command.

Here is an example of how to declare two custom commands,

// Declare chattable.commands obj
chattable.commands = {
  "test" : function(){
    chattable.sendMessage("!test works.");
  },
  echo: function(fullstring){
    fullstring = fullstring.replace(/^!echo\s/i, "");
    chattable.sendMessage(text.trim());
  },
};
// Then, initialize the chat to proceed with loading
chattable.initialize({
  stylesheet: "chattable.css"
});

The Chattable Library includes many advanced options for scripting a more customized chatting experience. Learn More

Custom Emojis

Chat owners can set custom emojis via the dashboard. Add a URL and alias (e.g., "smiley_face") for each emoji.

Chattable API / Library

The API enables styling, custom commands, flairs, message handling, and more. Learn more here.

Frequently Asked Questions

Q: Can I delete/edit my messages?

A: Yes. Right-click your message for options. Owners/moderators can manage others' messages.

Q: I lost my chat link and/or chat ID

A: Visit the dashboard with the account that created the chat to view, moderate, or get embed instructions.

Q: Can I remove/alter the "Chattable" logo/banner?

A: Yes. Modify #top_banner in CSS or hide with display: none;.

Q: Why is my chat infinitely loading?

A: Initialize the chat with a stylesheet or send an empty CSS string via postMessage. Ensure you're initializing the chat after the iframe has been loaded.

Q: Can I edit the HTML?

A: Not directly, but use the alternate layout: https://iframe.chat/embed/alternate?chat=YOUR_CHAT_ID.

Q: How can I get visitors to set their names?

A: Add instructions near the chat, use !help, modify #settings icon, or create an alternate layout using th Chattable Library.

Q: Can I have multiple chats on one page?

A: Yes, but you'll need to embed chats in separate HTML files using iframes to avoid ID conflicts since only one iframe per document can have the ID "chattable".

Support

Chattable is in perpetual development. For issues, include screenshots of console errors (open dev tools with CTRL+SHIFT+I or right-click > inspect). Contact us on Reddit at r/ChattableDevs or email chattable@xobyte.org.

Topics

Chattable Help