Documentation

Creating a room

Sign up in the control panel, name the room, choose the address it will live on and save. Every room has a permanent address of the form /chat/<id>, for example /chat/1, which opens on its own with no embedding at all.

The panel is organised in tabs. Each tab below is documented in the order the panel shows it, and the names match what you see on screen.

Choosing a plan

One room runs on one address, whichever plan you are on. Basic runs 1 chat room on 1 domain, Premium allows up to 15. Premium lets the same account run up to fifteen rooms, each one pinned to the domain it was given. Plans are managed from Plans and billing in the panel.

First steps

A room works the moment it exists, so these four things are simply the order most owners follow before they invite anyone.

• Set the room's identity. Name, topic and colours live in Settings, and the address in the Website field is also the domain the room may be embedded from.
• Decide who may enter. Registration, guest entry and the age rules are all on the Members tab of Settings.
• Hand out ranks. Ranks decide who counts as staff, and Permissions decides what each rank may do.
• Put the room on your site. Copy the iframe snippet from the Embed API page, or link straight to /chat/<id>.

Nothing here is permanent. Settings, ranks and the embed can all be changed later without moving the room's address.

The embed key

Every room carries one embed key, issued on the Embed API page of the control panel. It is the credential a page presents when it embeds a room it does not own, sent on the frame address as ?key=.

One key exists per room and it holds until you regenerate it. Only the panel ever shows it, so it is handled like a password rather than a public value.

The iframe snippet

A room lives at a permanent address of the form /chat/<id>. Drop an iframe on it and the room fills the frame. This is the form the control panel hands you on the Embed API page, with the key already in place.

<iframe
    src="https://www.chatsocket.net/chat/1?key=YOUR_KEY"
    title="Chat room"
    width="100%"
    height="640"
    loading="lazy"
    style="border:0;border-radius:12px">
</iframe>

Swap 1 for your room id and YOUR_KEY for the key on the Embed API page. The frame works inside a page builder, a CMS, a wiki or plain HTML.

Script loader

When the room should fill a container you already have, use the loader instead. It reads the room and key from the tag and sizes the frame to fit.

<div id="chatsocket-room" style="height:640px"></div>
<script src="https://www.chatsocket.net/embed/chatroom.js"
        data-room="1"
        data-target="chatsocket-room"
        data-key="YOUR_KEY"
        defer></script>

Attributes on the loader

The loader validates every value before it uses it, so a mistyped attribute produces a message in the browser console instead of a broken frame.

Query parameters

There are no other parameters. Theme, entry policy and moderation are decided in the control panel, so a visitor cannot change how your room runs by editing the URL.

Allowed domain

Each room runs on a single domain: the address in the Website field of its settings. Open Embed API in the control panel to read it and, on Premium, to change it. A frame opened from that address needs no key at all.

Basic runs 1 chat room on 1 domain. Premium allows up to 15, each room on the domain it was given.

Who may embed the room

Before a frame renders, one of these has to hold:

• The key matches. The address carries ?key= and it is the key issued for this room.
• The domain is allowed. The address carries no key, and the page comes from your room's own address or from a domain on your allowed list.

Anything else shows the credentials screen instead of the room. An ordinary link to /chat/1 is never treated as an embed, so sharing the address keeps working.

Sizing

Error screens

Credentials screen

Shown when neither rule above holds. The visitor sees a plain message with the room name, and no part of your chat.

The message itself reads That Chat Cant Work Incorrect Credentials Detected, so searching for those words brings whoever is wiring the frame straight to this table.

Regenerating the key

The Embed API page has a Regenerate key action. It asks for your account password first, because every site already using the old key stops working immediately. The new key then lands in place and the copy code box shows it without a reload.

• Regenerate the moment a key reaches a public repository or a public ticket.
• Treat it as a breaking change: every site still holding the old snippet stops showing the room.
• Paste the new snippet wherever the room is embedded before you close the panel.

HTTPS and cookies

The room is served over HTTPS, so it only opens on a page served over HTTPS as well. It sets one cookie to remember who is signed in, and there is no tracking script of any kind inside the frame.

Quick reference

Dashboard

