# Chatbots

## The Bot model

| Key              | Type    | Description                                                   |
| ---------------- | ------- | ------------------------------------------------------------- |
| id               | String  | The unique identifier for the bot which is given by Tiledesk. |
| name             | String  | The bot name.                                                 |
| id\_project      | String  | The unique identifier of the project                          |
| type             | String  | The bot type. Permitted values: internal, external.           |
| secret           | String  | The bot secret token used for JWT authentication.             |
| createdBy        | String  | The unique identifier of the row creator                      |
| description      | String  | (Optional) The bot description.                               |
| url              | String  | (Optional) The bot external endpoint address                  |
| webhook\_url     | String  | (Optional)                                                    |
| webhook\_enabled | Boolean | (Optional)                                                    |
| trashed          | Boolean | (Optional) The bot status.                                    |
| attributes       | Object  | (Optional) The custom attributes which are set for the bot.   |
| language         | String  | (Optional) The bot language.                                  |
| createdAt        | String  | (Optional) The time when the bot was created.                 |
| public           | Boolean | (Optional) The sharing status of the bot. Default false.      |
| updatedAt        | String  | (Optional) The time when the bot was updated.                 |

## Get all bots

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/bots`

Allows an account to list all the bots of the project.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |

{% tabs %}
{% tab title="200 " %}

```
[
   {
      "_id":"5be9b2ecc72a050015e14951",
      "updatedAt":"2018-11-12T17:05:50.616Z",
      "createdAt":"2018-11-12T17:05:48.544Z",
      "name":"bot1",
      "id_project":"5b55e806c93dde00143163dd",
      "trashed":false,
      "createdBy":"5ab0f3fa57066e0014bfd71e",
      "__v":0,
      "external":false
   },
   {
      "_id":"5ce265596438e40017e3610d",
      "updatedAt":"2019-05-20T08:29:14.524Z",
      "createdAt":"2019-05-20T08:29:13.286Z",
      "name":"bot2",
      "id_project":"5b55e806c93dde00143163dd",
      "trashed":false,
      "createdBy":"5ab0f3fa57066e0014bfd71e",
      "__v":0,
      "external":false
   }
]
```

{% endtab %}
{% endtabs %}

Example

```
curl -v -X GET -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots
```

***

## Get a bot by id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/bots/:id`

Allows an account to get a bot of the project.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |
| id          | string | The bot identifier                                                                       |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |

{% tabs %}
{% tab title="200 " %}

```
  {
      "_id":"5be9b2ecc72a050015e14951",
      "updatedAt":"2018-11-12T17:05:50.616Z",
      "createdAt":"2018-11-12T17:05:48.544Z",
      "name":"bot1",
      "id_project":"5b55e806c93dde00143163dd",
      "trashed":false,
      "createdBy":"5ab0f3fa57066e0014bfd71e",
      "__v":0,
      "external":false
   }
```

{% endtab %}
{% endtabs %}

Example

```
curl -v -X GET -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951
```

***

## Export a bot in JSON format

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/bots/exportjson/:id`

Allows an accont to export the bot in json format

#### Path Parameters

| Name        | Type   | Description                                                                             |
| ----------- | ------ | --------------------------------------------------------------------------------------- |
| project\_id | string | The Project Id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The bot identifier                                                                      |

#### Query Parameters

| Name        | Type    | Description                                                 |
| ----------- | ------- | ----------------------------------------------------------- |
| intentsOnly | boolean | (Optional) if TRUE will be exported only the intents (faqs) |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | Authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

{% tabs %}
{% tab title="200 " %}

```
  {"webhook_enabled":false,"language":"en","name":"bot1","intents":[{"webhook_enabled":false,"enabled":true,"question":"\start","answer":"Hello","intent_display_name":"start","language":"en"}]}
```

{% endtab %}
{% endtabs %}

Example

```
curl -v -X GET -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/exportjson/5be9b2ecc72a050015e14951
```

***

## Create a new bot

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/bots`

Allows to add more bots.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

#### Request Body

| Name             | Type   | Description                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name             | string | The bot name                                                                                                                                                                                                                                                                                                                                             |
| description      | string | The bot description                                                                                                                                                                                                                                                                                                                                      |
| language         | string | The bot language with two-letter ISO 639-1 code.                                                                                                                                                                                                                                                                                                         |
| webhook\_enabled | string | Enable the webhook fullfillment endpoint                                                                                                                                                                                                                                                                                                                 |
| template         | string | If internal type is used you can specify the template used to create the faqs. Supported values : blank, handoff, example. Example is the default value. Blank is a basic chatbot with only start e defaultFallback intents. Handoff is like the basic chatbot with the Agent handoff intent. Example is a chatbot with a showcase of the main features. |
| type             | string | Supported type values are: "internal", "external". Default is "internal". With internal value the standard tiledesk bot engine is used. With external you can create your own chatbot engine specifing the url parameter.                                                                                                                                |
| url              | string | The external chatbot endpoint                                                                                                                                                                                                                                                                                                                            |

