Message your website's visitors through Slack for support or sales. 100% free and open source.
Yalcs displays a configurable floating action button over your page that when activated opens a chat window connecting your visitors with an agent responding from your specified Slack channel.
- Communicate with visitors who are on your site or app through your Slack workspace
- Configurable routes to display and hide Yalcs on certain pages
- Configurable theme to match your app's design
- Configurable text for titles, buttons, etc
- Works well on desktop and mobile devices
- Standalone server and web client that integrates into applications of any stack
- No dependencies other than Node and what npm will install
As simple as Yalcs is, because it's entirely self-hosted, you'll still need to download, configure, build, and integrate it into your app. We've made it just about as easy as it could possibly be.
Note #1: If your system does not yet have Node installed, start with nvm (or nvm for Windows).
Note #2: You may alternatively download Yalcs through npm (see here), however this is not currently the recommended installation method. In the future we may offer a CLI tool available through npm to make configuring, running, and managing Yalcs instances easier.
Note #3: You could alternatively use Yalcs through Docker. But Yalcs in development does not seem working well. Full tests have not be done.
git clone https://github.com/xyfir/yalcs.git
cd yalcs
From now on we'll assume commands are run from yalcs/
.
Build image docker through docker-compose.yml:
docker-compose build yalcs
or with docker engine, start building image for development environment:
docker build --target builder -t yalcs:dev .
Using docker-compose is a better solution because it creates docker volumes to store npm dependencies and gets them during image building.
Due to volume store, dependencies will not be fetched for each new container.
Install npm depencies for each module:
cd loader
npm install
cd ../server
npm install
cd ../web
npm install
cd ../ # back to yalcs/
- Go to the Create a Slack App form on the Slack API dashboard.
- Login to the Slack workspace you wish to add Yalcs to.
- Set the app name to Yalcs or whatever you like and select your workspace.
- Once viewing your new Slack app, go to Bot Users and click Add a bot user. To add a bot user, follow these instructions :
- Go to "OAuth & Permissions" โ "Bot Token Scopes", add the following scopes :
- incoming-webhook
- channels:history
- groups:history
- groups:read
- groups:write
- chat:write
- im:write
- Go to "App home" : give a name to bot (Yalcs or whatever) and verify if "Message Tab" is on in "Show Tabs" section.
- Go to OAuth & Permissions.
- Click Install App and Authorize its installation to your workspace.
- Save your Bot User OAuth Access Token somewhere for later use.
- Go to Basic Information.
- Under App Credentials, save your Signing Secret somewhere for later use.
- In a new tab, navigate to your workspace:
your-workspace.slack.com
. - Navigate to the channel or private group you wish to add Yalcs to.
- Save the channel's id from the url somewhere for later use. (For example, in
https://your-workspace.slack.com/messages/GHG8G3WH2/
, the id isGHG8G3WH2
) - Invite the Yalcs bot to your channel.
Keep the Slack API dashboard open, we'll return to it again later.
The Yalcs modules are configured via environment variables which are loaded into the applications via .env
files located in each module's directory.
To understand the syntax of the .env
files, know that they are first loaded via dotenv and then the string values provided by dotenv are parsed by enve.
First we'll create each file by copying the example .env
files and then we'll work our way through populating them with values.
cp loader/example.env loader/.env
cp server/example.env server/.env
cp web/example.env web/.env
Note: A French example .env
file is also available for yalcs/web:
cp web/example-french.env web/.env
Edit the files loader/.env
, server/.env
, and web/.env
. Update the config keys with your own values. You can find descriptions for each one under the Yalcs
-> Env
namespaces in the type definitions. Use the appropriate interface
for each corresponding file.
BE CAREFUL: In a docker context, you have to remove yalcs
from the url in .env
files. For example, in server/.env
:
YALCS_WEB_URL="https://example.com/yalcs"
becomes
YALCS_WEB_URL="https://example.com"
Only new env variables are described.
- APP_CONTEXT (boolean
true|false
) is not mandatory : if true, it says to Yalcs to ask context to loader. When loader gets messagesget_context
, it sends to web part of Yalcs theyalcs_context
javascript variable. This context permits to set an explicit title in Slack.
Only new env variables are described.
-
APP_CONTEXT (boolean
true|false
) is not mandatory : same as above but now server set title in Slack from context received by web part of Yalcs. -
TRUST_PROXY (boolean
true|false
) is not mandatory : if true, server get ip from X-FORWARDER-FOR header of request (request.ips). It's useful when Yalcs is behind a proxy (Nginx, ngrok) to get real IP of message sender. -
NO_GEOIP (boolean
true|false
) is not mandatory : it disable fetching localisation of IP and does not set IP in title of Slack.
If APP_CONTEXT is not to true or undefined, IP is set to title of Slack event if NO_GEOIP is true.
- Building image builds app from sources.
- Starting a new container from docker-compose builds app from sources also.
docker-compose start yalcs
or with docker engine, start building image for development environment:
docker run -n yalcs_dev -v [mount env files] -v [mount node_modules] -v [mount sources] yalcs:dev
cd loader
npm run build
cd ../server
npm run build
cd ../web
npm run build
cd ../
The server is started with Docker container.
Now you'll need to start the server and serve the built files. The simplest way to do this is:
cd server
npm run start
cd ../
If you're in production, you'll probably run the server with pm2 and proxy the server through Nginx or Apache while serving static files through them instead of Node. For you, know that files to be served to the client are located in web/dist
with web/dist/index.html
serving as the web client's entry file.
Let's return to the Slack API dashboard again.
- Go to Event Subscriptions and toggle Enable Events.
- For the Request URL field, input the full URL to your instance of Yalcs server (the API), and then append to that URL
/slack
. It will should look something like this:https://example.com/yalcs/api/slack
orhttps://example.com/api/slack
in a docker context. It should verify. - Under Subscribe to Bot Events, add
message.channels
if you're adding Yalcs to a public channel ormessage.groups
if you're adding Yalcs to a private channel/group.
Now all that's left is to add the Yalcs loader to one of your page's HTML:
<script src="/yalcs/static/yalcs-loader.js" async></script>
or in a docker context :
<script src="/static/yalcs-loader.js" async></script>
Note that the source is fully dependent on where your app is serving the Yalcs web client files from and the URL of the page(s) where you're importing the loader. It should generally be a URL that combines YALCS_WEB_URL
with STATIC_PATH
and "yalcs-loader.js"
.
If you'd like to help work on Yalcs, the tutorial above will suffice to get you up and running. Certain things however will make your life easier:
- Make sure your
NODE_ENV
variables in the.env
files are set to"development"
. - Run the web client's dev server via
npm run start
when inweb/
. Connect to it via thePORT
you set inweb/.env
. - Use ngrok so that Slack can contact your local machine:
ngrok http 2040
where2040
is the API server's port. - Use
http://localhost:2041/loader.html
to properly test the web app and loader. This assumes you're running the web client's dev server on port2041
. - Check the
scripts
in each module'spackage.json
for helpful scripts.
- Full tests in development environment with Docker containers
- Write in this README how to update dependencies and rebuild within docker container