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
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.
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
project_id
string
the Project Id is a unique code assigned to your project when you create it in Tiledesk.
Query Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Example
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Example:
Close a request by request_id
PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/close
Path Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Reopen a request by request_id
PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/reopen
Path Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
departmentid
string
the department identifier
nobot
boolean
Optional. Default is false. If nobot is true the bot is excluded from the assignment
Update a request by request_id
PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/
Path Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
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
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
member
string
the participant (agent or bot) identifier
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
array
the participants (agent or bot) identifiers array
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Update the request attributes
PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/attributes
Update the request custom attributes.
Path Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
object
the request attributes
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
text
string
the note content
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Get a request history by request_id
GET https://api.tiledesk.com/v3/:project_id/requests/:request_id/history
Path Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
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
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
Authorization
string
authorization token. Basic Auth or JWT
Content-Type
string
use "application/json" value
Rate a request by request_id
PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/rating
Path Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: guest
Content-Type
string
use "application/json" value
Request Body
rate
number
the request rate from 0 to 5
rate_message
string
the rate message
Example
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
member
string
the teammate (agent) identifier
Set the request followers
PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/followers
Set the request followers (agent).
Path Parameters
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
Content-Type
string
use "application/json" value
Request Body
array
the followers (agent) identifiers array
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: agent
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
project_id
string
the Project Id is a unique code assigned to your project when you create it in Tiledesk.
Headers
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: guest
Content-Type
string
use "application/json" value
Request Body
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
Example
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
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
Authorization
string
Authorization token. Basic Auth or JWT. Minumun role: guest
Content-Type
string
use "application/json" value
Example
Last updated