System settings

This is part of the Settings API section of the Web Services API.

Overview

The Web Services API provides two types of settings you can access and manipulate:

• System settings — System settings groups and settings are defined by Web Services and can be adjusted by clients through the API.
• Custom settings — Custom settings groups and settings are defined by you to suit the needs of your client application.

Genesys offers the following system settings by default: General settings, Reporting settings, Agent states settings, Voice settings, and Voice operations settings.

General settings

The general-settings group provides read-only access to several key contact center properties:

Setting	Description
countryCode	The country code of the contact center.
countryDigits	The digit used to dial the country.
countryName	The name of the country of the contact center.

Examples

Get general-settings

Request

GET /api/v2/settings/general-settings

Response

{  
   "settings":{  
      "countryCode":"US",
      "countryDigits":"1",
      "countryName":"United States"
   },
   "statusCode":0
}

Reporting settings

The reporting settings group provides a means of tuning the metrics available through the Statistics API:

Setting	Description
defaultServiceLevelInterval	Specifies the maximum time, in seconds, it should take an agent to answer a call. You can get the percentage of answered calls that were under this threshold by using the Statistics API. If you don't explicitly set this setting, Web Services returns the default value from the statistics.yaml file — the value comes from the TimeRangeRight property of the ServiceLevel statistic that's defined for the QUEUE object type. If the corresponding statistic and property is not found, Web Services doesn't consider the defaultServiceLevelInterval threshold property to be set. Note: If you change this setting, it causes Stat Server to calculate a new statistic, resetting statistics.
defaultServicePeriod
defaultTargetServiceLevelPercentage	Use this setting to store or retrieve the value to be used as the default target service level. This setting does not affect the reporting functionality on server side. If you don't explicitly set this setting, the default value is 80. Web Services accepts any integer between 1 and 100 for this setting.

Important

All reporting settings are default settings and can only be updated, not created or deleted.

Examples

Get reporting settings

Request

GET /api/v2/settings/reporting

Response

{  
   "key":"name",
   "settings":[  
      {  
         "name":"defaultTargetServiceLevelPercentage",
         "value":"80"
      },
      {  
         "name":"defaultServicePeriod",
         "value":"60"
      },
      {  
         "name":"defaultServiceLevelInterval",
         "value":"120"
      }
   ],
   "statusCode":0
}

Agent states settings

An agent state operation is a resource that defines the state, workmode, and reason code that should be used when sending a state change to T-Server. Web Services defines a basic set of system agent state operations, but you can also define additional agent state operations. Here are the system-defined agent states included in Web Services (they can't be modified or deleted):

operationName	displayName	state	workMode
Ready	Ready	Ready	-
NotReady	NotReady	NotReady	-
AuxWork	AuxWork	NotReady	AuxWork
AfterCallWork	AfterCallWork	NotReady	AfterCallWork
Offline	Offline	Logout	-

Agent state operations aren't governed by capabilities because you can define custom operations (agent states). You can send any agent state operation at any time, and Web Services and T-Server are generally tolerant of duplicate requests. For example, if you send a request for NotReady and the current user is already in the NotReady state, the request is ignored.

Once a custom agent state operation has been defined, it's returned to the client application when you query the set of available agent state operations (GET api/v2/me/settings/agent-states).

On startup, your client applications should query for the set of available agent state operations and allow the user to choose any of returned options. Each agent state operation also defines a display name that can be used in UI elements. A unique ID is also provided to allow clients to more easily identify a state.

The agent-states resource includes the following attributes:

Field	Description
displayName	The name for the state.
id	The unique ID (GUID) for the agent state. This ID is included in the userState of device change messages when an agent state is matched.
operationName	The unique operation name that is used to set this state (for example, AfterCallWork).
state	The actual T-Server state (Ready/NotReady).
workMode	An after call work mode. Note that modes are applicable to particular states. Ready — ManualIn/AutoIn/ReturnBack NotReady — AfterCallWork/AuxWork/LegalGuard/NoCallDisconnect/WalkAway.
reason	The reason for the agent's state (if specified, it must be unique as it is used as a reason code).

Examples

Get agent states settings

Request

GET /api/v2/settings/agent-states

Response

{  
   "statusCode":0,
   "settings":[  
      {  
         "id":"900D55CC-2BB0-431F-8BF9-D3525B383BE6",
         "operationName":"NotReady",
         "displayName":"Not Ready",
         "state":"NotReady"
      },
      {  
         "id":"0F7F5003-EF26-4D13-A6Ef-D0C7EC819BEB",
         "operationName":"Offline",
         "displayName":"Offline",
         "state":"Logout"
      },
      {  
         "id":"2B36138D-C564-4562-A8CB-3C32D564F296",
         "operationName":"AuxWork",
         "displayName":"AuxWork",
         "state":"NotReady",
         "workMode":"AuxWork"
      },
      {  
         "id":"D3663509-3D82-4DD3-A82E-2EA8EFA02AEF",
         "operationName":"AfterCallWork",
         "displayName":"AfterCallWork",
         "state":"NotReady",
         "workMode":"AfterCallWork"
      },
      {  
         "id":"9430250E-0A1B-421F-B372-F29E69366DED",
         "operationName":"Ready",
         "displayName":"Ready",
         "state":"Ready"
      }
   ],
   "key":"operationName"
}

Voice settings

The voice settings group provides settings related to agents and call activity:

Setting	Description
case-filter	Defines the subset of userData that should be provided in the case property for established calls. See Toast and case data for additional details.
defaultTelephonyNetworkType	The default type is Public, to be used when creating new devices if no telephonyNetworkType is provided in the creation request. Note: This property is a default property and can only be updated, not created or deleted.
defaultWrapupTime	Defines the default amount of time that agents are given between ending a call and the system making them ready for the next call.
outboundCallerId	Sets the number to be used in the caller ID override for outbound calls. This can be used to protect the agent identity and show a corporate number to customers.
toast-filter	Defines the subset of userData that should be provided in the toast property for ringing or dialing calls. See Toast and case data for additional details.

Important

The key for the voice settings group is name.

Examples

Get voice settings

Request

GET /api/v2/settings/voice

Response

{  
   "key":"name",
   "settings":[  
      {  
         "name":"defaultTelephonyNetworkType",
         "value":"Private"
      }
   ],
   "statusCode":0
}

Create a voice setting

Important

Default settings cannot be created or deleted, only updated.

Request

POST /api/v2/settings/voice
{
    "name": "outboundCallerId",
    "value": "18883695555"
}

Response

{  
   "statusCode":0
}

Update a voice setting

Request

PUT /api/v2/settings/voice
{
    "name": "outboundCallerId",
    "value": "18883691212"
}

Response

{  
   "statusCode":0
}

Delete a voice setting

Important

Default settings cannot be created or deleted, only updated.

Request

DELETE /api/v2/settings/voice
{
    "name": "outboundCallerId"
}

Response

{  
   "statusCode":0
}

Voice operations settings

You can use the voice-operations setting group to configure a default set of user attached data to be provided with call-related operations. Currently, default user data is only supported for the Dial operation. User data configured via voice-operations settings is added to any userData provided in the API request to dial the call. If there are duplicate keys between the two, the values provided in the API request are used.

Examples

Create a voice-operations setting

Request

POST /api/v2/settings/voice-operations
{
    "operationName": "Dial",
    "userData": {
        "subscriberId": "1234567890"
    }
}

Response

{  
   "statusCode":0
}

Read a voice-operations settings

Request

GET /api/v2/settings/voice-operations

Response

{  
   "key":"operationName",
   "settings":[  
      {  
         "operationName":"Dial",
         "userData":{  
            "subscriberId":"1234567890"
         }
      }
   ],
   "statusCode":0
}

Update a voice-operations setting

Request

PUT /api/v2/settings/voice-operations
{
    "operationName": "Dial",
    "userData": {
        "subscriberId": "1234567890",
        "region": "EU"
    }
}

Response

{  
   "statusCode":0
}

Delete a voice-operations setting

Request

DELETE /api/v2/settings/voice-operations
{
    "operationName": "Dial"
}

Response

{  
   "statusCode":0
}