search

osousa / livematrix

Livechat integration for your website, using matrix.
GNU General Public License v3.0
66 stars 5 forks source link

readme

livematrix

Chat with your website's visitors, using your Matrix client of choice.

If you need help, you can ask here: #livematrix:matrix.org

📌 What is livematrix?

An oversimplified, easy to implement, embedded live chat widget that allows your website's visitors to send you messages seamlessly to your Matrix account.

:bust_in_silhouette: Why livematrix?

livematrix is intended for personal use, very lightweight, stripped down and easy to embed (Nothing to install or compile). You have a personal blog/website and really enjoy using Matrix? Well, give it a try :)

:heavy_check_mark: Todo

If you wish to clone this repo, remember to sync submodules after cloning it with : 

git submodule update --init

A quick note about encrytion being implemented: If you host the server on a VPS of your own, and use TLS on your website, it should enable for a fairly robust private conversation with your visitors:

[Browser] <---TLS---> [livematrix] <---e2ee---> [Matrix homeserver]

📺 Working demo

Visitor's first interaction, creates session:

(Wait for the GIF to load...)

demo_1

Chatting with visitor, through Element client:

(Wait for the GIF to load...)

demo_2

🛠️ How does it work?

There would be many ways of doing a live chat, for example, we could create a Matrix account for each visitor using an SDK that allows this on the browser. You could also use your own homeserver and allow guests . Why your own? Because most homeservers disallow guests.

The next best bet, and subjectively less cumbersome, is for you to create a new Matrix account and all visitor's chats will be mediated by it. Each new conversation is a new room. When a visitor starts a chat he/she needs to introduce their name, surname and email. If Melissa Brandon starts a chat, you'll receive an invitation on your personal account to join a room of the name #Melissa_Brandon4212353:Matrix.org

📗 How to use

:computer: client

Built using Svelte, so everything goes in one nice bundle, its fast and awesome to embed. No need for external libraries or big framework.js files. Just import into your website's structure one JS and one CSS files.

To embed the widget is very straightforward, copy the following and paste on your index.html (or other):

    <script type="module" crossorigin src="https://github.com/osousa/livematrix/raw/main/static/js/index-e73fa2f7.js"></script>
    <link rel="stylesheet" href="https://github.com/osousa/livematrix/blob/main/static/css/index-de5f8656.css">
    <div id="app" class="tw-fixed"></div>

Configure paths on client-side

On the repo's folder _client (Not the submodule), download the files, and put them inside folders relative to your index.html, like this:

root/ .
      |_ index.html
      |_ static/
         |_ config.json 
         |_ images/
         |   |_ bubbleicon.svg
         |_ js/
         |   |_ index-xxxxxxx.js
         |_ css/
             |_ index-xxxxxxx.css

Edit the config.json to set your server's addresses and ports;

❔

If you can't use this directories' sctructure, change the corresponding paths on the Svelte's App and compile it again; Follow the submodule named client@xxxx

🛰️ Server

On the repo's folder _server (Not the submodule), download the binary "livematrix" (Only 2.1MB, small for Go standards) and the .env file; Edit the .env file and add your personal details. You can download the same binary and .env file from here on Releases if you don't wish to clone this repo.

You must create a Matrix user specifically to mediate conversations with your visitors. The .env looks like this:

# MySQL/MariaDB credentials
DATABASE_NAME=livematrix
DATABASE_USER=username
DATABASE_PASSWORD=password
DATABASE_IPADDR="127.0.0.1"
DATABASE_PORT="3306"

# Your personal Matrix.org account
MATRIX_RECIPIENT=@username:matrix.org

# Account used ONLY for mediation
MATRIX_SERVER=matrix.privex.io
MATRIX_USERNAME=@ousername:privex.io
MATRIX_PASSWORD=password

# Time to wait until next login (in days)
# Defautl: Access Token is kept for 7 days
MATRIX_TIMEOUT=7

# Leave empty if you want it to bind
# to every available interfaces. 
SERVER_IFACE="127.0.0.1"
SERVER_PORT=8000
- DO NOT use your personal account's password and username. CREATE one for this purpose only

🔥 Just fire up the server and you're done. Your live chat is working:

$ chmod 755 livematrix
$ ./livematrix &

or if you wish to suppress logs from terminal:

$ chmod 755 livematrix
$ ./livematrix 2>/dev/null &

❔

If you do not want to use the compiled binary "livematrix" you can compile your own. Follow the submodule named server@xxxx

⚙️

If you're having difficulties configuring the livematrix on your side, remember that you probably need a nginx proxy that upstreams requests to livematrix Here is a working example that uses letsencrypt and docker containers to launch a website and livematrix separately, and nginx deals with traffic routing: https://github.com/osousa/livematrix/issues/3#issuecomment-1910005841

:bulb: Disclaimer