The dashboard is the command deck for the room. The room card carries the name, the plan badge, the online or paused state, the plan state, how many members are online now and how many accounts need attention.

Under it sit the member counts as live figures: users, muted, banned, admins, moderators, custom ranks and the room's RJ and DJ accounts.

General

Members

The Members tab decides who may join an account in the room and at what age.

Appearance

Media

Voice

Security

API Settings

The screen for keys borrowed from other services. It sits beside Settings in the sidebar, and only what is listed here is on it.

Images

Each image has a choose button and a remove button. Removing one returns the room to the default.

Sounds

A list of room events with a sound for each and a switch beside it. Pick a sound from the list, switch it on, and save. Events left switched off stay silent. The list covers messages, direct messages, joins, leaves, kicks, bans, points and the microphone.

Points

Points are held per account and shown on profiles. The whole feature belongs to the plan, so it can be switched off by the plan itself as well as by these numbers.

Pages

On the kick page, #kickTimer receives the countdown until the person can rejoin and #kickIcon receives the kick image. On the ban page, #banIcon receives the ban image. Leave those elements out and the page simply shows as written.

Other

Saving

Settings are saved from the Save button at the bottom of the panel. The screen stays where it is: the answer comes back as a short notice, so the tab, the scroll position and anything half typed are kept.

Room changes reach the chat within a few seconds. Appearance changes are visible the moment you save, because the room reads them on the next paint.

AI

The AI page runs a bot that sits in the room as a member. Anyone can talk to it by mentioning its name, in the main chat or in a direct message, and it answers in the language each message is written in.

Providers

Switches the bot on, sets the primary provider, and turns on the provider rotator, which tries your providers in order until one answers so a rate limit on one service does not stop the bot.

Keys & Models

One card per provider, each holding an API key and a model pick list. The keys are yours: provider usage bills to your own provider account, and ChatSocket adds no charge on top. The list ends with Another model id for any model the provider offers that is not listed, and a Test connection button checks the key and model before you save. Saved keys are never shown again; leaving the field empty keeps the one already stored.

Bot

The bot's identity and manner: name, avatar, bio, text streaming, the language it answers in and whether it may read feeds for videos and news. Show in member list hides the bot from the list without stopping it answering mentions. Members reach it by writing its name with or without @, or by quoting one of its answers, and every answer quotes the message it replies to. The video and news command words are renamed here; the command list below always shows the live words. A free GNews key gives the room its own news quota instead of the shared feed.

Images

The command members type to have a picture drawn, the image service that draws it, and the key for that service. Rooms generate one picture per minute; faster taps hear when to retry. Cloudflare Workers is the free service: it needs a worker address and key, and the page carries the setup script. Videos arrive as the same preview card members get when they paste a link: thumbnail first, player on click. The news command alone brings the latest headlines; with a topic it narrows the search. A free GNews key gives the room its own news quota instead of the shared feed.

Moderation

Smart moderation checks text and pictures before they appear and holds anything harmful. Text and images can be checked separately, and an optional key is used only for moderation.

Configuration

Temperature, the system prompt that tells the bot how to behave, memory over recent messages, how many messages are kept for context and the token cap on each answer.

Supported providers

• OpenAI
• Anthropic Claude
• DeepSeek
• xAI Grok
• Groq
• OpenRouter
• Cerebras
• Mistral
• Google Gemini

Ranks

Ranks are listed strongest first, and each one is defined by three things only: its order, its name and its icon. Deleting a rank moves its members down to the lowest rank, and a room may hold up to twenty ranks.

The Owner rank cannot be deleted. The Bot rank is system generated for the AI feature and is invisible in the list: it cannot be renamed, deleted, moved or assigned to a member.

Members management

The Members page is a live list of every account in the room with its rank and current state, counts along the top for all, banned, muted and kicked, and a search by username.

The Action button reads the member's state before it offers anything: a banned account is offered Unban, a muted one Unmute, a kicked one Unkick, and an account with nothing on record is offered Mute, Kick or Ban with a duration and a reason. Edit Rank opens a modal that moves the member to any rank, Owner included.

Permissions

The permissions matrix sets what each rank may do, in four blocks: staff actions such as kick, mute, ban, deleting messages and pinning; member actions such as direct messages, voice, calls and uploads; the profile fields a staff rank may edit on somebody else; and messages and media, which holds editing your own chat and DM messages plus posting GIFs, YouTube videos and stickers.

Higher ranks pick up anything ticked for the ranks beneath them, so a permission granted once covers the ranks above it. The Owner row shows full access and is locked.

Editing happens from the message menu: Edit loads the text into the input with an editing ribbon above it. Send saves the change and marks the message edited, the X drops it, and sending the same text simply stops editing. YouTube links are checked wherever they are pasted, and the sticker tray answers to its own switch. Reactions live on messages too: pick one from the menu, tap a badge to join it, and hover a badge to see who is in. The React switch gates the whole feature.

Reaction tray

Five quick emoji sit in front with a plus button. The plus opens 20 more unique ones, never the same five again.

Emojis

The Emojis page holds three tabs. Emojis lists every static picture, Stickers every animated one, and Reactions holds the keyboard characters members can react with, plus any custom one you add. Owners group codes into named categories with icons, and the chat picker shows those categories as tabs with a star for personal favourites.

Members keep their own favourites from the star tab: anything added or removed updates immediately, and removing a favourite never deletes the picture itself.

Action history

Every panel action on a member is recorded with who applied it, what was applied and the reason given, and the record is read from that member's profile.

Reading it is gated by the view_history permission on the Permissions page, and the room owner always has it whatever the matrix says.

Cloud storage

Cloud storage keeps the room's uploads in your own bucket instead of on the server running the chat. One provider is used at a time: Amazon S3 or Cloudflare R2, with the credentials, region and bucket name for it.

Plans

The plans page shows what is running on the room now, lets you activate a plan or move to another one, lists what the current plan includes, and holds one invoice row for every billing month of the room. Features unlock the moment a payment is received. Basic at $9 a month runs one room with the full chat, points, filters, profile music, voice messages, the public listing and the embed key. Premium at $19 a month runs up to 15 rooms and adds captcha, voice broadcast, custom kick and ban pages, watermark removal, sign in with Google, cloud storage, and the AI bot Evan with chat answers, picture generation, news headlines, video search and smart moderation.

Word filters

Three filters run on the way messages and sign ups arrive. Profanity replaces matching words with four asterisks in any language, blocked words are removed from chat altogether, and mail refuses sign ups from addresses outside the domains on your list.

Words you add sit alongside the built-in lists, and each filter has its own switch.

API connect

The Embed API page holds the room's embed key, the copy code box with the iframe snippet, and the domain the room runs on, which can be changed there on Premium.

It also states what happens when a frame arrives without the right credentials, and holds the regenerate action described above.

Logs

The logs page holds two records for the room: the system log, and the moderation actions taken in it, with who applied each one and why.

Website address (SaaS)

The Website address on the SaaS settings page is the public address of the install. Embed code, footers and links use it everywhere, so moving domain means changing it there once. Changing it needs the account password and the current two-factor code, and two-factor must be on first.

Support

Support takes questions by email, with a reply within one working day. Room-down reports jump the queue.

Two-factor authentication

A 6 digit code from an authenticator app stands between a stolen password and your control panel. It is switched on from the Edit Info page, in a modal that shows a QR code to scan and the manual entry key underneath it for anyone who prefers to type the key in.

The key works with Google Authenticator, Twilio Authy and Microsoft Authenticator, and enrolment finishes with the 6 digit code those apps show. Once it is on, every sign in asks for a code, and switching it off asks for the current code first. Codes get five tries per five minutes per account, then the door stays shut a while against guessing.

Sessions

With two-factor authentication on, signing in holds a partial session until the code arrives: a full session is not created until the code proves possession of the app.

The chat control panel and the network console keep separate sessions, so signing into one never opens or closes the other. The room itself sets a single cookie to remember who is signed in, over HTTPS, and carries no tracking script.

Embed key

The embed key is the only credential a page needs to open a room it does not own, so it is handled like a password: it is shown in the control panel alone and no visitor ever sees it.

Regenerating it asks for the account password, because every site already using the old key stops working immediately. Rotate it whenever a key reaches a public repository, then paste the new snippet wherever the room is embedded.