Help & Support

Your Cbox embed code is available at your control panel. You need this code to install your Cbox on your website.

Also on that page is your Quick Link — a URL which you can use to access your Cbox directly in your browser or on your mobile device.

Once you have created your Cbox account, go to the Publish page of your control panel. The code and steps for embedding your Cbox are provided there for a number of common platforms.

If you install your Cbox and all you see is code, or nothing at all, your web host may be removing or otherwise interfering with the HTML iframe tags that Cbox uses. Your Cbox code needs to be pasted into an area of your site that accepts HTML without modification. This may mean switching your editor from "rich text" or "WYSIWYG" mode into HTML-editing or "raw" mode, or you may need to open your template files in a plain-text editor like Notepad.

Remember that you always have the option of posting or sharing your Cbox Quick Link — this gives visitors direct access to your Cbox in a full-screen layout, so it's perfect as a mobile option or for stand-alone use.

Go to the Theme editor in your control panel. There you can specify the fonts and colours of your Cbox, using a point-and-click editor. You can always reset your theme to one of the preset defaults there, if you would like to start again.

If you have a Premium or Pro Cbox you can edit CSS, which gives you complete control over presentation.

If you have a Premium or Pro Cbox, you can create a moderator name for yourself at your Users page, and then log in on your Cbox using the "profile" link. You will see a delete icon [x] next to each message in your Cbox, and you will not have to log in at your control panel at all to delete messages.

Alternatively, visit your Messages page to delete messages individually or in bulk. Deleted messages are removed from your public Cbox history, but are preserved in your Archives.

Yes. In the Theme editor, simply delete the colour codes for the main and form background ("BG") elements. This will make the Cbox transparent, allowing whatever is behind the Cbox to show through.

Note that any pop-ups generated by a transparent Cbox will have the default background colour — usually white. If your font colour is light, it may be invisible in popups. You can fix this by editing the CSS to introduce a background-color rule for popups.

When boxcode is disabled in Posting options, it is only disabled for user messages. You will still be able to use it for your Sticky message and Custom filtering rules.

Cbox supports boxcode, which is a way to add markup to messages. You can also use it to style your Sticky message and Custom filtering replacement text.

The boxcodes supported by Cbox are:

