> For the complete documentation index, see [llms.txt](https://developer.tiledesk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.tiledesk.com/apis/rest-api/requests.md). # 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](https://www.npmjs.com/package/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](/apis/rest-api/management-api/departments.md#the-department-model) selected for the request. | | lead | Object | the [Lead model](/apis/rest-api/leads.md#the-lead-model) involved in this request. | | requester | Object | contains information about the user originated the request. This is a [Team model](/apis/rest-api/team.md#the-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) | | start\_date\_time | string | filter by date/time interval. Use the format DD/MM/YYYY HH:mm:ss to define the start of the interval. Please encode the query parameter like the example (07/10/2025 12:10:09 -> encoded 07%2F10%2F2025%2012%3A10%3A09) | | end\_date\_time | string | filter by date/time interval. Use the format DD/MM/YYYY HH:mm:ss to define the end of the interval. Please encode the query parameter like the example (07/10/2025 23:10:09 -> encoded 07%2F10%2F2025%2023%3A10%3A09) | | 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 | {% tabs %} {% tab title="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":{..} } ... ] } ``` {% endtab %} {% endtabs %} Example ``` curl -v -X GET -u andrea.leo@f21.it: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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} Example: ``` curl -v -X GET -u andrea.leo@f21.it: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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200 " %} ``` .. ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="200 " %} ``` { ... } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} Example ``` curl -v -X PATCH -H 'Content-Type:application/json' -u andrea.leo@f21.it: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 | {% tabs %} {% tab title="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"], .... } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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"], .... } ``` {% endtab %} {% endtabs %} ## 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 | {% tabs %} {% tab title="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":[], .... } ``` {% endtab %} {% endtabs %} ## 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](https://developer.tiledesk.com/apis/rest-api/messages#insert-multiple-messages). For common cases, use [Send message REST API](https://developer.tiledesk.com/apis/rest-api/messages#send-a-message) #### 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 | {% tabs %} {% tab title="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":{..} } ``` {% endtab %} {% endtabs %} Example ``` curl -v -X POST -H 'Content-Type:application/json' -u andrea.leo@f21.it: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 | {% tabs %} {% tab title="200 " %} ``` { "user_email": "giovanni@test.com", "user_name": "Giovanni" } ``` {% endtab %} {% endtabs %} Example ``` curl -v -X GET -u giovanni@tiledesk.com:password https://api.tiledesk.com/v3/63ad512e70d5ed0012ad6286/requests/support-group-63ad512e70d5ed0012ad6286-82c16d3b10dc4abba2326a5d7611b022/chatbot/parameters ```