Team

A teammate is a special user who represents a Tiledesk user invited to a project with a specific role. When you work with teammates very often you will not use the user_id of the Tiledesk user but rather the specific id of your teammate in the project. In the Tiledesk API the temamate is named project_user. For example, if you want to know your project_user in a specific project, all you have to do is call this API: Get a teammate by id.

The Team Model

Key	Type	Description
id	String	The unique identifier for the teammate which is given by Tiledesk.
role	String	The teammate role. Values: owner, agent, admin, user, guest
user_available	Boolean	Dermine if the teammate is available or unavailable to accept requests
id_user	Object	The user object referenced by the teammate
max_served_chat	Number	Number of chats that agent is allowed to take at one time (Only Enterprise)
number_assigned_requests	Number	Number of active request for the teammate (Only Enterprise)
status	String	The status of a teammate. Can be "active" or "disabled"
isBusy	Boolean	Determine if the teammate is busy (Only Enterprise)
profileStatus	String	It is an alias associated to the teammate availability. For example: inactive, to the toilet, on the phone
attributes	Object	The custom attributes which are set for the teammate.
tags	Array	A list of tags objects associated with the teammate.
settings	Object	The setting configurations of the teammate.
presence	Object	The presence info of the teammate.
isAuthenticated	Boolean	Returns true if is strongly authenticated (custom-auth or email/password), false otherwise (anonymous).
isBusy	Boolean	Returns true if is teammate is busy, false otherwise. See Tiledesk Smart Assignment for more info.
createdAt	String	The time (ISO-8601 date string) when the teammate was created.
updatedAt	String	The time (ISO-8601 date string) when the teammate was updated.
createdBy	String	The unique identifier of the row creator
id_project	String	The unique identifier of the project
trashed	Boolean	True if the teammate has been removed from the project

The Presence model

Presence lets you track the online and offline status of the teammates in real-time (if you use Tiledesk Websocket or Webhook) and store the information state. Possible values: online, offline. Attention: an agent passes from online to offline only when he closed all Tiledesk messaging apps (eg Agent web chat in all tabs and mobile apps).

Agent availability

The field user_available determines if the teammate is available or unavailable to accept requests. Attention: Agent availability changes only when the agent explicitly changes from the UI from available to unavailable. If an agent is available and logs out, the agent remains available as he may have decided to serve chats from another channel (eg. Tiledesk mobile app).

Get the team

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

Return the team members and availability. Use the optional query parameter trashed=true to include trashed teammates in the response.

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
trashed	string	Optional. Set to true to include trashed teammates in the response. When false or omitted, trashed teammates are excluded (default).

Headers

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

200 List of teammates. Without trashed (default): only active.

[
   {
      "_id":"5df2240cecd41b00173a06bc",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5aaa99024c3b110014b478f0",
         "email":"[email protected]",
         "firstname":"Andrea",
         "lastname":"Leo",
         "emailverified":true,
         "__v":0,
         "resetpswrequestid":""
      },
      "role":"owner",
      "user_available":true,
      "trashed":false,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-12T11:27:08.581Z",
      "updatedAt":"2019-12-12T11:27:08.581Z",
      "__v":0
   },
   {
      "_id":"5df34ab80bc923001792e274",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5de9200d6722370017731969",
         "email":"[email protected]",
         "firstname":"Nuovopre",
         "lastname":"Pre",
         "emailverified":false,
         "createdAt":"2019-12-05T15:19:41.296Z",
         "updatedAt":"2019-12-05T15:19:41.296Z",
         "__v":0
      },
      "role":"admin",
      "user_available":true,
      "trashed":false,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-13T08:24:24.586Z",
      "updatedAt":"2020-01-04T09:45:26.331Z",
      "__v":0
   }
]

Example (default, exclude trashed):

curl -v -X GET \
  -u [email protected]:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users

Example (include trashed teammates):

curl -v -X GET \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users?trashed=true"

Get a teammate by id

GET https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id

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.
project_user_id	string	The teammate identifier.

