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 toJoinRoom
to have your Chatterbox instance join a specific room on startup. Set this toInvite
mode if each client session of cahtterbox should have its own room.- If using
JoinRoom
: Defineauto_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
: Definebot_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.
- If using
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.