• [color=#ff0000]hex colour[/color] or [color=forestgreen]named colour[/color]
• [color=#f00,#ff0]foreground and background[/color]
• [b]bold text[/b]
• [u]underlined text[/u]
• [i]italicized text[/i]
• [s]struck-out text[/s]
• [q]quoted text[/q]
• [sub]_subscript[/sub]
• [sup]^superscript[/sup]
• [center]centered text[/center]
• [br]
  (line break)
• [big]larger font[/big]
• [small]smaller font[/small]
• [class=custom]custom-styled text[/custom]
• [code]fixed-width text[/code]
• [url=https://address.com/hyperlink]link text[/url] or [url]https://address.com/hyperlink[/url]
• [img=https://address.com/image.jpg]image title[/img] or [img]https://address.com/image.jpg[/img]

Combining boxcode

Besides using boxcode in Custom filtering replacement text, you can also match boxcodes in filter rules. See more.

It's possible to combine boxcode by nesting it, with some caveats:

1. Tags must be nested in the correct order: [b][u]bold underline[/u][/b] is valid but [b][u]broken[/b][/u] is not.
2. The same tag cannot be nested. For example, [class=one][class=two]some text[/class][/class] will not work. To get the intended behaviour in this case, you could have a combined class instead: [class=onetwo]some text[/class].
3. The no-attribute form of [url] (e.g. without link text), and both forms of the [img] tag, must be the innermost element in any nested sequence.

Styling boxcode

Boxcode is translated internally to HTML. You can thus affect the presentation of boxcode by editing your CSS. For example, to change the presentation of the [s] tag:

s {
	text-decoration: none; /* reset default */
	opacity: 0.2;
}

[class] parameters must start with a letter, and are limited to 20 alphanumeric characters. [class=blink] is valid but [class=2] is not.

The [class] boxcode is intended for open-ended styling. It produces a span with no default CSS. You can create a corresponding class using a cc_ prefix. For example, for blurred text, copy this to your CSS:

.cc_blur {
	text-shadow: #000 0 0 0.5em;
	color: transparent;
}

Now users can blur the text in their messages: [class=blur]this will be blurred![/class].

Find out more about custom CSS.

In the Date options in your control panel, there is a "Zone" setting. Click the [reset] link to have Cbox attempt to figure out the correct time zone based on your current clock time. If it's still not correct according to the example shown on that page, add or subtract 1 from the Zone number until the example time shown is correct. Your time zone may be negative or positive.

You can also change the "Date display" option to show relative timestamps — this way the clock time is not shown on your Cbox at all, but rather a relative time, such as "2 minutes ago".

If you are a Cbox administrator or owner then you can delete users' data via the control panel. In particular, you can delete messages permanently at here and remove registered user names here.

If you are a Cbox user then you can request the owner or administrator of the Cbox that you have participated in to remove your data.

You can also request a manual data deletion by contacting us, including a reference to your account. We may require that you provide additional information to authenticate you as the account owner.

A Moderated Cbox requires that messages be manually approved before they are published.

Normally, all users can post to your public Cbox, and everyone can see their messages. If you enable Moderated chat, then only voiced users can post directly. Unvoiced users' messages are redirected to a special channel where moderators can view and approve them.

This setting enables proactive moderation. It's important if you are concerned about your platform's brand but still want your Cbox to be publicly-accessible. It's also useful if you host live chats where you may want to control the volume and relevance of published messages by accepting only the ones you want, and at the appropriate time.

Using Moderated chat

For testing, it's helpful to open another instance of your Cbox in an incognito/private tab. This allows you to log in as a guest in one tab and as a Mod in the other.

When you enable this setting, a shadow channel is created. Regular users cannot access it, but a Mod or Admin user on the public Cbox will see a "mod channel" link or "thumbs up" button. Clicking this button opens the shadow channel, and shows any messages that are awaiting approval. These messages can be published (i.e. re-posted) to the public Cbox by clicking the [a]/"tick" button in the mod tools next to each message.

Voice permission

Note that when users register they do not automatically get voice. So, if you have existing registered users, before you enable Moderated chat, you might first want to voice them.

Mods and admins always have voice. This means they can always post directly to your public Cbox. Registered users (other than mods and admins) can be voiced and unvoiced from within your Cbox by clicking the [v]/"plus" button in the mod tools next to their messages. Unregistered guest users cannot be granted this permission, however.

Voice permission grants a user direct publication access to your Cbox, without any of the special permissions of mods or admins. It is useful in cases where the user is trusted and/or conversation established.

Moderated channels

Moderation works in conjunction with channels, too. The global setting controls whether new channels are created in Moderated mode or not. The per-channel setting is maintained even if the global setting is later changed.

Getting started

This feature requires some familiarity with hosting your own scripts on the Web. Our code examples are in PHP, but you can use any platform and programming language you like, providing you can access HTTP POST data.

The Cbox webhook is an HTTP POST callback mechanism for getting a copy of new messages as they are posted to your Cbox. A couple of lines of PHP are sufficient to get started:

<?php
$input = @file_get_contents("php://input");
$json = json_decode($input);

// $json contains array of messages

error_log(print_r($json, true), 1, "your-email@example.com");

echo "OK";
?>

With the above code uploaded to your server, test that it works by opening the corresponding URL, e.g. https://yoursite.example.com/cbox.php, and confirming that you see "OK". You can then enter it as your callback URL in your Cbox settings.

When a user posts a message, Cbox will issue an HTTP POST request to your callback URL, with Content-Type application/json. The request body will look something like this:

[{"type":"message","box":802140,"channel":0,"time":1488526982,"uid":0,"name":"test","text":"this is a test","link":"","ip":"0.0.0.0"}]

The object is an array of messages. There can be multiple messages in a single POST. Your code can do whatever you like with the messages; it just needs to return an HTTP OK status to Cbox. Any response body is ignored.

Message contents

The message webhook is located after the message-accepted stage and before filtering. This means your endpoint will only receive messages that are being published on your Cbox (i.e. not messages from banned users). They will be "raw", having none of the built-in or custom filters applied (i.e. no boxcode expansion). Important to note is that messages can contain any UTF-8 character, and so should be escaped as appropriate before storage or display.

Message properties:

• type — always set to "message"
• box — your Cbox ID.
• channel — The channel ID to which the message was posted.
• id — The message ID.
• time — Unix times when the message was received.
• uid — Registered user ID. Guest IDs are undefined or zero.
• name — The user's name, as entered.
• text — The text of the message, as entered.
• link — Link associated with the message; the profile URL.
• ip — IP address of the user.

Errors and retry

Your endpoint needs to return an HTTP success header (status codes in the 2XX range) in response to the POST. If it returns any other status, or times out, Cbox will consider the delivery to have failed. On failure, Cbox will buffer messages for retry. Cbox will retry the POST at increasingly long intervals, even in the absence of further new messages.

Cbox buffers are not unlimited; if your endpoint is down for an extended time, the oldest messages may be dropped.

Notes

• Cbox ignores the body sent in response to the POST, and does not wait for it to complete.
• Return a 200 OK to Cbox as quickly as possible. Otherwise, there is a risk of a timeout, which will cause the same message(s) to be re-sent. If your message processing is slow, move it "offline", either by completing and flushing the HTTP response early and continuing to work, or by offloading incoming messages to another service.
• For forwards-compatibility, confirm that type == 'message' in your code; new event types may be supported in future.
• The box and channel properties mean you can multiplex several Cboxes to a single endpoint, and filter or switch based on channel.
• Message ID is a monotonically increasing number. Larger IDs are always newer messages.
• Although some properties are 32-bit integers, it's recommended that you treat all values as UTF-8 strings for storage or further processing.
• The POST request includes a custom HTTP header, X-Cbox-Time which contains the Unix timestamp at the moment the POST was sent. You can use this to calculate differential message times.