Embed a room on your site

Quickstart

Load the script on your page, set the src of an iframe to an embed URL, then call Divcord.connect. Wait for bridge.ready before sending commands.

<script src="https://divcord.gg/embed.js"></script>
<iframe id="chat" src="https://my-server.divcord.gg/embed/general"></iframe>
<script>
  const bridge = Divcord.connect(document.getElementById('chat'));

  bridge.ready.then(function () {
    return bridge.setTheme('aurora');
  }).then(function () {
    bridge.on('new_message', function (msg) {
      console.log(msg);
    });
    return bridge.getState();
  }).then(function (state) {
    console.log(state.user, state.room, state.online);
  });
</script>

Embed URLs

Embed URLs can be obtained for each room you own on the dashboard. Open the dashboard, navigate to the rooms tab, select the actions button on the room you want to embed, and click "Embed".

Divcord.connect(iframe, options)

Creates a bridge to one iframe.

const bridge = Divcord.connect(iframe, {
  origin: 'https://my-server.divcord.gg'
});

Lifecycle

Theme and CSS

You can apply custom CSS rules inside the iframe and override the room's default stylesheet, or pick from an existing Divcord theme.

bridge.setTheme(name, opts)

Loads a Divcord theme into the iframe. Default opts.reset is true, which completely disables the embed's default stylesheets first (except widgets, icons, fonts, code syntax highlighting, the user-list menu sheet, and other niche features).

Divcord themes match the names from the settings menu, default, aurora, business, frutiger-aero, irc, lightcast, etc.

bridge.setTheme('aurora');

bridge.setCSS(css, opts)

Inject raw CSS. Pass { reset: true } to disable most of the embed's default stylesheets.

bridge.setCSS(`
  body { background: #0f172a !important; }
  #embed-bar { background: #1e293b !important; }
`, { reset: true });

bridge.setCSSFromURL(url, opts)

Fetches CSS on the source url. The stylesheet must be CORS-readable from the source domain. Same reset option as setCSS.

bridge.clearCSS()

Removes any styles added by you and re-enables stylesheets that were disabled by reset if any.

Flair

Writes a CSS class flair onto the signed-in embed account. The flair text is applied as a class on the username in the online list, messages, and profile cards. The flair text is trimmed to 24 characters of [A-Za-z0-9_-]. Spaces become hyphens. Some flair names are reserved such as mod, moderator, owner, admin.

bridge.setFlair('subscriber');
bridge.clearFlair();
bridge.setFlair(''); // also clears current flair

Safe to call right after bridge.ready. If the embed user is not signed in yet or the socket is still connecting, the flair is queued and applied after login.

JSON payloads

Send a JSON value from your page to every client in that room. Payloads are not stored anywhere on the database and do not execute any code natively.

bridge.sendPayload({ type: 'score', value: 12, player: 'alice' });
bridge.sendPayload({ ready: true });

bridge.on('payload', function (packet) {
  if (packet.data && packet.data.type === 'score') {
    console.log(packet.data.value, packet.from.username);
  }
});

bridge.off('payload', handler);

Inbound packet shape: { roomId, data, from, timestamp }. from is the public user object of the sender. The sender also receives their own payload.

Events

bridge.on and bridge.off are the listener API. Use them for payloads, chat lines, edits, deletes, and the online list.

function onChat(msg) {
  console.log(msg.username, msg.content);
}

bridge.on('new_message', onChat);
bridge.on('message_edited', function (msg) {});
bridge.on('message_deleted', function (data) {});
bridge.on('users', function (data) {
  console.log(data.users, data.roomId);
});
bridge.on('payload', function (packet) {
  console.log(packet.data);
});

bridge.off('new_message', onChat);
bridge.once('ready', function () {});
bridge.on(['new_message', 'message_edited'], onChat);
bridge.on('*', function (name, payload) {
  console.log('event', name, payload);
});

Common listener names

users fires on user_joined, user_left, user_updated, and room_presence. The payload still has users and usually roomId. Do not use on('message') for chat lines.

Bridge protocol events

Chat events arrive as type event and are also re-emitted under the inner name. bridge.on('new_message', fn) is the usual listener.

Forwarded chat events

If you connect after the room is already signed in, you still get connect, authenticated, and joined_room so you do not miss the current state.

Snapshots and lookups

These ask the iframe for current state. They return a Promise. Application failures use { ok: false, error } instead of throwing, except where noted.

bridge.getOnlineList().then(function (online) {
  // { ok, roomId, count, users }
});

bridge.getUser().then(function (me) {
  // { ok, authenticated, user }
});

bridge.getRoom().then(function (room) {
  // { ok, room: { id, name, createdBy, private, locked, moderators, notifications, userCount, users } }
});

bridge.getServer({ rooms: true }).then(function (server) {
  // { ok, server: { name, origin, href, path, connected }, rooms }
});

bridge.getState({ rooms: true }).then(function (state) {
  // { ok, user, authenticated, online, onlineCount, room, server, rooms }
});

bridge.getProfile('alice').then(function (profile) {});
bridge.getInfo().then(function (info) {});

Public user objects typically include username, isAnonymous, avatarUrl, flair, createdAt, timezone (omitted when the user opts to hide it), showTimezone, bio, and link.

Errors and timing

• Ack methods time out after 8 seconds and reject with timeout waiting for <type>.
• Types ending in :error reject with payload.message.
• Snapshot getters resolve { ok: false, error: 'Chat UI not ready' } if the room has not finished loading.
• getProfile fails the same way if the room is not ready. A failed lookup comes back as { ok: false, error }.
• setCSSFromURL rejects if the CSS fetch is not OK (status text included).
• destroy() rejects every in-flight call with destroyed.
• Payloads are JSON-cloned before they leave the iframe. Errors become { message }.