Agents APIs

Agents are users who are assigned a user role. Agents are managed (added, updated, deleted) as users and have the same configurations as users (see the User API), but they also have some additional configurations. Use this API to manage the additional configurations associated with agents.

Agents can belong to one or more group: queues and tickets can be assigned to a group, and then any agent in that group can deal with queue or ticket, as required. See Groups API.

Agents can also be assigned to a team. Teams have a manager. Teams are used for informational and reporting purposes only. For example, you might manage a large number of agents, each of whom speaks one or more languages. Your team then can include several groups, each of which is assigned to the queue relevant for that language. Agents who speak multiple languages can be assigned to multiple groups.

Note that there is no requirement that all agents in a group must belong to the same team.

Agents can be assigned to features for handling and have workload limits for these features. Features are channels, i.e. the originating points for tickets (email, call center, Facebook, etc.). When an agent is assigned to a feature, Wix Answers can be set to automatically route tickets from these channels to the agent to begin handling, unless the agent is already handling the maximum number of tickets from these channels (according to the workload limit for that feature for that agent).

Search Agents by Criteria

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/search

Get a list of agents that fulfill the search/filtering criteria.
Payload Params
Description
Type
text
Filter by search string on user name, email address, GUID, and phone numbers

The search is a straight text match (not regular expression) from the start of any of the fields.
String
emails
Filter by agent's email addresses
List of strings
emailStatus
Filter by agent Email Status
Integer
locationIds
Filter by locations of the agents
List of location GUIDs

Max 50 IDs.
userIds
Filter by list of agent IDs 
List of user GUIDs
groupsIds
Filter by list of group IDs to include
List of group GUIDs
excludedGroupIds
Filter by list of group IDs to exclude
List of group GUIDs
queueIds
Filter by list of queues (for agents associated with a queue)
List of queue GUIDs
agentChannels
Filter by list of activity types
List of integers
callCenterId
Filter by associated call center ID (the Twilio ID of the agent)
String
isManager
Filter by whether the agent is a manager to other agents
Boolean
phoneNumber
Filter by phone number
roleIds
Filter by whether the agent belongs to one or more user roles
List of role GUIDs
page
The requested page. If not a positive integer, the first page is returned by default.
Integer
pageSize
The requested page size. If not a positive integer, the default is 10 agents per request.
Integer, 1 to 250
agentSortType
Sort type. Possible values:
* User creation date, ascending (10)
* User creation date, descending (20)
* User last updated date, ascending (30): This refers to the user data; see 120
* User last updated date, descending (40): This refers to the user data; see 130
* User first name, ascending (50)
* User first name, descending (60)
* Email address, ascending (70)
* Email address, descending (80)
* Date user became agent, ascending (100)
* Date user became agent, descending (110)
* Agent last updated date, ascending (120): This refers to the agent data; see 20
* Agent last updated date, descending (130): This refers to the agent data; see 30
* Location, ascending (140)
* Location, descending (150)
* Status, ascending (200)
* Status, descending (210)
* Time since last status change, ascending (220)
* Time since last status change, descending (230)
* Average time on call, ascending (240)
* Average time on call, descending (250)
* Number of calls, ascending (260)
* Number of calls, descending (270)
* Last chat assigned, ascending (300)
* Last chat assigned, descending (310)
* Number of active chats, ascending (320)
* Number of active chats, descending (330)
* Job title, ascending (340)
* Job title, descending (350)
* Channel, ascending (380)
* Channel, descending (390)
* Role ID, ascending (400)
* Role ID, descending (410)
* Location ID, ascending (420)
* Location ID, descending (430)
* Team ID, ascending (440)
* Team ID, descending (450)
* Manager ID, ascending (460)
* Manager ID, descending (470)

If not defined, the default is 130.
Integer
fromCreationDate
Filter by users created on or after this date
toCreationDate
Filter by users created on or before this date
fromLastUpdateDate
Filter by users updated on or after this date
toLastUpdateDate
Filter by users updated on or before this date
timeZone
Enter when searching by one of the above date fields.
Long time zone name string, for example America/Denver
customFieldFilters
Filter using a map of user custom field values; a structure of one or more fields and values, each one as follows:
* <API field name> (string): The API name of the field (auto-generated; see Finding a Custom Field Name)
* <Custom Field values / range> (format depends on the field):
  * fromDate (Date string)
  * toDate (Date string)
  * from (long)
  * to (long)
  * values (list)
  * text (string)
  * searchType (integer):
    * Contains (2)
    * No contains (3)
  * bool (Boolean)
