Skip to main content

Setting Up Chatterbox

What is Chatterbox?

Chatterbox allows for the embedding of a light-weight matrix-based chat client into any standard website. Chatterbox can be configured in two main modes:

  • Invite mode: A user interacting with a "chatterbox" is assigned a guest account and placed into a room on a homeserver. In this mode, one specifies a list of agents who should be monitoring these chats and these users are notified of the new guest account and invited into the same room. In this manner, customers can have agents staffing chat requests through Chatterbox.
  • Join room mode: In this mode, "chatterbox" joins an existing room on a homeserver and anyone visiting the webpage with this "chatterbox" can see the chat in the room and interact with the room. This is good for chat that runs alongside a video presentation for instance.

How to set up Chatterbox

Copy config-sample/chatterbox/chatterbox.yml.sample into a file called chatterbox/chatterbox.yml in your configuration directory.

Create a certificate for the fqdn of chatterbox (chatterbox.example) and add that PEM based .crt/.key pair to your certs/ directory.

Edit the values of chatterbox/chatterbox.yml and set the following:

  • username_prefix: This defaults to chatters, but you can change this.
  • chatterbox_fqdn: Set the fqdn for the chatterbox service.
  • operating_mode: Set this to JoinRoom to have your Chatterbox instance join a specific room on startup. Set this to Invite mode if each client session of cahtterbox should have its own room.
    • If using JoinRoom : Define auto_join_room: The room the operator bot should join automatically. Use the ID of the room. To get it, on element, open room settings on the right panel, Advanced. You must provide the ID of the room and not the published address. Room IDs will look similar to: !bYSJwxpJxShZVjoSoF:local
    • If using Invite : Define bot_operator_username: The name of the bot inviting responders
    • header_title: The name of Chatterbox widget
    • header_avatar: The icon of the Chatterbox widget
    • encrypt_room: true to enable Chatterbox rooms encryption. Else, false.
    • bot_data_size: The size of the bot directory.
    • bot_data_path: The bot data path on the local machine, if deploying on microk8s.
    • max_users: The maximum number of chatterbox users.
    • responders: The list of the users which should respond to new chatterbox chats. Use the matrix address of each user.
    • should_avoid_offline_responders: true to avoid inviting absent users. Else, false.
    • responder_group_router: all invites all the responsders. roundrobin uses a round robin algorithm to fairly distribute invites. random chooses a random user from the list.

Deploying Chatterbox to Your Website

On the website that you'd like chatterbox set up on, add the following code:

    <script>
        window.CHATTERBOX_CONFIG_LOCATION = "https://<chatterbox_fqdn>/chatterbox-webconfig/config.json";
    </script>
    <script src="https://<chatterbox_fqdn>/assets/parent.js" type="module" id="chatterbox-script"></script>
    </body>

replacing <chatterbox_fqdn> with the value specified in the config file.

Back to top