Requests

Requests are the means through which your end users (customers) communicate with agents in Tiledesk. Requests can originate from a number of channels, including email, chat, Facebook, Whatsapp or the API. All requests have a core set of properties. Commonly when a request is created via email channel it is also called a ticket in the Tiledesk platform. Instead when a request is created by a chat channel it is also called conversation.

The Request model

Key	Type	Description
id	String	The unique identifier for the request which is given by
request_id	String	A unique identifier for the request which is given to Tiledesk. Follow this pattern 'support-group-UUID'. It is an external Id, so you must uniquely generate this id and pass it to Tiledesk. For example you can generate this id like this: 'support-group-af4b54df-3237-4db5-9351' (using uuid or other UUID generator) or using timestamp like this 'support-group-TIMESTAMP'
first_text	String	the request first text.
department	Object	the Department model selected for the request.
lead	Object	the Lead model involved in this request.
requester	Object	contains information about the user originated the request. This is a Team model.
participants	Array	The list of the identifier of the teammates or bots who participated in the request.
participatingAgents	Array	The list of the teammates who participated in the request.
participatingBots	Array	The list of the bots who participated in the request.
hasBot	Boolean	Indicates whether a bot is participating in the conversation.
status	Number	The request status: TEMPORARY : 50, UNSERVED : 100, ABANDONED : 150, SERVED : 200, CLOSED : 1000
sourcePage	String	The request source page.
language	String	The request language.
userAgent	String	The user agent.
tags	Array	A list of tags objects associated with the request.
notes	Array	A list of notes objects associated with the request.
rating	Number	The request rating. From 0 to 5.
rating_message	String	The rating message.
waiting_time	Number	Wait time is calculated as duration between the first visitor message in the chat and the first agent message.
transcript	String	The chat transcript.
attributes	Object	The custom attributes which are set for the request.
channel	Object	The channel of the conversation.
createdAt	String	The time (ISO-8601 date string) when the request was created.
first_response_at	String	The time (ISO-8601 date string) when the first answer is given by bot or an agent
updatedAt	String	The time (ISO-8601 date string) when the request was updated.
assigned_at	String	The time (ISO-8601 date string) when the request was assigned to an agent or bot.
first_response_at	String	The time (ISO-8601 date string) when the agent or the bot replies the first time.
closed_at	String	The time (ISO-8601 date string) when the request was closed.
closed_by	String	The unique identifier of the user who closed the request.
createdBy	String	The unique identifier of the row creator
preflight	Boolean	If true the request has been proactively created by the system and the user has not yet sent a message
priority	String	Define the priority of the request. Available values: normal (default), low, hight, urgent.
location	Object	Define the location of the request obtained by a geo search based on the ip address of the client.
ticket_id	String	It is the number that uniquely identifies the request within the project.
snapshot	Object	The snapshot object containing context information (like department, lead, requester, agents, availableAgentsCount) when the the request was created.
id_project	String	The unique identifier of the project

You can use the API to get the request information.

Get all requests

GET https://api.tiledesk.com/v3/:project_id/requests

Allows an account to list all the requests for 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.

Query Parameters

Name	Type	Description
sortField	string	what field to sort the results by. default field is createdAt
direction	string	sort direction: 1 (asc) or -1 (desc). Return the results in ascending (1) or descending (-1) order. defaults to desc (-1)
page	number	what page of results to fetch. defaults to first page.
limit	number	specify the maximum number of results to be returned. default is 40 rows
full_text	string	make a fulltext search query
status	string	filter by request status. Values: 100 for unserved requests, 150 for abandoned requests, 1000 for closed requests, "all" to retrieve all statuses. Default value is status < 1000 so it returns all the opened requests. You can also search for multiple statuses separating the statuses with a comma (i.e. 100,200)
start_date	string	filter by date interval. Use the format DD/MM/YYYY to define the start of the interval (i.e. 01/09/2024)
end_date	string	filter by date interval. Use the format DD/MM/YYYY to define the end of the interval (i.e. 30/09/2024)
ticket_id	string	filter by ticket id
dept_id	string	filter by department id
lead	string	filter by lead id
hasBot	boolean	filter by the hasBot field. If hasBot is true, the service returns all requests served by the chatbot, If hasBot is false, the service returns all requests served by a human agent.
tags	string	filter by tag
channel	string	filter by channel name. The channel name can be: "chat21" for chat messages, "email" for inboud ticket email, "form" for ticket created using the Dashboard UI, "whatsapp" for Whatsapp channel, "telegram" for Telegram Channel, "messenger" for Facebook Messenger Channel
snap_lead_email	string	filter by the field email of the lead
snap_lead_lead_id	string	filter by the field lead_id of the lead

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minumun role: agent

