Chatterbox

Chatterbox lets you securely embed Hydrogen within any website.

Requirements

To use Chatterbox you will need:

• A homeserver which supports Token-authenticated registration. Currently the only known implementation is Synapse (which is available as a service from element.io).
• An account on that homeserver which can create registration tokens. Synapse requires the account to be an admin.

Develop Instructions

1. Clone the repo.
2. Install dependencies (you only need to do this once):

   yarn install

3. Modify config.json in public directory with your homeserver details.
   (See types/IChatterboxConfig.ts for the format)
4. Start develop server:

   yarn start

Build Instructions

Follow the develop instructions above (steps 1-3), then:

• Build chatterbox app into /target directory:

  yarn build

Embed Instructions

Assuming that the build output (inside /target) is hosted at <root> (eg: chatterbox.element.io), copy and paste the following snippet before the closing </body> tag:

	<script>
		window.CHATTERBOX_CONFIG_LOCATION = "path_to_config";
	</script>
	<script src="<root>/assets/parent.js" type="module" id="chatterbox-script"></script>

Testing

Chatterbox comes with a suite of integration tests, using cypress.

You can run them by doing

yarn cypress install
yarn cypress open

Ensure you copy the cypress/fixtures/demoInstance.sample.json file to cypress/fixtures/demoInstance.json and edit the keys accordingly.

Homeserver requirements & configuration

Chatterbox makes use of the Token-authenticated registration feature, and as such your homeserver implementation will need to support it.

Synapse

Synapse has supported this feature since at least 1.52.0. You can enable token registration in homeserver config with:

registration_requires_token: true

You will also need to manually create a registration token with the create token API. You must use the access token of an administrator for this. See the Synapse documentation for help.

$ curl --data '{ "uses_allowed": 50 }' -H 'Authorization: Bearer YOUR_ADMIN_TOKEN' 'https://your-homeserver/_synapse/admin/v1/registration_tokens/new'
200 OK
{
    "token": "defg",
    "uses_allowed": 50,
    "pending": 0,
    "completed": 0,
    "expiry_time": null
}

Note that you can use uses_allowed to set how many chatterbox users can register via this token before no more will be permitted. You can then use the value of token in the response inside your config.json.