Structure
Payload Example:
1
2
3
4
5
6
7
8
9
POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/search

{
 "text":"example",
 "emails":["example1@gmail.com", "example2@gmail.com"],
 "page":1,
 "pageSize":10,
 "agentSortType":170
}
Response Example:
1
2
3
4
5
6
7
8
9
{
  "items": [ List of @Agent objects ],
  "itemsCount": 108,
  "page": 2,
  "numPages": 22,
  "previousPage": 1,
  "nextPage": 3,
  "pageSize": 5
}

Invite a User to Become an Agent

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/invite

Invite a user to become an agent. Wix Answers sends the user an email message. The user can click a link in the email message to complete the process of becoming an agent.
Limitation
Your tenant agreement limits the number of agents you can add. For more information, contact Wix Answers customer support.
Expiration
The link sent in the email message is valid for 72 hours.
Payload Params
Description
Type
Required
roleId
email
User's email address
String
Payload Example:
1
2
3
4
5
6
POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/invite

{
 "email":"example@wix.com",
 "role":"77bc8694-5ccf-436c-ab2b-543563a5f425",
}

Revoke an Agent Invitation

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/revoke-invitation

Revoke an invitation to a user to become an agent. After you revoke an invitation, if the user clicks the link in the invitation, Wix Answers informs the user that the invitation was revoked.

No payload is required or expected.
Request Example:
1
POST https://<account_subdomain>.wixanswers.com/api/v1/agents/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/revoke-invitation

Update Roles of Agents in Bulk

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/role
Update the role of up to 1000 agents. The old role, if any, is replaced with the new one. Note that this endpoint cannot change a user into an agent.
  • Authorization: Requires agent authorization token
  • Content type: application/json; charset=utf-8
  • Accept: application/json
  • Response: None
Payload Params
Description
Type
Required
agentIds
List of agents to update
List of user GUIDs

Max 1000.

At least one user ID is required
roleId
User role to assign to agents
Request Example:
1
2
3
4
5
6
7
POST https://<account_subdomain>.wixanswers.com/api/v1/agents/role

