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.

We have a free plan, which will always be free, but it does not offer the full complement of features available with Cbox. Our paid plans come with plenty of good reasons to upgrade.

Paid Cboxes support Facebook authentication for user registration. You can enable this option at your Users page.

Facebook authentication makes it easy for users to register their names with your Cbox, because they do not have to enter or remember a separate password for Cbox. They tap the "profile" link and then the "Log in with Facebook" button. If they are already logged in with Facebook and have previously accepted the Cbox app connection, then they will be logged in without any further prompt.

Facebook authentication also makes it easier for you to control access to your Cbox, because bans against Facebook users will apply to their Facebook identity, not just their name or IP on your Cbox.

Cbox does not use its Facebook integration to post to users' feeds; we only ask permission to retrieve the user's name and email address, as well as basic public information that all Facebook apps receive. We may set the user's avatar on your Cbox to their Facebook profile picture by default, but they are free to change this.

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.

Cbox supports private messaging to and from mod and admin users. You can enable PM for your Cbox at your Settings page.

You can also type out the PM command: enter //pm username message..., where username is the name of the person you want to send your message to. This method works if the username conforms to Cbox "strict name" or "ASCII name" policy, i.e. comprises alphanumeric characters only and includes no spaces. Otherwise, you will have to refer to the user by ID.

By default, ordinary users cannot send PMs to other ordinary users. One of the two participants in any private conversation must be a mod or admin.

Opting in and out

Registered users can opt in to sending and receiving private messages from other registered (non-mod) users, by entering //pm on. The command //pm off revokes this availability.

Errors on sending

Private messages can fail to send for a number of reasons. If you get an error, it will likely either be due to the target user not being online (see below) or due to policy regarding who can send and receive private messages (see above). If the target user is not online, you may need to wait just a few seconds before retrying. Refer to the onliners list to confirm whether Cbox recognizes the user as present.

Message delivery

Private messages are sent via the streaming interfaces. The target user must be viewing and connected. Users on old browsers or restricted networks may not be able to receive PMs. When your message has been accepted by our servers for relaying, you will see an indicator (by default, a tick symbol). When the message has been received by the target user, the indicator will change (double-tick symbol). If that doesn't happen, your message probably wasn't received. Note that Cbox does not know that a message has been read, only that it has been delivered.

Persistence

Cbox does not store private messages for future delivery. New messages are relayed only if the user has an active connection. If the user has gone offline or is otherwise unable to receive your message, it will not be sent again, and nor will it be seen by that user when he reconnects. If you do not see the two-tick "received" indicator within a few seconds of sending a message, you will need to re-send your message later.

Yes, you can have as many as you like! Create a separate account for each Cbox. You will need a unique account name for each, but we recommend using the same email address.

If you need a large number of Cboxes, you might want to be on our Cbox Pro plan. Cbox Pro supports channels, which are independent conversation threads. Each channel can be embedded or linked as if it were a separate Cbox, and will host a separate conversation. Channels share the same theme, settings and users, and you only need one control panel login to manage them.