Download PDF
Download page Session API.
Session API
Introduction
Session management describes the API requests needed to manage LiveVox API sessions, including logging into the LiveVox platform to create a new session, logging out an active session, listing active sessions, and getting details of an active session.
The Session API has two separate methods that allow either LiveVox Users or Agents to log in and create a new session. This allows API consumers to build a variety of applications that can accept either LiveVox Agent credentials or LiveVox User credentials and generate a Session ID. The API methods that can then be used with that Session ID will depend on whether the session was generated by an Agent or a LiveVox User. If it was generated by a LiveVox User, the User's security role will impact what API methods can be accessed with that Session ID. See the documentation of each API and API method, where this information is described.
For a general overview of the LiveVox APIs, include security aspects, see the LiveVox API Overview.
Prerequisites
- The user must have an active subscription to the Session API, in order to obtain an Access Token for use in all API requests. See Access Tokens for details.
- All messages in this API may be subject to rate limits and other restrictions.
Session API WADL/Swagger
The Session API WADL/Swagger is publicly available; to obtain the WADL/Swagger for any other API category a user will need to include the LV-Session header with a valid session ID in the WADL/Swagger request.
The Session API v19.0 WADL/Swagger is available at the following URL:
The URLs listed below are for the LiveVox NA3 environment and will change slightly if your portal is in a different environment. To know how the URL changes per environment, see the LiveVox Environments and APIs section.
| Session API Resource | Link |
|---|---|
| Session WADL | |
| Session Swagger |
LV-Session Header
Other than the login, IsSessionValid, ChangePassowrd, and Logout requests, all other requests to the Session API, as well as all requests to all other LiveVox APIs, require that a Session ID be passed in with the request, in an HTTP Header. The Header field name is LV-Session and the value will simply be the sessionId. For example:
LV-Session: 38de9bcc-7425-4392-b821-99026632c369
Session Expiration
The session expiration is based on its usage. As long as a session is used once in a 2-hour rolling window, it will remain valid. The only exception to this is when the user's / agent's password expires or changes, at which point the user/agent will need to log in again using their new credentials and obtain a new session.
Multiple requests to log in using the same token, username, and password return the same valid session ID.
User Roles
The login request and Change Password request may be used by a LiveVox User or Agent. For all of the other requests, the user making the request must be a LiveVox User belonging to either the Sysadmin or Superuser role.
API Methods
Session Management
Change Password
Description: Allows a LiveVox User or Agent to change their password.
Method: POST session/password
Parameters:
None
Body:
| Key or Attribute | Type | Mandatory? | Description |
|---|---|---|---|
| clientName | String | Yes | Name of LiveVox Client to which the User or Agent belongs. |
| userName | String | Yes | Name of the LiveVox User or Agent who wants to change his password. |
| password | String | Yes | Current password of the LiveVox User or Agent. |
| newPassword | String | Yes | New password of the LiveVox User or Agent. The password must comply with the same rules as when a LiveVox User or Agent is created or updated through the LVP GUI. Specifically, the password must be a minimum of 8 characters, containing at least 1 digit and cannot match any of the previous 4 passwords for the User or Agent. |
| agent | Boolean | No | If set to If not included in the request it defaults to 'false' meaning that the password change is for a User. |
Response Code: 204 No Content
Body:
None
Change the password of a LiveVox User
#Request (JSON)
POST /session/password
Host: localhost.com
Content-Type: application/json
Accept: application/json
{"clientName": "ACME",
"userName": "john_doe",
"password": "odPaSSW0rd",
"newPassword": "newPaSSW0rd"}
#Response (JSON)
204 No Content
Change the password of an Agent
#Request (JSON)
POST /session/password
Host: localhost.com
Content-Type: application/json
Accept: application/json
{"clientName": "ACME",
"userName": "john_doe",
"password": "odPaSSW0rd",
"newPassword": "newPaSSW0rd",
"agent": "true"}
#Response (JSON)
204 No Content
Is Session Valid
Description: Checks if a session is still valid.
Method: GET /session/validate/{session}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory | Description |
|---|---|---|---|---|
| session | sessionId | String | Yes | ID of the session you want to check. |
Body:
None
Response Code: 204 No Content or 404 Not Found
Method will return a '204 No Content' if the session is still valid, while an invalid session will return a '404 Not Found'.
Body:
None
Session is still valid
#Request (JSON)
GET /session/validate/a3104123-de21-4b74-8efc-8771fa4c8455
Host: www.livevox.com
Content-Type: application/json
Accept: application/json
#Response (JSON)
204 No Content
Session is no longer valid
#Request (JSON)
GET /session/validate/a3104123-d233-4b74-8efc-8771fa4c8455
Host: www.livevox.com
Content-Type: application/json
Accept: application/json
#Response (JSON)
404 Not Found
Login
Description: Logs a User or Agent into the LiveVox platform to create a Session ID which must be used in subsequent API requests.
Session permissions are updated every 5 min. This means that when you add/remove a Service to a User/Agent or add/remove an Agent Skill to a User/Agent etc. you'll either have to wait 5 min for those new permissions to take effect or create a new session id.
How to Use the Session:
Using a Session in the APIs (ex: Getting a List of Agents)
#Request (JSON)
GET /configuration/agents?count=5&client=4199&offset=0
Host: localhost.com
Content-Type: application/json
Accept: application/json
LV-Session: 3d408e7b-8afd-4f3a-8973-a7bc1a4deefd
LV-Access: 862ba646fa22352838xcg8b54939e
#Response
200 OK
Content-Type: application/json
{
"agent": [
{
"id": 17243,
"loginId": "ABC2323",
"firstName": "DEVLIN",
"lastName": "MCDOUGAL",
"phone": "6786486419",
"active": true
},
{
"id": 21211,
"loginId": "CJL1111",
"firstName": "CHRISTINE",
"lastName": "LAJOIE",
"phone": "6178498808",
"active": true
},
{
"id": 21751,
"loginId": "ARTHUR2",
"firstName": "ARTHUR",
"lastName": "MADDOX",
"phone": "6142093064",
"active": false
},
{
"id": 22131,
"loginId": "JFC1222",
"firstName": "JENNIFER",
"lastName": "CESPEDES",
"phone": "4803190744",
"active": true
},
{
"id": 23017,
"loginId": "TMP_CAVALRY",
"firstName": "TODD",
"lastName": "PHILLIPS",
"phone": "9255954457",
"active": true
}
],
"next": "configuration/agents?count=5&client=4199&offset=5"
}
This is different than the Logon method of the LiveVox ACD API, which is specifically to log on Agent onto the LiveVox ACD. The login method of the Session API is to allow you to build an application that accepts Agent credentials and is then able to make use of a variety of other LiveVox API methods outside of the ACD API. For example, you may want to incorporate some compliance features into a custom agent desktop, for which you want to make use of the Is Blocked method of the LiveVox Compliance API. You would first use this login request to generate a Session ID on behalf of the Agent who has authenticated with your agent desktop, and you could then use that Session ID to make the Is Blocked request.
Method: POST session/login
Parameters:
None
Body:
| Key or Attribute | Type | Mandatory? | Description |
|---|---|---|---|
| clientName | String | Yes | Name of LiveVox Client on whose behalf the session is being created. This is not the "Display Name" of the Client, but rather the "Client Code" as it appears in the Client Editor screen in the LiveVox Portal GUI. |
| userName | String | Yes | Name of LiveVox user or Agent on whose behalf the session is being created. An Agents 'userName' is case insensitive while a Users 'userName' is case sensitive. |
| password | String | Yes | Password associated with the Username |
| agent | Boolean | No | If set to If not included in the request it defaults to 'false' meaning that the login request is for a User. |
Response Code: 200 OK
Body:
| Key or Attribute | Type | Mandatory? | Description |
|---|---|---|---|
| sessionId | String | Yes | LiveVox Session ID to be used in subsequent API requests. |
| clientId | Integer (ID) | Yes | The ID of the Client corresponding to the clientName provided in the login request. |
| userId | Integer (ID) | Yes | The internal ID of the LiveVox User or Agent corresponding to the userName provided in the login request. |
| daysUntilPasswordExpires | Integer | No | The number of days until the User or Agents' password expires. |
- If the session was not successfully created, then an error will be returned. See Errors for more information.
- If the LV User/Agent's account is locked out for any reason (for example, if he has surpassed the allowable number of invalid login attempts), the user/agent will be informed in the response that the account is locked.
- If the LV User/Agent's password has expired, the user/agent will be informed in the response.
Create a new LV API session for a LV User
#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json
{"clientName": "CAVALRY",
"userName": "API12",
"password": "livevox1"}
#Response (JSON)
200 OK
Content-Type: application/json
{
"sessionId": "95d895a9-7a84-4270-9ec8-8a5c9388625e",
"userId": 119570,
"clientId": 4199,
"daysUntilPasswordExpires": 111
}
Create a new LV API session for an Agent
#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json
{"clientName": "CAVALRY",
"userName": "API12",
"password": "livevox1",
"agent": "true"}
#Response (JSON)
200 OK
Content-Type: application/json
{
"sessionId": "3d408e7b-8afd-4f3a-8973-a7bc1a4deefd",
"userId": 363545,
"clientId": 4199,
"daysUntilPasswordExpires": 10
}
Incorrect clientName or userName
#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json
{"clientName": "Demo",
"userName": "API4231",
"password": "livevox13254",
"agent": "true"}
#Response (JSON)
404 Not Found
Content-Type: application/json
Incorrect Password
#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json
{"clientName": "CAVALRY",
"userName": "API1",
"password": "livevox1234",
"agent": "true"}
#Response (JSON)
403 Forbidden
Content-Type: application/json
{
"code": 400,
"message": "Invalid Password"
}
Password has Expired
#Request (JSON)
POST /session/login
Host: localhost.com
Content-Type: application/json
Accept: application/json
{"clientName": "CAVALRY",
"userName": "API1",
"password": "livevox1234",
"agent": "true"}
#Response (JSON)
403 Forbidden
Content-Type: application/json
{
"code": 400,
"message": "Stale Password"
}
Logout
Description: Logs out a particular session ID, thus ending that session.
Method: DELETE /session/logout/{session}
Parameters:
| Path/Query Parameter Name | Variable Name | Type | Mandatory? | Description |
|---|---|---|---|---|
| session | sessionId | String | Yes | LiveVox API session ID that you want to log out |
Body:
None
Response Code: 204 No Content
Body:
None
Close an open LV API session
#Request
DELETE /session/logout/a3104123-de21-4b74-8efc-8771fa4c8455
Host: localhost.com
Content-Type: application/json
Accept: application/json
#Response
204 No Content
Errors
For more information, see the Errors section on the REST APIs page.