Headers

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

200

   {
      "_id":"5df2240cecd41b00173a06bc",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5aaa99024c3b110014b478f0",
         "email":"[email protected]",
         "firstname":"Andrea",
         "lastname":"Leo",
         "emailverified":true,
         "__v":0,
         "resetpswrequestid":""
      },
      "role":"owner",
      "user_available":true,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-12T11:27:08.581Z",
      "updatedAt":"2019-12-12T11:27:08.581Z",
      "__v":0
   }

Example:

curl -v -X GET \
  -u [email protected]:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df2240cecd41b00173a06bc

Get a teammate by user id

GET https://api.tiledesk.com/v3/:project_id/project_users/users/:user_id

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.
user_id	string	The user identifier.

Headers

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

200

   {
      "_id":"5df2240cecd41b00173a06bc",
      "id_project":"5df2240cecd41b00173a06bb",
      "id_user":{
         "_id":"5aaa99024c3b110014b478f0",
         "email":"[email protected]",
         "firstname":"Andrea",
         "lastname":"Leo",
         "emailverified":true,
         "__v":0,
         "resetpswrequestid":""
      },
      "role":"owner",
      "user_available":true,
      "createdBy":"5aaa99024c3b110014b478f0",
      "createdAt":"2019-12-12T11:27:08.581Z",
      "updatedAt":"2019-12-12T11:27:08.581Z",
      "__v":0
   }

Example:

curl -v -X GET \
  -u [email protected]:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/users/5aaa99024c3b110014b478f0

Invite an agent

POST https://api.tiledesk.com/v3/:project_id/project_users/invite

Invite an agent to a project.

Path Parameters

Name	Type	Description
project_id	string	The project_id is a unique code assigned to your project when you create it in Tiledesk

Headers

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

Request Body

Name	Type	Description
email	string	the agent email address
role	string	the agent role. Accepted values: agent, admin
firstname	string	the firstname of the agent
lastname	string	the lastname of the agent
user_available	boolean	the initial agent status. Available (true) or unavailable (false).

200 Teammate invited successfully

{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "email": "[email protected]",
    "firstname": "Nuovopre",
    "lastname": "Pre",
    "emailverified": false,
    "createdAt": "2019-12-05T15:19:41.296Z",
    "updatedAt": "2019-12-05T15:19:41.296Z",
    "__v": 0
  },
  "role": "admin",
  "user_available": true,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2019-12-13T08:24:24.586Z",
  "__v": 0
}

Example:

curl -v -X POST \
  -H 'Content-Type: application/json' \
  -u [email protected]:password \
  -d '{"email":"[email protected]","role":"agent","firstname":"Mario","lastname":"Rossi","user_available":true}' \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/invite

Update the current logged teammate

PUT https://api.tiledesk.com/v3/:project_id/project_users/

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: agent
Content-Type	string	use "application/json" value

Request Body

Name	Type	Description
role	string	The teammate role. Permitted values: admin, agent.
user_available	boolean	The teammate availability. True for available, false for unavailable. Default is true
max_served_chat	number	The number of concurrent chats the teammate can take at once.
attributes	object	The teammate custom attributes
settings	object	The teammate settings object

200 Updated teammate

{
  "_id": "5df2240cecd41b00173a06bc",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5aaa99024c3b110014b478f0",
    "email": "[email protected]",
    "firstname": "Andrea",
    "lastname": "Leo",
    "emailverified": true,
    "__v": 0,
    "resetpswrequestid": ""
  },
  "role": "admin",
  "user_available": false,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-12T11:27:08.581Z",
  "updatedAt": "2020-01-04T09:50:00.000Z",
  "__v": 0
}

Example:

curl -v -X PUT \
  -H 'Content-Type: application/json' \
  -u [email protected]:password \
  -d '{"user_available":false,"role":"admin"}' \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/

Update a teammate by id

PUT https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id

It requires admin role

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
project_user_id	string	The teammate identifier.

Headers

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

Request Body

