Chatterbox lets you securely embed Hydrogen on any website!
  • TypeScript 77.4%
  • CSS 13.9%
  • HTML 4.7%
  • JavaScript 2.7%
  • Shell 0.7%
  • Other 0.6%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
R Midhun Suresh df49983d24
Merge pull request #108 from element-hq/langleyd/add_agpl_and_commercial_license
Change license: Add AGPL and commercial license
2025-01-28 12:00:22 +05:30
.github/workflows master/main 2022-04-25 14:14:12 +01:00
cypress Update source headers 2025-01-22 16:18:29 +00:00
public The option should default to false 2022-07-27 11:46:25 +05:30
scripts Create release script 2022-02-18 19:03:50 +05:30
src Update source headers 2025-01-22 16:18:29 +00:00
.dockerignore Add .idea to .dockerignore 2022-03-08 10:18:18 +02:00
.editorconfig Add editorconfig from Hydrogen 2021-12-31 13:30:05 +05:30
.gitignore Add Dockerfile 2022-03-04 15:55:49 +02:00
chatterbox.html Move styles into separate directory 2022-02-17 17:43:57 +05:30
cypress.config.ts Update cypress.config.ts 2022-07-05 11:52:07 +01:00
default-nginx.conf Add a nginx config file which includes the required cors headers 2022-04-21 16:09:34 +01:00
Dockerfile Add a nginx config file which includes the required cors headers 2022-04-21 16:09:34 +01:00
favicon.svg Create blank vite project 2021-12-27 15:01:52 +05:30
index.html Move parent files into /parent directory 2022-04-26 22:19:25 +05:30
LICENSE-AGPL-3.0 Add AGPL and commercial license 2025-01-22 16:15:00 +00:00
LICENSE-COMMERCIAL Add AGPL and commercial license 2025-01-22 16:15:00 +00:00
package.json Add AGPL and commercial license 2025-01-22 16:15:00 +00:00
parent-vite.config.js Add explaining comments 2022-04-26 22:19:25 +05:30
README.md Add AGPL and commercial license 2025-01-22 16:15:00 +00:00
tsconfig.json UI WIP 2022-01-04 22:56:32 +05:30
vite.config.js Rename defined constant 2022-02-08 16:04:23 +05:30
yarn.lock Upgrade SDK 2022-10-17 18:52:29 +05:30

Chatterbox

Chatterbox lets you securely embed Hydrogen within any website.

Chatterbox client screenshot

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 (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.