- TypeScript 77.4%
- CSS 13.9%
- HTML 4.7%
- JavaScript 2.7%
- Shell 0.7%
- Other 0.6%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .github/workflows | ||
| cypress | ||
| public | ||
| scripts | ||
| src | ||
| .dockerignore | ||
| .editorconfig | ||
| .gitignore | ||
| chatterbox.html | ||
| cypress.config.ts | ||
| default-nginx.conf | ||
| Dockerfile | ||
| favicon.svg | ||
| index.html | ||
| LICENSE-AGPL-3.0 | ||
| LICENSE-COMMERCIAL | ||
| package.json | ||
| parent-vite.config.js | ||
| README.md | ||
| tsconfig.json | ||
| vite.config.js | ||
| yarn.lock | ||
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
- Clone the repo.
- Install dependencies (you only need to do this once):
yarn install - Modify config.json in
publicdirectory with your homeserver details.
(Seetypes/IChatterboxConfig.tsfor the format) - Start develop server:
yarn start
Build Instructions
Follow the develop instructions above (steps 1-3), then:
- Build chatterbox app into
/targetdirectory: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.