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

GET 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

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
   }
]

Example

curl -v -X GET -u [email protected]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots

---

Get a bot by id

GET 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

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
   }

Example

curl -v -X GET -u [email protected]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951

---

Export a bot in JSON format

GET 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

200

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

Example

curl -v -X GET -u [email protected]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/exportjson/5be9b2ecc72a050015e14951

---

Create a new bot

POST 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

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
   }

Example:

curl -v -X POST -H 'Content-Type: application/json' -u [email protected]:123456  -d '{"name":"bot1"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots

---

Fork a bot

POST 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

200

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

Example:

curl -v -X PUT -H 'Content-Type: application/json' -u [email protected]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/fork/5be9b2ecc72a050015e14951?public=false&projectid=5b55e806c93dde0014316e33

---

Import whole bot from JSON

POST 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.

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
}

Example:

curl -v -X POST -H 'Content-Type: application/json' -u [email protected]:123456  -d "@path_to_file/bot.json" https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/importjson/5be9b2ecc72a050015e14951

---

Update a bot

PUT 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.

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
   }

Example:

curl -v -X PUT -H 'Content-Type: application/json' -u [email protected]:123456  -d '{"name":"bot1"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951

---

Delete a bot

DELETE 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

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
   }

Example:

curl -v -X DELETE -H 'Content-Type: application/json' -u [email protected]:123456  https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/bots/5be9b2ecc72a050015e14951