Wix Answers Help Center
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 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.
Get a list of agents that fulfill the search/filtering criteria.
- Authorization: Requires agent authorization token and permission FETCH_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Structure including list of Agent Objects
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.
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.
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Agent Object
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.
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.
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: None
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
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).
- Authorization: Requires agent authorization token and permission MANAGE_CHANNEL_ASSIGNMENT
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: List of agent GUIDs
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 Activity Types | 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.
- Authorization: Requires agent authorization token and permission MANAGE_CHANNEL_WORKLOAD
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: List of agent GUIDs
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.
Also see End Handling a Ticket (Agent) and End All Handling of a Ticket.
- Authorization: Requires agent authorization token and permission END_HANDLE_TICKET_SESSIONS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: None
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.
Get the list of agents, optionally filtered by user type.
- Authorization: Requires agent authorization token and permission FETCH_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: List of Agent Objects
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.
Get information about an agent.
- Authorization: Requires agent authorization token and permission FETCH_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Agent Object
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.
- Authorization: Requires agent authorization token for specific agent and permission FETCH_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Agent Object
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.
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Agent Object
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
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: None
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.
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: None
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.
Get an agent's list of groups.
- Authorization: Requires agent authorization token and permission FETCH_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: List of Group objects
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.
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.
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Agent Object
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.
- Authorization: Requires agent authorization token
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: 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.
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.
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Agent Object
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.
Update custom field values for an agent record. For information about configuring the available custom fields for an agent, see Custom Fields API.
- Authorization: Requires agent authorization token and permission MANAGE_TEAM_MEMBERS
- Content type: application/json; charset=utf-8
- Accept: application/json
- Response: Agent Object (extended level)
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" } }
Was this article helpful?