Running Tiledesk from Source Code

Applicable to Tiledesk version 2.

Actually we support Tiledesk installation under MacOS and Linux. Windows OS is not supported.

Tiledesk uses Chat21 as messaging platform. Refer to Architecture overview to undestand the product's modules.

Chat21 relies on Firebase as the backend, so it's really important for you to acquire familiarity with Firebase and all of his services.

Please help us improving this documentation: if you encounter a problem, something you don’t understand or a typo, use this link to ask a question. You could also open a PR to directly fix the documentation on Github, if you want.

Tiledesk is composed by the following components:

  • tiledesk-server

  • tiledesk-dashboard

  • chat21-cloud-functions

  • chat21-web-widget

  • chat21-ionic

Installation tips

  • Enable https to front-end and backend endpoints. Https is required for receiving web push notifications;

  • Create a DNS entries for:

    • tiledesk-server. Create a DNS entry like this: api.YOURDOMAIN.COM. Then configure a virtualhost for it.

    • chat21-web-widget. Create a DNS entry like widget.YOURDOMAIN.COM. The widget must be on a different domain to avoid authentication conflicts with the dashboard. Dashboard component and widget test page should never share the same user.

    • tiledesk-dashboard and chat21-ionic (the desktop chat) are suggested to be under the same domain to share authentications tokens. Create a DNS entry like support.YOURDOMAIN.COM. You must be able to access:

      • /dashboard -> Tiledesk dashboard component

      • /chat -> Chat21 ionic component

    • Install the latest stable release versions of the components. Check the last release under Releases tab of every Github components pages.


Please follow this guide in order to install all the Tiledesk components.

1. Create and configure a Firebase project

Chat21 relies on Firebase as the backend, so it's really important for you to acquire familiarity with Firebase and all of his services.

Sign up on Firebase and create a project. Please refer to our guide or directly to Firebase to accomplish and better understand this task.

2. Install chat21-cloud-functions

To install and configure chat21-cloud-functions follow this README:

3. Install and configure tiledesk-server

To install tiledesk-server version 2 please follow this guide:

You must set the following properties under .env file:

  • FIREBASE_PRIVATE_KEY. Get it here. More info about firebase private key here.


  • FIREBASE_PROJECT_ID. Get it here.

  • FIREBASE_APIKEY. Get it here.




  • FIREBASE_MESSAGINGSENDERID. Get it here. A unique numerical value created when you create your Firebase project, available in the Cloud Messaging tab of the Firebase console Settings pane.

  • CHAT21_ENABLED. Enable Chat21 channel with true value.

  • CHAT21_URL. Get it here.

  • CHAT21_APPID. Enter the value tilechat

  • CHAT21_ADMIN_TOKEN. The Chat21 admin token. The default value is chat21-secret-orgAa,. See here to change it.

4. Configure the webhook module of chat21-cloud-functions

Chat21 communicates with Tiledesk through webhooks. When a Chat21 event occurs - a new message arrives, a new member join a group, etc - a new Event is created and notified to Tiledesk Server. Chat21 then makes an HTTP POST request to send the Event to the Tiledesk webhook endpoint.

Chat21 needs a public Tiledesk server endpoint to work properly.

Firebase requires an active billing project to perform external call. It is necessary to do external HTTP requests and since Tiledesk Server lives outside Google’s servers we need to switch to the Blaze plan, which is surprisingly cheap.

Enable the webhook with :

$ firebase functions:config:set webhook.enabled=true

Configure the webhook endpoint with:

$ firebase functions:config:set webhook.url=<PUBLIC_TILEDESK_URL_EXPOSED_BY_NGROK>/chat21/requests

Example: firebase functions:config:set webhook.url=https://

You can find other info on this guide:

5. Install and configure tiledesk-dashboard

Follow this guide to install and configure Tiledesk-Dasboard:

6. Install and configure chat21-web-widget

Follow this guide to install and configure the Web Widget:

7. Install and configure chat21-ionic with push notification

Follow this guide to install chat21-ionic from source code:

Follow this guide to configure push notification for chat21-cloud-functions:

Configure Chat21-ionic following this guide: