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.

Copyright & License

Copyright (c) 2020 The Matrix.org Foundation C.I.C.

Copyright (c) 2025 New Vector Ltd

This software is multi licensed by New Vector Ltd (Element). It can be used either:

(1) for free under the terms of the GNU Affero General Public License (as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version); OR

(2) under the terms of a paid-for Element Commercial License agreement between you and Element (the terms of which may vary depending on what you and Element have agreed to). Unless required by applicable law or agreed to in writing, software distributed under the Licenses is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licenses for the specific language governing permissions and limitations under the Licenses.