This section is for System Administrators and Developers of 3rd party products using Stratus Agent functionality externally .

The API allows to manipulate multiple data entities simultaneously, allowing task automation and external UI interaction with Stratus Agent.

If you are in need of additional support or further applications using the API don’t hesitate to contact us.

(info) Also look at our existing solutions which already make direct use of the API

Scope

In the following we provide a description about the data models and functions used within Stratus Agent and in automated interaction with other applications.

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

Authorization Configuration / API Key

(lightbulb) To allow access the API we generate unique API tokens from within WebConfigurator for you. 

(lightbulb) It's possible to limit single API key access only certain areas via role assignment → See next chapter.

API Roles

Precondition

A Luware System Administrator will generate a key for you and make it accessible to your Organization Units .

After getting an API key you now have access to the roles tab:

API Roles tab

API Methods / Roles

(info) 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.

AreaDescriptionRoles with AccessAPI methods V1.0API methods V2.0
Callbacks

Allows to get or manage Outbound / Callback Task Configuration tasks.

(info) The Callback tasks get shown in:

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 UnitAllows only Organization Units to be read via the API (GET)OU ReadonlyGET​/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.
ServicesAllows Service details to be read via the API (GET)ServiceReadonlyGET​/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
GET ​/v2.0​/services​/count - Retrieve overall count of Services in the system.
GET ​/v2.0​/services​/{serviceIdentifier}​/context - Get list the configured context information for a service
GET ​/v2.0​/services - Get all the existing Services/ContactObjects in the system. Returns data by pages.
GET ​/v2.0​/users​/{userIdentifier}​/services​/conversationas - Get per user the available conversation as services. Returns data by pages.
GET ​/v2.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). Returns data by pages.
TasksAllows 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​/v1.0​/services​/{serviceIdentifier}​/tasks - Retrieves a list of tasks for the specified service
GET​/v1.0​/services​/{serviceIdentifier}​/longestwaitingtask - Retrieves a longest-waiting task for the specified service
POST ​/v1.0​/tasks - Create new task in the system. ReservedUserObject in response is always null.
POST ​/v1.0​/tasks​/{taskIdentifier}​/setestablished - Notify LUCS system that external task is established. Applicable only for the external tasks.
POST ​/v1.0​/tasks​/{taskIdentifier}​/refresh - Reset task to pending and trigger the process to search for agent again. Applicable only for external tasks. Can not be called for tasks if: - task distributed to agent - agent is connected
POST ​/v1.0​/tasks​/outboundCall​/start - Start Outbound Call.
GET​/v1.0​/users​/{userIdentifier}​/tasks 
POST ​/v1.0​/tasks​/{taskIdentifier}​/transfer - Transfer the task. Applicable only for the incoming call tasks.
POST ​/v1.0​/tasks​/{taskIdentifier}​/hold - Put existing task on Hold. Returns TaskStatusData object.
POST ​/v1.0​/tasks​/{taskIdentifier}​/resume - Resume task from Hold state. Returns TaskStatusData object.
POST ​/v1.0​/tasks​/{taskIdentifier}​/terminate - Terminate the task.

GET ​/v2.0​/tasks​/{taskIdentifier} - Get the particular task's data referenced by taskIdentifier.
GET ​/v2.0​/services​/{serviceIdentifier}​/longestwaitingtask - Retrieves a longest-waiting task for the specified service
POST ​/v2.0​/tasks - Create new task in the system. ReservedUserObject in response is always null.
POST ​/v2.0​/tasks​/{taskIdentifier}​/setestablished - Notify LUCS system that external task is established. Applicable only for the external tasks.
POST ​/v2.0​/tasks​/{taskIdentifier}​/refresh - Reset task to pending and trigger the process to search for agent again. Applicable only for external tasks. Can not be called for tasks if: - task distributed to agent - agent is connected
POST ​/v2.0​/tasks​/outboundCall​/start - Start Outbound Call.
GET ​/v2.0​/services​/{serviceIdentifier}​/tasks - Retrieves a list of tasks for the specified service Returns data by pages.
POST ​/v2.0​/users​/{userIdentifier}​/addBlockTask - Adds a "fake" task to the user to block him from other work. Use this method, if the user should be blocked for other work but be reported as "working". User will be blocked until this fake task is removed via API.
GET ​/v2.0​/users​/{userIdentifier}​/tasks
POST ​/v2.0​/tasks​/{taskIdentifier}​/transfer - Transfer the task. Applicable only for the incoming call tasks.
POST ​/v2.0​/tasks​/{taskIdentifier}​/hold - Put existing task on Hold. Returns TaskStatusData object.
POST ​/v2.0​/tasks​/{taskIdentifier}​/resume - Resume task from Hold state. Returns TaskStatusData object.
POST ​/v2.0​/tasks​/{taskIdentifier}​/terminate - Terminate the task.



Tasks: Consultative CallsManage 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 ProvisioningAllows access to user provisioning (GET, POST, DELETE)

UserReadonly

UserProvision

