LUCS API
In the following we provide a description about the data models and functions used within LUCS and in automated interaction with other applications. Separate API Use Cases will explain how to apply those concepts in specific scenarios.
The Luware API allows customers to manage external system tasks in their own systems and block specific agents. The new Luware API component is divided into the following three parts to support three different usage areas:
- Provisioning API: Configure and provision users and services in the system
- Reporting API: Get system information and reporting data
- Control API: Add and manage callback and external system tasks
Target audience
This Document is written for System Administrators and Developers of 3rd party products using LUCS functionality externally . If you are in need of additional support or want to provide feedback, don’t hesitate to contact us.
Preconditions & System Requirements
LUCS needs to be installed and fully configured respectively using the API. Please refer to the "Precondition" Documents of your respective Luware Product and Version.
API and Luware Version compatibility
The API functionality described in this documentation is only supported for LUCS Versions 3.1 or newer.
Version mismatches between LUCS base components and the installed API can lead to erratic system behavior, errors and potential loss of database content!
→ Make sure to only install the corresponding API setup matching and delivered alongside your Luware product.
API Checklist - Before you start
- LUCS and API Component is installed →
See chapter below and API - Advanced Programming Interface
- AC, AM, CI and CIC Services must be running as well in order to operate the system overall →
See Architecture
- IIS is running to operate the Web FrontEnd User Interface
- AC, AM, CI and CIC Services must be running as well in order to operate the system overall →
- Check in "Home" Tab in LUCS Configurator or Web Configurator and check if the API service is running.
- Generate a new API Key →
See chapter below
- Configure Access rights for the key →
See chapter below
If malfunctions occur after setting changes (e.g. in the API Component, Network Ports or IIS) a quick restart of API Services is recommended.
Ensure that the API port used is also exempt from any Anti-Virus and Firewall tools
API Ports
Since the LUCS API uses the functionality of LUCS, ports need to be forwarded.
Source | Destination | Protocol | Destination Server Port (Default) | Comment |
---|---|---|---|---|
Agent PC (LUCS-API) | LUCS Server 01 | TCP | 4444 | LUCS Web API |
Agent PC (LUCS-API) | LUCS Server 02 | TCP | 4444 | LUCS Web API |
Server | LUCS Server 01 | TCP | 19413 | How How Luware-API connects to other Luware components through WCF channel |
Installation
When installing the API as individual setup (e.g. on a Client PC), the port and server instance can be individually configured during setup.
For an external use of the API, consider that outgoing ports need to be forwarded as well.
Authorization Configuration / API Key
Luware API is an active – active component and may be installed on any machine that has IIS configured. To allow access the API you need to generate unique API tokens from within WebConfigurator.
Open Settings -> Topology -> Authentication Tokens
Click "Add" and name / describe your token as needed
API Key configurationOptionally you can set an expiry date for the token.
- The API should now be ready to use. Check in "Home" Tab if the API service is running.
If malfunctions occur after setting changes (e.g. in the API Component, Ports or IIS) a quick restart of API Services is recommended.
API Rate limits
By default an API key can be used without rate limits. If your LUCS API is extensively used (maybe imposing huge load on your servers) you might configure optional burst and rate limits in a defined time period.
Examples :
- Rate Limit (x per minute/hour): If a customer makes 1000 calls, they cannot complete any more calls until the hour has expired.
- Burst Limit (y per second): A rate limit that is applied over a small time period (second). Once that pause is over, calls continue to be accepted, e.g. until the rate limit is reached.
Use Case: Configuring a burst limit prevents usage spikes and ensures that the rate limit is evenly spread across its overall time period. For example, you might want to permit a total of 1000 calls per hour (rate limit) and a maximum spike of 50 calls per second (burst limit).
What are the effects? Users of that API key will see a "Too many requests" return code until the rate / burst time period has passed.
Note: Rejections by rate limits are not queued by the API nor stored by LUCS for later processing. They must be handled / repeated by the system that makes the request.
API Roles
Starting with LUCS 3.3 it's now possible to limit single API key access only certain areas via role assignment.
Precondition
You need System Administrator or at least the "Topology" Permission given to your account via Role Based Access - RBAC to use this feature. Otherwise you will only be able to inspect API keys or not see the entry at all.
After generating a new API key entry you now have access to the roles tab:
API Methods / Roles
POST / GET / DELETE methods are limited by API Roles (see above). An "unauthorized" error 401 is thrown when the API key is wrong or role permissions are insufficient.
Area | Description | Roles with Access | API methods V1.0 | API methods V2.0 |
---|---|---|---|---|
Callbacks | Allows to get or manage Outbound / Callback Task Configuration tasks.
| TasksManage | POST /v1.0/callbacks - Creates a new callback request GET /v1.0/callbacks/{callbacksIdentifier} - Get callback using callbackId or using ExternalTaskId that provided on creation request POST /v1.0/callbacks/{callbacksIdentifier}/cancel - Cancel the Callback using callbackId or ExternalTaskId POST /v1.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria. Post the empty object "{}" to get all of them. | POST /v2.0/callbacks - Creates a new callback request GET /v2.0/callbacks/{callbacksIdentifier} - Get callback using callbackId or using ExternalTaskId that provided on creation request POST /v2.0/callbacks/{callbacksIdentifier}/cancel - Cancel the Callback using callbackId or ExternalTaskId POST /v2.0/callbacks/search - Flexible API to search through the Callbacks in the system by different criteria. Post the empty object "{}" to get all of them. |
Organization Unit | Allows only Organization Units to be read via the API (GET) | OU Readonly | GET/v1.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit GET/v1.0/organizationunits - Get all OrganizationUnits in the system. Flat structure with ParentId, if defined. Services | GET /v2.0/organizationunits/{ouIdentifier} - Get details of the particular OrganizationUnit GET /v2.0/organizationunits - Get all OrganizationUnits in the system. Flat structure with ParentId, if defined. |
Services | Allows Service details to be read via the API (GET) | ServiceReadonly | GET/v1.0/services - Get all the existing Services/ContactObjects in the system. GET/v1.0/services/{serviceIdentifier} - Get particular service by its identifier or SIP URI GET/v1.0/organizationunits/{ouIdentifier}/services - Search services in a specific OrganizationUnit. Search from the Top Unit, defined by ouIdentifier and down through its tree (in all child units). GET/v1.0/services/count - Retrieve overall count of Services in the system. GET/v1.0/users/{userIdentifier}/services/conversationas - Get per user the available conversation as services. GET/v1.0/services/{serviceIdentifier}/context - Get list the configured context information for a service | GET /v2.0/services/{serviceIdentifier} - Get particular service by its identifier or SIP URI |
Tasks | Allows to fully manage and manipulate tasks in the system. (GET, POST) | TasksReadonly TasksManage | GET/v1.0/tasks/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier. | GET /v2.0/tasks/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier. |
Tasks: Consultative Calls | Manage consultative calls (GET, POST) | TaskReadonly TasksManage | POST /v1.0/tasks/{taskIdentifier}/consultationCall - Make a new consult call Applicable only for the incoming call tasks. GET/v1.0/tasks/{taskIdentifier}/consultationCall - Get consultation call status POST /v1.0/tasks/{taskIdentifier}/consultationCall/merge - Merge the consultation call with the customer Applicable only for the incoming call tasks. POST /v1.0/tasks/{taskIdentifier}/consultationCall/transfer - Transfer the consultation call with the customer Applicable only for the incoming call tasks. POST /v1.0/tasks/{taskIdentifier}/consultationCall/terminate - Terminate consultation call POST /v1.0/tasks/{taskIdentifier}/consultationCall/leave - Terminate consultation call POST /v1.0/tasks/{taskIdentifier}/consultationCall/audioRoutes - Set audio routes for merged consultation call Applicable only for the incoming call tasks. POST /v1.0/tasks/{taskIdentifier}/consultationCall/terminateCustomerCall - Terminate customer call during the consultation call Applicable only for the incoming call tasks. GET/v1.0/users/{userIdentifier}/consultativeCalls - Get user's' consultative calls | POST /v2.0/tasks/{taskIdentifier}/consultationCall - Make a new consult call Applicable only for the incoming call tasks. GET /v2.0/tasks/{taskIdentifier}/consultationCall - Get consultation call status POST /v2.0/tasks/{taskIdentifier}/consultationCall/merge - Merge the consultation call with the customer Applicable only for the incoming call tasks. POST /v2.0/tasks/{taskIdentifier}/consultationCall/transfer - Transfer the consultation call with the customer Applicable only for the incoming call tasks. POST /v2.0/tasks/{taskIdentifier}/consultationCall/terminate - Terminate consultation call POST /v2.0/tasks/{taskIdentifier}/consultationCall/leave - Terminate consultation call POST /v2.0/tasks/{taskIdentifier}/consultationCall/audioRoutes - Set audio routes for merged consultation call Applicable only for the incoming call tasks. POST /v2.0/tasks/{taskIdentifier}/consultationCall/terminateCustomerCall - Terminate customer call during the consultation call Applicable only for the incoming call tasks. GET /v2.0/users/{userIdentifier}/consultativeCalls - Get user's' consultative calls |
User Provisioning | Allows access to user provisioning (GET, POST, DELETE) | UserReadonly UserProvision | GET/v1.0/users/{userIdentifier}/roles - Get user's roles via user identifier (case insensitive). | GET /v2.0/users/{userIdentifier}/roles - Get user's roles via user identifier (case insensitive). GET /v2.0/profiles → Returns all configured responsibility profiles (ID, Name, OffDuty-Flag) GET /v2.0/users - Get all users in the system. Traits and Profiles fields are not returned by default. Use fieldsToReturn to implicitly return them. Returns data by pages. |
Users: Presence / Block | Allows to manage user presence, block / unblock from task distribution (GET, POST) | UserControl | POST /v1.0/users/{userIdentifier}/block - Block the defined agent. So, agent won't be selectable for the tasks assignment until someone call Unblock or system (AM) restarted. POST /v1.0/users/{userIdentifier}/unblock - Unblock a previously blocked agent. Unblocked agent can participate in a tasks assignment process. POST /v1.0/users/{userIdentifier}/applytemplate/{templateUserIdentifier} - Copy fields, provided by "fieldsToUpdate" from the template user identified by "templateUserId" into User, identified by "userIdentifier". POST /v1.0/users/{userIdentifier}/setpresence - Sets the particular presence for the specified Agent (so, external system can maintain presence state of the LUCS agents). | GET /v2.0/usersStates - Get states of all users in the system. Returns data by pages. Differences between "users" and "userstates" methods
POST /v2.0/users/{userIdentifier}/setpresence - Sets the particular presence for the specified Agent (so, external system can maintain presence state of the LUCS agents). |
Users: Absence | Allows to set or retrieve special "Absence" type Not Ready Reasons (NRR). | UserControl |
| GET /v2.0/users/{userIdentifier}/getAbsentReasons - Get all available absence reasons for agent Agent Self-Block via NRR This method only works with Stratus Agent Assistant in conjunction with MS Teams. |
Notes
- For a full list on API command functionality regarding Tasks, Callbacks, OU, Services and User management, refer to our → API Swagger documentation (see below)
- Existing API-Keys from previous LUCS installations will be given full access by default to avoid access conflicts. You can edit them to narrow down the permissions to the needed amount.
- Task Expiry: The API - Advanced Programming Interface has a setting "MaximumPollingTimeoutInMin". If no polling happened during this timeframe the task gets disposed, because it seems "abandoned").
- Overall maximum lifetime for a task is 5 days. If you want to keep it in the system you need to make a refresh request via API to let the system know you still "care" about this task.
API Usage / Endpoints / Swagger
The following content below is embedded from our Live-API documentation (Swagger UI). It is not connected to a host for command execution and only acts as reference. Alternatively you can use these links to open the Swagger viewer directly V1.0 | V2.0 .
The URL for API access depends on your server address. Refer to Essential Topology Settings to determine where your API component was installed.
Note : LUCS uses the same API as our Stratus Cloud products, so mentions of either name are to be expected.
API related errors
The API returns default → HTML Error status codes. The most common one is not passing the api_key along with a request:
During all HTTP Requests the generated API Key has to be included in the HTTP Header. Otherwise an error will be thrown:
"Error" : { "Code" : "Unauthorized" , "Message" : "Header 'api_key' not found." } The info below is left as legacy API documentation content. Newest API definitions can be found in our Swagger UI documentation above.
In this section: