# 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
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.tiledesk.com/apis/rest-api/bots.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.