Hello World tutorial

Connect your own chatbots to Tiledesk

Hello World tutorial for external chatbots integration

Tiledesk is designed to allow external chatbots to easy communicate with your Agents or End users. Once a chatbot receive an authentication token from Tiledesk he can easily call many APIs to modify the state of a Request (the support conversation) changing Departments, inviting Agents, sending scheduled messages, use the chatbot microlanguage to simplify interaction with buttons, images, messages' timing etc.

This tutorial will show how to create a very basic chatbot integration, allowing you to reply to specific messages sent by the End user.

Signup a user on Tiledesk

To use Tiledesk APIs or integrate your own chatbots is mandatory to signup a new user on our beta environment. It's available on the following link https://console.tiledesk.com/v2/dashboard

After signup please follow the proposed wizard to create your first Tiledesk project (you can jump the last step, relative to the widget installation).

As soon as you create the project you will be redirected to the project home.

To integrate an external bot, we'll need a web endpoint where all the chatbot's requests will be forwarded. We'll use the well-known Repl.it service to fast create our own web endpoint.

Create and configure external chatbot endpoint

Go on the repl.it and press "+ new repl" button. Then select Node.js as the programming environment and choose a unique name of you repl propject. We used tiledeskbot.

Presse "Create Repl". Your initial source code will be generated, a empty idex.js file, like the following:


We'll use NodeJS for this example, due to his simplicity, low cost hosting and low learning curve. But keep in mind that the concepts in this tutorial can be easily applied to every web framework of your choice.

Now press the "examples" link in index.js file, then select the "Server (Express)" option, as in the following figure:


Now we can add a new HTTP method POST to our web application, lets call this /bot. The new source will look like this:

Snippet source:

const express = require('express');
const app = express();
app.get('/', (req, res) => {
res.send('Hello Express app!')
app.post('/bot', (req, res) => {
res.send('Bot in progress...');
app.listen(3000, () => {
console.log('server started');

Press "Run" on top to start the server, then you can reach this url using the full address (with HTTP POST method):


This url is the external bot endpoint. We'll use this later.

Now move back to the Tiledesk project console and open the Settings menù on the left panel of our Tiledesk project, selecting the Bots option:

Press the ADD BOT button, to create your own external bot. Choose the "External" option.

We must chose a name for the bot and placing in the Url field the external bot endpoint url of the repl app:

Click the CREATE BOT button. Tolobot is now available in our Bots summary list:

Now it's time to write some code to make our bot service functional.

Go back to the repl project. In the index.js file modify the /bot service, copying and pasting the following code:

const express = require('express');
const bodyParser = require('body-parser');
const { TiledeskChatbotClient } = require('@tiledesk/tiledesk-chatbot-client');
const app = express();
app.post('/bot', (req, res) => {
const tdclient =
new TiledeskChatbotClient(
request: req,
console.log('You asked: ' + tdclient.text);
// instantly reply "success" to TILEDESK
// Replies are asynchronous.
// You can reply when your data is ready
// i.e. send asynch messages whenever an event occurs.
let msg = {
text: 'Cheers! You asked: ' + tdclient.text
app.listen(3000, () => {
console.log('server started');

NOTE: just set APIKEY parameter to a generic string, as in the example. APIKEYs will be itroduced later in Tiledesk but Nodejs APIs already support them as a mandatory parameter. To send messages to the current conversation (and to do other interesting stuff on the same conversation) we used Tiledesk Chatbot Client library, that we imported on top of the the index.js file:

const { TiledeskChatbotClient } =

Remember to place the import in the dependencies section of your package.json file as follows:

"dependencies": {
"@tiledesk/tiledesk-chatbot-client": "^0.5.29"

You can find the full code of this tutorial on the repl linked here:


Here you can find an alternative version of the same code using raw calls to Tiledesk REST APIs instead of the NodeJS library.


Configure a Route for the chatbot

Now that our code is ok, we should configure a routing rule to make this chatbot available to our users. Select the Routing option and configure the corresponding rules as follows, activating the Bot, selecting Tolobot and marking the Bot only option for this routing, so Tolobot will be the only available Agent.

Live test

To test our chatbot go to the Requests menù and press the green "Simulate visitor" button as shown in the following figure.


A new browser Tab will open with the widget working as if it is already installed on your website.

Push the New conversation button on the widget. A conversation will open on the default routing. A hidden message is sent to your bot, if activated (as in our example). Your bot will reply with the message you previously configured in the code:

All the tutorial's source code is available on Github here

In the next tutorial you will learn how to interact with a Dialogflow agent directly from an external chatbot endpoint.

Do you have feedback on this article? Please send us your feedback writing an email to [email protected]