Name	Type	Description
role	string	The teammate role. Permitted values: admin, agent.
user_available	boolean	The teammate availability. True for available, false for unavailable. Default is true
max_served_chat	number	The number of concurrent chats the teammate can take at once.
attributes	object	The teammate custom attributes
settings	object	The teammate settings object

200 Updated teammate

{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "email": "[email protected]",
    "firstname": "Nuovopre",
    "lastname": "Pre",
    "emailverified": false,
    "createdAt": "2019-12-05T15:19:41.296Z",
    "updatedAt": "2019-12-05T15:19:41.296Z",
    "__v": 0
  },
  "role": "agent",
  "user_available": true,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2020-01-04T09:55:00.000Z",
  "__v": 0
}

Example:

curl -v -X PUT \
  -H 'Content-Type: application/json' \
  -u [email protected]:password \
  -d '{"role":"agent","user_available":true}' \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274

Remove a teammate from the project

DELETE https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id

Remove an agent from a project. The type of removal is controlled by query parameters:

• soft (soft=true): Soft delete (ghost delete). The teammate is marked as trashed and can be restored later. Data is preserved.

• hard (hard=true): Hard delete. The teammate is permanently removed from the database. Warning: statistics referring to this teammate will be lost.

• Disable (no soft or hard): The teammate is disabled but remains visible on the dashboard and can be re-enabled. Sets status: "disabled" and user_available: false.

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
project_user_id	string	The teammate identifier.

Query Parameters

Name	Type	Description
soft	string	Set to true for soft delete (ghost delete). The teammate is marked as trashed and can be restored.
hard	string	Set to true for hard delete. Permanently removes the teammate from the database; statistics referring to this teammate will be lost.

Headers

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

200 Returns the updated or removed project_user. For soft delete: trashed is true; for disable: status is "disabled" and user_available is false; for hard delete: the deleted project_user object.

{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "firstname": "Nuovopre",
    "lastname": "Pre"
  },
  "role": "admin",
  "user_available": false,
  "status": "disabled",
  "trashed": false,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2020-01-04T10:00:00.000Z",
  "__v": 0
}

404 Project user not found

500 Server error

Example (soft delete - can be restored):

curl -v -X DELETE \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274?soft=true"

Example (hard delete - permanent, statistics lost):

curl -v -X DELETE \
  -u [email protected]:password \
  "https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274?hard=true"

Example (disable - remains visible, can be re-enabled):

curl -v -X DELETE \
  -u [email protected]:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274

Restore a trashed teammate

PUT https://api.tiledesk.com/v3/:project_id/project_users/:project_user_id/restore

Restore a teammate that was previously soft-deleted (trashed). Sets trashed: false and status: "active". The teammate must be in trashed state; if not, the API returns 400.

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
project_user_id	string	The teammate identifier (project_user id) to restore.

Headers

Name	Type	Description
Authorization	string	Authorization token. Basic Auth or JWT. Minimum role: admin

200 Teammate restored successfully

{
  "_id": "5df34ab80bc923001792e274",
  "id_project": "5df2240cecd41b00173a06bb",
  "id_user": {
    "_id": "5de9200d6722370017731969",
    "email": "[email protected]",
    "firstname": "Nuovopre",
    "lastname": "Pre",
    "emailverified": false,
    "createdAt": "2019-12-05T15:19:41.296Z",
    "updatedAt": "2019-12-05T15:19:41.296Z",
    "__v": 0
  },
  "role": "admin",
  "user_available": true,
  "status": "active",
  "trashed": false,
  "createdBy": "5aaa99024c3b110014b478f0",
  "createdAt": "2019-12-13T08:24:24.586Z",
  "updatedAt": "2020-01-04T10:05:00.000Z",
  "__v": 0
}

400 Teammate is not trashed and cannot be restored

404 Teammate not found

Example:

curl -v -X PUT \
  -u [email protected]:password \
  https://api.tiledesk.com/v3/5df2240cecd41b00173a06bb/project_users/5df34ab80bc923001792e274/restore