200

{
   "perPage":40,
   "count":179,
   "requests":[
      {
            "_id":"5c81593adf767b0017d1aa67",
            "updatedAt":"2019-03-07T17:48:05.934Z",
            "createdAt":"2019-03-07T17:47:38.405Z",
            "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
            "requester_id":"5c81593adf767b0017d1aa66",
            "first_text":"first text message",
            "department":"5c34ba232c62730016da250e",
            "sourcePage":"https://www.tiledesk.com",
            "language":"it",
            "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
            "id_project":"5b55e806c93dde00143163dd",
            "createdBy":"5c81593adf767b0017d1aa66",
            "__v":2,
            "waiting_time":21709,
            "agents":[
               {
                  "__v":0,
                  "createdBy":"5aaa99024c3b110014b478f0",
                  "user_available":true,
                  "role":"admin",
                  "id_user":"5ab0f3fa57066e0014bfd71e",
                  "id_project":"5b55e806c93dde00143163dd",
                  "createdAt":"2018-10-03T14:40:19.521Z",
                  "updatedAt":"2019-03-07T17:47:38.405Z",
                  "_id":"5bb4d4d39214830015742b00"
               }
            ],
            "tags":[
            ],
            "notes":[
               {
                  "_id":"5e6ba903261616001752b9f4",
                  "text":"note 1",
                  "createdBy":"5aaa99024c3b110014b478f0",
                  "updatedAt":"2020-03-13T15:38:43.880Z",
                  "createdAt":"2020-03-13T15:38:43.880Z"
               }
            ],
            "participants":[
               "5aaa99024c3b110014b478f0"
            ],
            "status":200,
            "lead":{..}
         }
      ...
   ]
}

Example

curl -v -X GET -u [e-mail]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests

Get a request by request_id

GET https://api.tiledesk.com/v3/:project_id/requests/:request_id

Fetches a request by his or her request_id

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier.
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. Minumun role: agent

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "notes":[
      {
         "_id":"5e6ba903261616001752b9f4",
         "text":"note 1",
         "createdBy":"5aaa99024c3b110014b478f0",
         "updatedAt":"2020-03-13T15:38:43.880Z",
         "createdAt":"2020-03-13T15:38:43.880Z"
      }
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":200,
   "lead":{..}
}

Example:

curl -v -X GET -u [e-mail]:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/support-group-L_OG76RYhR0XFiMf2PK

Close a request by request_id

PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/close

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":1000,
   "lead":{..}
}

Reopen a request by request_id

PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/reopen

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Route a request to a department

PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/departments

Routes a request to a department.

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
departmentid	string	the department identifier
nobot	boolean	Optional. Default is false. If nobot is true the bot is excluded from the assignment

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Update a request by request_id

PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
first_text	string	the request first text
lead	string	the lead identifier
status	number	the request status
tags	array	the request tags
rating	number	the request rating
rating_message	string	the request rating message
language	string	the request language
sourcePage	string	the request source page

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Add a participant to a request

POST https://api.tiledesk.com/v3/:project_id/requests/:request_id/participants

Add a participant (agent or bot) to a request.

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
member	string	the participant (agent or bot) identifier

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Set the request participants

PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/participants

Set the request participants (agent or bot).

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
	array	the participants (agent or bot) identifiers array

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Delete a participant from the request

DELETE https://api.tiledesk.com/v3/:project_id/requests/:request_id/participants/:participantid

Delete a participant (agent or bot) from the request.

Path Parameters

Name	Type	Description
participantid	string	the participant (agent or bot) identifier
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Update the request attributes

PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/attributes

Update the request custom attributes.

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
	object	the request attributes

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Add a note to a request

POST https://api.tiledesk.com/v3/:project_id/requests/:request_id/notes