GET​/v1.0​/users​/{userIdentifier}​/roles - Get user's roles via user identifier (case insensitive).
POST ​/v1.0​/users​/{userIdentifier}​/roles - Set/Remove user's roles via user identifier (case insensitive).
GET​/v1.0​/users​/{userIdentifier} - Get a particular user via identifier (case insensitive).
DELETE ​/v1.0​/users​/{userIdentifier} Remove existing user by userIdentifier
GET​/v1.0​/users - Get all users in the system.
POST ​/v1.0​/users - Create new User in the system.
GET​/v1.0​/services​/{serviceIdentifier}​/users - Get existing users for the specified service.
GET​/v1.0​/organizationunits​/{ouIdentifier}​/users - Get users from the particular Organization Unit.
POST ​/v1.0​/users​/{userIdentifier}​/update - Update User in the system.
POST ​/v1.0​/users​/{userIdentifier}​/copy - Create new user based on existing one.

GET ​/v2.0​/users​/{userIdentifier}​/roles - Get user's roles via user identifier (case insensitive).
POST ​/v2.0​/users​/{userIdentifier}​/roles - Set/Remove 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.
POST ​/v2.0​/users - Create new User in the system.
GET ​/v2.0​/users​/{userIdentifier} - Get a particular user via identifier (case insensitive). Traits and Profiles fields are not returned by default. Use fieldsToReturn to implicitly return them.
DELETE ​/v2.0​/users​/{userIdentifier} Remove existing user by userIdentifier
GET ​/v2.0​/organizationunits​/{ouIdentifier}​/users - Get users from the particular Organization Unit. Traits and Profiles fields are not returned by default. Use fieldsToReturn to implicitly return them. Returns data by pages.
GET ​/v2.0​/services​/{serviceIdentifier}​/users - Get existing users for the specified service. Returns data by pages.
POST ​/v2.0​/users​/{userIdentifier}​/update - Update User in the system.
POST ​/v2.0​/users​/{userIdentifier}​/copy - Create new user based on existing one.
POST ​/v2.0​/users​/{userIdentifier}​/applytemplate​/{templateUserIdentifier} - Copy fields, provided by "fieldsToUpdate" from the template user identified by "templateUserId" into User, identified by "userIdentifier".

Users:  Presence / BlockAllows to manage user presence, block / unblock from task distribution (GET, POST) UserControlPOST ​/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.
GET ​/v2.0​/usersStates​/{userIdentifier} - Get a particular user state via identifier (case insensitive).
GET ​/v2.0​/organizationunits​/{ouIdentifier}​/usersStates - Get states of users from the particular Organization Unit. Returns data by pages.
GET ​/v2.0​/services​/{serviceIdentifier}​/usersStates - Get states of users for the specified service. Returns data by pages.
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).
POST /v2.0/users/{userIdentifier}/setActiveProfile → Removes "Absent" state from user. User will once again participate normally in task assignment process.
POST /v2.0/users/{userIdentifier}/setConversationAsService → Removes "Absent" state from user. User will once again participate normally in task assignment process.

Users: Absence

Allows to set or retrieve special "Absence" type Not Ready Reasons (NRR).

(warning) This method only works with Stratus Agent Assistant in conjunction with MS Teams.

UserControl

(info) Not available in API V1.0

GET ​/v2.0​/users​/{userIdentifier}​/getAbsentReasons - Get all available absence reasons for agent
POST ​/v2.0​/users​/{userIdentifier}​/setAbsent - Blocks user from work. Reports user as "NotReady"/absent with provided NotReadyReason, which means, he's considered not "working". This state persist until either it is removed via API, the user ends the "Absent" period through Agent Assistant or AM is restarted.
POST ​/v2.0​/users​/{userIdentifier}​/unsetAbsent - Removes "Absent" state from user. User will once again participate normally in task assignment process.

Usage

Agents using Agent Assistant can "block" themselves from work by selecting a NRR.

(warning) POST /v1.0/users/{userIdentifier}/block  is not suitable as alternative here, because it creates a "fake" task for the user which reports the agent as "working" while being blocked.

Three new methods are available for this:

  • GET /v2.0/users/{userIdentifier}/getAbsentReasons - Returns all visible NRRs for this user ("Id" and "Name")
  • POST /v2.0/users/{userIdentifier}/setAbsent - (lightbulb) A Valid NRR for the User has to be presented (either "Id" or "Name"). Blocks user from work.
  • POST /v2.0/users/{userIdentifier}/unsetAbsent - Removes the "Absent" state from a user. The User will once again participate normally in task assignment process.

Results:

→ Using these methods reports user as "NotReady" / absent with a provided NotReadyReason. The user is considered as "not working" in  Historic Reporting.
→ The state persist until either removed via API, the user ends the "Absent" period through Agent Assistant.

  • 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 Stratus Agent 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.

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

(tick) To get access to the Luware API URL, please get in contact with support

(lightbulb) Note : Stratus Agent uses the same API as our LUCS On-Prem 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." }