Requests
The Request model
id
String
The unique identifier for the request which is given by
request_id
String
A unique identifier for the request given to Tiledesk. Follow this pattern 'support-group-UUID'. It is an external Id, so you must generate this id and pass it to Tiledesk. Example: 'support-group-af4b54df-3237-4db5-9351' (using https://www.npmjs.com/package/uuid or other UUID generator) or using timestamp like 'support-group-TIMESTAMP'
first_text
String
The request first text.
department
Object
The Department model (https://developer.tiledesk.com/apis/rest-api/management-api/departments#the-department-model) selected for the request.
lead
Object
The Lead model (https://developer.tiledesk.com/apis/rest-api/leads#the-lead-model) involved in this request.
requester
Object
Contains information about the user who originated the request. This is a Team model (https://developer.tiledesk.com/apis/rest-api/team#the-team-model).
participants
Array
The list of identifiers 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 tag objects associated with the request.
notes
Array
A list of note 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 the duration between the first visitor message in the chat and the first agent message.
transcript
String
The chat transcript.
attributes
Object
Custom attributes set for the request.
channel
Object
The channel of the conversation.
createdAt
String
ISO-8601 date string when the request was created.
first_response_at
String
ISO-8601 date string when the first answer is given by bot or an agent.
updatedAt
String
ISO-8601 date string when the request was updated.
assigned_at
String
ISO-8601 date string when the request was assigned to an agent or bot.
first_response_at
String
ISO-8601 date string when the agent or bot replies the first time.
closed_at
String
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
Priority of the request. Values: normal (default), low, hight, urgent.
location
Object
Location of the request obtained by a geo search based on the client's IP address.
ticket_id
String
The number that uniquely identifies the request within the project.
snapshot
Object
Snapshot object containing context information (like department, lead, requester, agents, availableAgentsCount) when the request was created.
id_project
String
The unique identifier of the project.
You can use the API to get request information.
Get all requests
GET https://api.tiledesk.com/v3/:project_id/requests
Description: List all the requests for the project.
Path parameters
project_id (string) — Project Id assigned to your project in Tiledesk.
Query parameters
sortField (string) — Field to sort results by (default: createdAt).
direction (string) — Sort direction: 1 (asc) or -1 (desc). Defaults to -1.
page (number) — Page of results to fetch (defaults to first page).
limit (number) — Max number of results (default: 40).
full_text (string) — Fulltext search query.
status (string) — Filter by request status: 100 (unserved), 150 (abandoned), 1000 (closed), "all". Default is status < 1000 (opened). Multiple statuses allowed comma-separated (e.g. 100,200).
start_date (string) — Start of date interval (format DD/MM/YYYY).
end_date (string) — End of date interval (format DD/MM/YYYY).
ticket_id (string) — Filter by ticket id.
dept_id (string) — Filter by department id.
lead (string) — Filter by lead id.
hasBot (boolean) — If true returns requests served by chatbot; if false returns those served by human agent.
tags (string) — Filter by tag.
channel (string) — Filter by channel name. Possible values: "chat21", "email", "form", "whatsapp", "telegram", "messenger".
snap_lead_email (string) — Filter by lead.email.
snap_lead_lead_id (string) — Filter by lead.lead_id.
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Example response (200)
Example curl
Get a request by request_id
GET https://api.tiledesk.com/v3/:project_id/requests/:request_id
Description: Fetch a request by its request_id (external identifier).
Path parameters
project_id (string)
request_id (string) — external request identifier.
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Example response (200)
Example curl
Close a request by request_id
PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/close
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Example response (200)
The returned request object will have status: 1000.
Reopen a request by request_id
PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/reopen
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Example response (200)
The returned request object will have status: 100.
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
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body
departmentid (string) — the department identifier
nobot (boolean, optional) — default false. If true the bot is excluded from assignment.
Example response (200)
Returns the updated request object (status usually set to 100).
Update a request by request_id
PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body (any of the following)
first_text (string)
lead (string) — lead identifier
status (number)
tags (array)
rating (number)
rating_message (string)
language (string)
sourcePage (string)
Example response (200)
Returns the updated request object.
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
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body
member (string) — the participant (agent or bot) identifier
Example response (200)
Returns the updated request object with the new participant.
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
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body
array — participants (agent or bot) identifiers array
Example response (200)
Returns the updated request object.
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
project_id (string)
request_id (string)
participantid (string) — participant identifier
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Example response (200)
Returns the updated request object.
Update the request attributes
PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/attributes
Update request custom attributes.
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body
object — the request attributes
Example response (200)
Returns the updated request object.
Add a note to a request
POST https://api.tiledesk.com/v3/:project_id/requests/:request_id/notes
Add a note to a request.
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body
text (string) — the note content
Example response (200)
Returns the updated request object including the new note.
Delete a note
DELETE https://api.tiledesk.com/v3/:project_id/requests/:request_id/notes/:noteid
Delete a note from a request.
Path parameters
project_id (string)
request_id (string)
noteid (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Example response (200)
Returns the updated request object (notes array updated).
Get a request history by request_id
GET https://api.tiledesk.com/v3/:project_id/requests/:request_id/history
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum 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
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT.
Content-Type: application/json
Example response (200)
Returns confirmation (object).
Rate a request by request_id
PATCH https://api.tiledesk.com/v3/:project_id/requests/:request_id/rating
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: guest.
Content-Type: application/json
Request body
rate (number) — rate from 0 to 5
rate_message (string) — the rate message
Example response (200)
Example curl
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
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body
member (string) — teammate (agent) identifier
Example response (200)
Returns updated request with followers array populated.
Set the request followers
PUT https://api.tiledesk.com/v3/:project_id/requests/:request_id/followers
Set the request followers (agent list).
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Content-Type: application/json
Request body
array — followers (agent) identifiers array
Example response (200)
Returns updated request.
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
project_id (string)
request_id (string)
followerid (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: agent.
Example response (200)
Returns updated request (followers array updated).
Create a request
POST https://api.tiledesk.com/v3/:project_id/requests/:request_id/
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
project_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: guest.
Content-Type: application/json
Request body
first_text (string)
request_id (string) — the request identifier. If not specified an auto id is generated.
language (string)
sourcePage (string)
Example response (200)
Returns the created request object.
Example curl
Get all chatbot parameters of a request
GET https://api.tiledesk.com/v3/:project_id/requests/:request_id/chatbot/parameters
Obtain all parameters set by the chatbot during the conversation.
Path parameters
project_id (string)
request_id (string)
Headers
Authorization (string) — Basic Auth or JWT. Minimum role: guest.
Content-Type: application/json
Example response (200)
Example curl
Links
Authentication: https://developer.tiledesk.com/apis/rest-api/authentication
Leads: https://developer.tiledesk.com/apis/rest-api/leads
Last updated 1 year ago
Privacy
This page references the privacy policy: https://tiledesk.com/privacy.html