Add a participant (agent or bot) to a request.

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
text	string	the note content

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   ...
   "tags":[
   ],
   "notes":[
      {
         "_id":"5e6ba903261616001752b9f4",
         "text":"note 1",
         "createdBy":"5aaa99024c3b110014b478f0",
         "updatedAt":"2020-03-13T15:38:43.880Z",
         "createdAt":"2020-03-13T15:38:43.880Z"
      }
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Delete a note

DELETE https://api.tiledesk.com/v3/:project_id/requests/:request_id/notes/:noteid

Add a participant (agent or bot) to a request.

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
project_id	string	the Project Id is a unique code assigned to your project when you create it in Tiledesk.
noteid	string	the note identifier

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minumun role: agent

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
  ..
   "notes":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Get a request history by request_id

GET https://api.tiledesk.com/v3/:project_id/requests/:request_id/history

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier.
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. Minumun role: agent

200

..

Delete a request by request_id

DELETE https://api.tiledesk.com/v3/:project_id/requests/:request_id

Only the project owner can delete a request.

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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

200

{
  ...
}

Rate a request by request_id

PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/rating

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: guest
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
rate	number	the request rate from 0 to 5
rate_message	string	the rate message

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "rate":5,
   "rating_message":"great work"
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Example

curl -v -X PATCH -H 'Content-Type:application/json' -u [e-mail]:123456 -d '{"rating":5, "rating_message":"Very good"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/support-group-5b55e806c93dde00143163dd/rating

Add a follower to a request

POST https://api.tiledesk.com/v3/:project_id/requests/:request_id/followers

Add a follower (agent) to a request.

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
member	string	the teammate (agent) identifier

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",   
   "followers":["62dfbbbf6b07df3ecbb130f4"],
   ....
}

Set the request followers

PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/followers

Set the request followers (agent).

Path Parameters

Name	Type	Description
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
	array	the followers (agent) identifiers array

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "followers":["62dfbbbf6b07df3ecbb130f4"],
   ....
}

Delete a follower from the request

DELETE https://api.tiledesk.com/v3/:project_id/requests/:request_id/followers/:followerid

Delete a follower (agent) from the request.

Path Parameters

Name	Type	Description
follower	string	the teammate (agent) identifier
request_id	string	the request_id field. It's the external request identifier
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. Minumun role: agent

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "followers":[],
   ....
}

Create a request

POST https://api.tiledesk.com/v3/:project_id/requests/:request_id/

This method should be used for mass importing of messages. After this endpoint, use Insert multiple messages REST API. For common cases, use Send message REST API

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. Minumun role: guest
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
first_text	string	the request first text
request_id	string	the request identifier. If not specified an auto id is generated
language	string	the request language
sourcePage	string	the request source page

200

{
   "_id":"5c81593adf767b0017d1aa67",
   "updatedAt":"2019-03-07T17:48:05.934Z",
   "createdAt":"2019-03-07T17:47:38.405Z",
   "request_id":"support-group-L_OG76RYhR0XFiMf2PK",
   "requester_id":"5c81593adf767b0017d1aa66",
   "first_text":"first text message",
   "department":"5c34ba232c62730016da250e",
   "sourcePage":"https://www.tiledesk.com",
   "language":"it",
   "userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.119 Safari/537.36",
   "id_project":"5b55e806c93dde00143163dd",
   "createdBy":"5c81593adf767b0017d1aa66",
   "__v":2,
   "waiting_time":21709,
   "agents":[
      {
         "__v":0,
         "createdBy":"5aaa99024c3b110014b478f0",
         "user_available":true,
         "role":"admin",
         "id_user":"5ab0f3fa57066e0014bfd71e",
         "id_project":"5b55e806c93dde00143163dd",
         "createdAt":"2018-10-03T14:40:19.521Z",
         "updatedAt":"2019-03-07T17:47:38.405Z",
         "_id":"5bb4d4d39214830015742b00"
      }
   ],
   "tags":[
   ],
   "participants":[
      "5aaa99024c3b110014b478f0"
   ],
   "status":100,
   "lead":{..}
}

Example

curl -v -X POST -H 'Content-Type:application/json' -u [e-mail]:123456 -d '{"sender":"bb0d809b-b093-419b-8b48-11a192cc3619", "first_text":"1"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/

Get all chatbot parameters of a request

GET https://api.tiledesk.com/v3/:project_id/requests/:request_id/chatbot/parameters

Allows to obtain all the parameters set by the chatbot during the conversation.

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.
request_id	string	the request_id field. It's the external request identifier

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minumun role: guest
Content-Type	string	use "application/json" value

200

{
    "user_email": "[e-mail]",
    "user_name": "Giovanni"
}

Example

curl -v -X GET -u [e-mail]:password https://api.tiledesk.com/v3/63ad512e70d5ed0012ad6286/requests/support-group-63ad512e70d5ed0012ad6286-82c16d3b10dc4abba2326a5d7611b022/chatbot/parameters