# Build Custom App - Quick start

## Introduction

You can build context-relevant, action-oriented apps (aka plugins) directly on top of Tiledesk with ease. We want customers to be confident that any app they connect to their Tiledesk account will be useful, work well and use their data responsibly.

A Tiledesk app is simply a small web application installed in the agent interface using an [iFrame](https://www.w3schools.com/tags/tag_iframe.asp) that extends the product's functionality in some way. You can use any web technology to create a Tiledesk app, for example: HTML, Javascript, NodeJs, Java, Python, etc.

### Quick start

To keep things simple in this quick start, you'll install and use an app named **Example Echo App** in Tiledesk. Example Echo App is an example app created to show you how to create a new Tiledesk app for the Tiledesk App Store. With Example Echo App you can find also how to read and use the Tiledesk context parameters passed by the Tiledesk clients (dashboard, webchat and widget) to your app.

Here's Example Echo App in the conversation dashboard sidebar:

![image](https://user-images.githubusercontent.com/9378770/171464951-c775416f-f94b-43af-b70f-b8df4ba29412.png)

#### Preparation

* If you don't already have a Tiledesk account, register at <https://panel.tiledesk.com/v3/dashboard/#/signup>
* Navigate to the **Example Echo App** in the **Tiledesk App Store**

![image](https://user-images.githubusercontent.com/9378770/171465518-2201e929-a906-4958-8890-dc56adb08797.png)

* Click **Install** to install Example Echo App on your Tiledesk project

![image](https://user-images.githubusercontent.com/9378770/171465698-0656ca63-3e7b-4dc6-a8b3-89bcd0335222.png)

#### Try it out

Go to the Monitor menu and get data from a conversation that's open in the dashboard interface.

* Open any conversation in the **Monitor** interface.
* To open the Example Echo App in the **conversation sidebar**, click the **Apps** icon in the bottom-right side of the conversation panel.

![image](https://user-images.githubusercontent.com/9378770/171465893-6ecee6e8-62fd-43ec-b9e1-f19b29b30ff5.png)

The Example Echo App is loaded by Tiledesk using an iframe. In the textarea of the app you can find the **JSON context payload** passed by the Tiledesk client (Conversation Detail in this example) to the app.

![image](https://user-images.githubusercontent.com/9378770/171464951-c775416f-f94b-43af-b70f-b8df4ba29412.png)

This app is configured to be available in both the dashboard and webchat, as well as in the appstore. If you want also to see this app in the webchat **select a conversation** from the list of conversations and in the **right sidebar** of the conversation details, click the **Apps** button.

![image](https://user-images.githubusercontent.com/9378770/171917421-787eef49-daaf-4b91-8f63-b5b1a9e1cadd.png)

The Example Echo App is loaded by Tiledesk:

![image](https://user-images.githubusercontent.com/9378770/171917304-af3ef9a5-f88e-4662-b147-2c90624c8eb3.png)

#### Read the Tiledesk Context parameters using iframe postMessage

The JSON context payload showed in the text area is passed using the [iframe postMessage method](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). Using Javascript you can subscribe to the iframe postMessage method using the code below:

```
<script>
  window.addEventListener("message", (event) => {
    console.log('Tiledesk context payload ', event.data );
    ...  
  }, false);
</script>
```

Below you can find the structure of the JSON context payload:

* appname: the name of the app
* request: the request object
* token: the jwt token of the user logged in to the UI

Be careful with the code below you are continuously subscribed to the contextual parameters of Tiledesk. So if the context parameters change, for example because the conversation data changes (for example a new tag is added to the conversation), the subscription will be performed in real time.

#### Read the Tiledesk Context parameters using iframe query url parameters

You can also read some Tiledesk Context parameters getting the query url parameters passed in GET to the iframe. Tiledesk passes the following query parameters using the HTTP GET method:

* request\_id: A unique identifier for the request which is given to Tiledesk. Follow this pattern 'support-group-UUID'. You can find more info [here](https://github.com/Tiledesk/tiledesk-docs/blob/master/apis/rest-api/requests/README.md#the-request-model)
* project\_id: The unique identifier of the Tiledesk project
* app\_name: The name of the Tiledesk app

You can use the Tiledesk REST API, for example the [Request detail REST API](https://developer.tiledesk.com/apis/rest-api/requests#get-a-request-by-request_id), to obtain more information about the conversation passing the request\_id and the project\_id parameters.

Go to the [index.js page of the Example Echo App](https://replit.com/@nicolan74/tiledesk-helloworld-webchat-example-app#index.js) if you want to see how to retrieve the parameters sent by tiledesk using url parameters method.

### Note

The app is installed in several locations:

* Conversation detail in the Dashboard Monitor panel
* Conversation detail in the Agent Web Chat
* In the Tiledesk App Store.

However, data that's available in some locations may not be available in others. For example, your previous requests accessed conversation data. Conversation data is available in apps running in the conversation sidebar but not apps running in the Tiledesk App Store.

## Create a Tiledesk app

Now that you have your project, it's time to create your first app in the Apps menu:

* In Your Apps, click **Create a New App** button.

![image](https://user-images.githubusercontent.com/9378770/171993888-6979f011-fbe2-44f2-bd95-04b95b52a7ba.png)

* In the form panel insert :
  * The **app icon** of your app (required)
  * The **name** of your app (required)
  * The configure URL (optional). Used to create a custom configuration page for your app. Your app can in fact include a page to perform advanced configurations eg: https//myapp-for-tiledesk/ configuration. To access the custom configuration page, click on the "manage" button after installing the app
  * The **Render URL** (required): This attribute specifies the URL address of your webapp to embed via an iframe
  * The app short **description** (required)
  * The **learn more URL** (required)
  * Where you want your app to be available. Permitted values:
    * Dashboard: the app will be available in the conversation details panel of the dashboard
    * Webchat: the app will be available in the conversation details panel of the agent web chat
    * Widget: the app will be available in the home page panel of the widget (COMING SOON)
    * App Store: the app will be available in the Apps menu of the dashboard

![image](https://user-images.githubusercontent.com/9378770/171993907-008e785e-b924-4b75-8f7b-a5d3cefeb5cc.png)