{% tabs %}
{% tab title="200 " %}

```
 {
      "_id":"5be9b2ecc72a050015e14951",
      "updatedAt":"2018-11-12T17:05:50.616Z",
      "createdAt":"2018-11-12T17:05:48.544Z",
      "name":"bot1",
      "id_project":"5b55e806c93dde00143163dd",
      "trashed":false,
      "createdBy":"5ab0f3fa57066e0014bfd71e",
      "__v":0,
      "external":false
   }
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X POST -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '{"name":"bot1"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots
```

***

## Fork a bot

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/bots/fork/:id`

Allows to fork an existing bot.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The bot identifier                                                                       |

#### Query Parameters

| Name      | Type   | Description                                                    |
| --------- | ------ | -------------------------------------------------------------- |
| public    | string | The sharing status of the bot. Permitted values: true \| false |
| projectid | string | The id of the project where wants to fork the bot              |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

{% tabs %}
{% tab title="200 " %}

```
{
   "message":"Chatbot forked successfully",
   "bot_id":"5ab0f3fa57066e0014bf777e"
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X PUT -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/fork/5be9b2ecc72a050015e14951?public=false&projectid=5b55e806c93dde0014316e33
```

***

## Import whole bot from JSON

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/bots/importjson/:id`

Allows to import the bot informations and intents from a JSON file.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | the bot identifier (on which perform import) (is null with create option)                |

#### Query Parameters

| Name      | Type   | Description                                                                                                                                                                                                                     |
| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| create    | string | Allows to create a chatbot before importing Permitted values: true \| false \| null                                                                                                                                             |
| replace   | string | (BETA) Allows you to clean the chatbot (all its intents) before importing Permitted values: true \| false \| null                                                                                                               |
| overwrite | string | Choose whether to replace intents with the same intent\_display\_name with the imported ones. If false or null Old intents with the same intent\_display\_name will not be overwritten. Permitted values: true \| false \| null |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

#### Request Body

| Name       | Type | Description                       |
| ---------- | ---- | --------------------------------- |
| uploadFile | json | The JSON file that contains data. |

{% tabs %}
{% tab title="200 " %}

```
{
   "_id":"5be9b2ecc72a050015e14951",
   "updatedAt":"2018-11-12T17:05:50.616Z",
   "createdAt":"2018-11-12T17:05:48.544Z",
   "name":"bot1",
   "id_project":"5b55e806c93dde00143163dd",
   "trashed":false,
   "createdBy":"5ab0f3fa57066e0014bfd71e",
   "__v":0,
   "external":false
}
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X POST -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d "@path_to_file/bot.json" https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/importjson/5be9b2ecc72a050015e14951
```

***

## Update a bot

<mark style="color:orange;">`PUT`</mark> `https://api.tiledesk.com/v3/:project_id/bots/:id`

Allows to update a bot.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The bot identifier                                                                       |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

#### Request Body

| Name             | Type   | Description                                                                                                                                                                                                               |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name             | string | The bot name                                                                                                                                                                                                              |
| url              | string | The bot external endpoint                                                                                                                                                                                                 |
| description      | string | The bot description                                                                                                                                                                                                       |
| language         | string | The bot language with two-letter ISO 639-1 code.                                                                                                                                                                          |
| webhook\_enabled | string | Enable the webhook fullfillment endpoint                                                                                                                                                                                  |
| type             | string | Supported type values are: "internal", "external". Default is "internal". With internal value the standard tiledesk bot engine is used. With external you can create your own chatbot engine specifing the url parameter. |

{% tabs %}
{% tab title="200 " %}

```
{
      "_id":"5be9b2ecc72a050015e14951",
      "updatedAt":"2018-11-12T17:05:50.616Z",
      "createdAt":"2018-11-12T17:05:48.544Z",
      "name":"bot1",
      "id_project":"5b55e806c93dde00143163dd",
      "trashed":false,
      "createdBy":"5ab0f3fa57066e0014bfd71e",
      "__v":0,
      "external":false
   }
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X PUT -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '{"name":"bot1"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951
```

***

## Delete a bot

<mark style="color:red;">`DELETE`</mark> `https://api.tiledesk.com/v3/:project_id/bots/:id`

Allows to delete a bot.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| id          | string | The bot identifier                                                                       |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |

{% tabs %}
{% tab title="200 " %}

```
{
      "_id":"5be9b2ecc72a050015e14951",
      "updatedAt":"2018-11-12T17:05:50.616Z",
      "createdAt":"2018-11-12T17:05:48.544Z",
      "name":"bot1",
      "id_project":"5b55e806c93dde00143163dd",
      "trashed":false,
      "createdBy":"5ab0f3fa57066e0014bfd71e",
      "__v":0,
      "external":false
   }
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X DELETE -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951
```