The Users API is part of Voiso's User Management APIs. Use it to obtain a list of all agent names and IDs.
Please refer to the detailed API endpoint specification: Get users
Note: The request, response, and authentication for this endpoint have been completely updated as of October 9, 2024. Please ensure that you update any customizations that use this endpoint.
Making requests
Authentication
The users API requires the Base URL and the contact center API key.
Request parameters
The users API uses the contact center API key as a bearer token for the request.
Simple REST request example:
{
"method": "GET",
"url": "https://cluster1.voiso.com/user_management/v1/users",
"headers": {
"Authorization": "Bearer ad-9433j0s...9rrk63",
"Accept": "application/json"
}
}
The users API also enables you to apply filters to the GET request. The following filters are supported:
| Parameter | Description | Type | Required | Notes |
|---|---|---|---|---|
| id | The Contact Center ID of the user. | number | Optional | Get only information for the specified user. |
| name | The name of the user. | string | Optional | Get only information for the specified user. |
| The email address of the user. | string | Optional | Get only information for the user based on the specified sign-in email address. | |
| sip_account | The SIP server address for the user's WebRTC Softphone. | string | Optional | Get only information for the user based on the specified SIP server address. |
| sag | The user's role. | string | Optional | Get only information for the users who are assigned to the specified security access group. |
| extension | The WebRTC extension of the user. | string | Optional | Get only information for the user based on the specified contact center extension. |
| caller_id | The Caller ID group of the user. | string | Optional | Get only information for the users who are assigned to the specified caller ID group. |
| timezone | The time zone of the user. | string | Optional | Get only information for the users who are assigned to the specified time zone. |
Full request example:
{
"method": "GET",
"url": "https://cluster1.voiso.com/api/user_management/v1/users",
"headers": {
"Authorization": "Bearer ad-9433j0s...9rrk63",
"Accept": "application/json"
},
"params": {
"id": "<integer>",
"name": "<string>",
"email": "<string>",
"sip_account": "<string>",
"sag": "<string>",
"extension": "<string>",
"caller_id": "<string>",
"timezone": "<string>"
}
}
Response
The following table describes the elements of the response.
| Element | Description | Type | Notes |
|---|---|---|---|
| id | The ID assigned by the system when the user is created. | number | |
| name | The name of the user, corresponding to the Name field in the User profile. | string | |
| The email address the agent uses to sign in to Voiso. | string | ||
| sip_account | The SIP address of the user's softphone. | string | |
| sag | The name of the Security Access Group to which the user is assigned. | string | |
| extension | The contact center extension used to route calls to the user. | string | |
| caller_id | The name of the caller ID group to which the user is assigned. | string | |
| timezone | The name of the time zone selected for the user. | string | |
| webrtc_ringtone | The name of the ringtone assigned to the user. | string | |
| assigned_teams | A comma-separated list of the IDs of the Teams to which the user is assigned. | string | Use the Teams API to obtain the team IDs. |
| supervisor_in_teams | A comma-separated list of the IDs of the Teams that the user supervises. | string | Use the Teams API to obtain the team IDs. |
| assigned_skills | An object containing an array of the names of the skills and the assigned skill level. | object | |
| assigned_channels | An object containing an array of the names of the digital channels assigned to the user. | object | |
| assigned_queues | A comma-separated list of queue names. | string | |
| employee_id | The value assigned to the user in the Employee ID field of the user profile. | string |
Assigned skills array
| Parameter | Description | Type | Notes |
|---|---|---|---|
| name | The name of the skill | string | |
| value | The skill level | number | An integer from 1 to 10, where 10 is the highest skill level. |
Assigned channels array
| Parameter | Description | Type | Notes |
|---|---|---|---|
| type | Digital channel type | string | One of the supported Digital channel types. |
| name | The name of the channel. | string | When digital channels are added to a contact center, they are assigned unique names so that two channels of the same type may be discriminated. |
| value | Phone number associated with the channel | number | Not all digital channels are associated with a phone number. The phone number is in E.164 format without the initial '+' symbol. |
Response sample
{
"summary": "Agents parameters",
"description": "All of the user data",
"value": {
"id": 28982,
"name": "AG D",
"email": "[email protected]",
"sip_account": "[email protected]",
"sag": "Agent",
"extension": "2594",
"caller_id": "378",
"timezone": "Istanbul",
"webrtc_ringtone": null,
"assigned_teams": "3623, 2481",
"supervisor_in_teams": "Support, Team3",
"assigned_skills": [
{
"name": "Skill1",
"value": 4
},
{
"name": "Skill2",
"value": 3
},
{
"name": "Skill3",
"value": 5
}
],
"assigned_queues": "AG Queue",
"employee_id": 123,
"assigned_channels": [
{
"type": "WhatsApp",
"name": "WhatsApp Support 1",
"value": 1234567890
},
{
"type": "Webchat",
"name": "Webchat Support",
"value": 9876543210
},
{
"type": "Viber",
"name": "Viber Support",
"value": 1122334455
}
]
}
}
Troubleshooting
The following issues are sometimes encountered:
Invalid User API Key
The users API requires the user API key to validate the request. If you see this error, "error": "Invalid User API Key", check that you use the correct user API key. For more information about API keys, refer to Authentication.