{
    "agentIds": ["bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa","e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a
"],
    "roleId": "d367738e-368e-41fe-9289-1a5cbbc3c239"
}

Set Workload Features for Agents

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/features
Add workload features (originating points of tickets) to up to 50 agents. Wix Answers may auto-route tickets of these features to these agents (when configured to do so in the UI).
Payload Params
Description
Type
Required
agentIds
List of agents for whom to set features
List of user GUIDs

Max 50.

At least one agent ID is required
features
List of integers

At least one feature is required
Request Example:
1
2
3
4
5
6
7
POST https://<account_subdomain>.wixanswers.com/api/v1/agents/features

{
    "agentIds": ["bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa","e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a
"],
    "features": [10, 20]
}

Set Maximum Workloads for Agents

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/features/workloads
Set maximum workloads for features for up to 50 agents. Wix Answers will not auto-routing tickets related to this feature to an agent who has currently reached or exceeded the maximum workload for that feature. Note that this maximum does not prevent an agent from manually handling any kind of ticket.
Payload Params
Description
Type
Required
agentIds
List of agents for whom to set features
List of user GUIDs

Max 50.

At least one agent ID is required
maxWorkloads
Map of Activity Types to maximum values
Structure

At least one feature is required
Request Example:
1
2
3
4
5
6
7
8
9
POST https://<account_subdomain>.wixanswers.com/api/v1/agents/features/workloads

{
  "agentIds" : ["bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa","e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a"],
  "maxWorkloads": {
    "10": 3,
    "30": 2
  }
}

End All Ticket Handling By an Agent

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/handling/end
Remove an agent from handling any tickets.

This endpoint removes the agent from handling up to 1,000 tickets, starting from the most recently created. To remove an agent from more than this number of tickets, call this endpoint multiple times, as required. To check if an agent is handling any tickets, use the handlingUserIds filter parameter when searching for tickets.


No payload is required or expected.

Get List of Agents

GET https://<tenant_subdomain>.wixanswers.com/api/v1/agents?userType={userType}

Get the list of agents, optionally filtered by user type.
Request Params
Description
Type
Required
userType
Integer

Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/agents

Get Agent Information

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}

Get information about an agent.
Request Example:
1
POST https://<account_subdomain>.wixanswers.com/api/v1/agents/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa

Get Your Agent Information

GET https://<tenant_subdomain>.wixanswers.com/api/v1/agents/me
Get agent information for the user making the request.
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/agents/me

Update Agent Role

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/permissions
Change an agent's user role.
Payload Params
Description
Type
Required
roleId
Payload Example:
1
2
3
4
5
https://<tenant_subdomain>.wixanswers.com/api/v1/agents/e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a/permissions

{
 "roleId":"bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa",
}

Remove Agent by ID

DELETE https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/permissions

Change an agent to be a regular user, given the agent's GUID.
Request Example:
1
DELETE https://<account_subdomain>.wixanswers.com/api/v1/agents/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/permissions

Remove Agent by Email Address

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/removeByEmail?email={email address}

Change an agent to be a regular user, given the agent's email address.
Request Params
Note that although this is a POST method, you must send the email address using a request param.
Request Params
Description
Type
Required
email
The agent's email address
String
Request Example:
1
POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/removeByEmail?email=example@wix.com

Get an Agent's Groups

GET https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/groups

Get an agent's list of groups.
Request Example:
1
GET https://<account_subdomain>.wixanswers.com/api/v1/agents/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/groups

Update Agent Data

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/{endpoint}

Update agent data, depending on the endpoint. See the table, below, for details.

Some of the data is currently for future use in the UI. See the table, below, for details.
Each endpoint takes a single, mandatory parameters, as follows:
Endpoint
Payload Param
Description
Type
Required
/jobTitle
jobTitle
The agent's job title

For future use in UI.
String
/managerId
managerId
The agent's manager

For future use in UI.
User GUID
/locationId
locationId
The agent's location
Location GUID
/teamId
teamId
The agent's team
Team GUID
/locales
locales
The languages with which the agent is familiar

For future use in UI.
List of language code strings, for example: ['en','de']
/active
active
Whether the agent is active or not

For future use in UI.
Boolean
Payload Example:
1
2
3
4
5
6

POST https://<tenant_subdomain>.wixanswers.com/api/v1/agents/e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a/active

{
 "active": true,
}

Update Your Knowledge Base UI Locale

PUT https://<tenant_subdomain>.wixanswers.com/api/v1/agents/me/interfaceLocale

Update the locale (language) of the KB UI for the user making the request. The change is stored in the interfaceLocale parameter of the Agent Object.

Payload Params
Description
Type
Required
locale
The agent's new interface language
Language code string, for example: 'de'
Payload Example:
1
2
3
4
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/agents/me/interfaceLocale
{
  "locale":"en"
}

Delete Agent Data

DELETE https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/{endpoint}

Delete agent data, depending on the endpoint (see endpoint options in the table in Update Agent Data).

Some of the data is currently for future use in the UI.
Payload Example:
1
DELETE https://<account_subdomain>.wixanswers.com/api/v1/agents/bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa/active

Update an Agent's Custom Fields

User Custom Fields
An agent may have additional custom fields associated with the agent's user record. For more information, see Update a User's Custom Fields.
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/agents/{agent GUID}/fields

Update custom field values for an agent record. For information about configuring the available custom fields for an agent, see Custom Fields API.
Merge
Unlike most update scenarios in Wix Answers (see Important Information about Updating Structures Using the API), when updating agent custom fields you can specify whether all existing custom field values are first removed, or whether the new values sent with this API call are added to the existing values.
Payload Params
Description 
Format
Required
customFields
A map of new field values, each mapping containing:
* <custom field GUID>: The field id
* <new value>: The new value in the relevant format
Structure
merge
Whether to add the new values but leave any existing values that are not being replaced (true), or to first remove all existing custom field values and then add the new values (false).
Boolean

The default is false.

Payload Example:
1
2
3
4
5
6
7
8
9
PUT https://<tenant_subdomain>.wixanswers.com/api/v1/agents/77bc8694-5ccf-436c-ab2b-543563a5f425/fields

{
    "merge": false,
    "customFields": {
      "bd948e62-a3fd-4cf0-87f3-ee6a0ae7f3fa":5,
      "e932c0a3-6e9b-43cf-b3a9-0ae790f6ee6a":"new value"
    }
}