Create a Preference

Use the create a preference request to create a new preference, useful for saving a view for another time, or to share with a view the rest of the organization, as mentioned previously a preference lets you save a view determining the metadata fields (columns) shown and in what order, and save a filter for the view to only show conversations matching specified criteria, such as a specific date/time range.

Endpoint

Method: POST

URL:/preference

Request Parameter

Parameter Name	Data Type	Description	Required/Optional
`category`	String	Set the category of the preference, set to `PREFERENCE_CATEGORY_VIEW_STATE`.	Required
`description`	String	Enter a useful description for the preference, at the time of writing this is not used in the UI but will be displayed in get preferences requests.	Optional
`scope`	String	Determine if the preference is shared (set to `ACCESS_SCOPE_PUBLIC`) or private (set to `ACCESS_SCOPE_PRIVATE_AUTOSAVED`). In addition to the standard shared or private scope, U-Capture also provides a scope for the last view that a user has used, for example if they rearrange the columns this can be remembered the next time they open the Recorded page - set `scope` to `ACCESS_SCOPE_PRIVATE_AUTOSAVED` for this view, no `title` is required for autosaved preferences.	Required
`title`	String	Enter a useful name of the preference, this is what a user will see when they pick the preference in the U-Capture application.	Required
`viewState`	Array	Set the details that determine how the preference works, what the view will show, consisting of the following parameters, `fields` and `filter`. `pageSize` and `pageToken` are also configurable however these parameters are not currently used in the UI, see below.	Required
`fields`	Array	List the metadata fields to display as columns in the U-Capture application when using the preference using a comma separated list. Columns in the UI will be displayed from left to right to match the list order (first to last). For a list of valid values at the time of writing see Valid Preference Fields.	Required
`filter`	Array	Set the filter to automatically apply when using the preference - determining which calls are shown, see Filters for more information on filters.	Required
`pageSize`	Number	A Placeholder for future enhancements, at the time of writing this is not used in the UI but will be displayed in get preferences requests.	Optional
`pageToken`	Number	A Placeholder for future enhancements, at the time of writing this is not used in the UI but will be displayed in get preferences requests if a value is entered.	Optional

Valid Preference Fields

The following list includes all of the valid metadata fields for the fields parameter in a create preference request.

agent.department
agent.email
agent.extension
agent.firstName
agent.id
agent.lastname
agent.location
agent.manager
agent.number
agentFullName
callProperties.accountInfo
callProperties.callAudio
callProperties.callDirection
callProperties.callType
callProperties.deviceId
callProperties.endDate
callProperties.group
callProperties.integration
callProperties.licensed
callProperties.licenseStatus
callProperties.localName
callProperties.screenRecordingStatus
callProperties.sipDetails
callProperties.sourceFormat
callProperties.startDate
callProperties.trunkName
conversationId
otherParties
tenantId

Response and Error Code

Response Code	Condition
201	Created

Response Parameter

Parameter Name	Data Type	Description
`id`	Integer	The automatically generated unique ID of the newly created preference.

Sample Request

{
    "category":"PREFERENCE_CATEGORY_VIEW_STATE",
    "description":"A view to only see calls for extension 502",
    "scope":"ACCESS_SCOPE_PRIVATE",
    "title":"See ext502",
    "viewState":{
        "fields":[
            "agentFullName",
            "agent.extension",
            "callProperties.startDate",
            "agent.location",
            "agent.manager",
            "agent.number"
            ],
        "filter":{
            "groupFilter":{
                "leftGroupFilter":{
                    "leftGroupFilter":{
                        "leftFilter":{
                            "fieldName":"agent.extension",
                            "operator":"CONVERSATION_FILTER_OPERATOR_CONTAINS",
                            "stringValue":"502"
                        }
                    }
                },
                "operator":"CONVERSATION_LOGICAL_OPERATOR_AND",
                "rightGroupFilter":{
                    "leftFilter":{
                        "fieldName":"callProperties.startDate",
                        "operator":"CONVERSATION_FILTER_OPERATOR_GREATER_THAN_OR_EQUAL",
                        "timestampValue":"2024-06-17T23:00:00.000Z"
                        },
                    "operator":"CONVERSATION_LOGICAL_OPERATOR_AND",
                    "rightFilter":{
                        "fieldName":"callProperties.endDate",
                        "operator":"CONVERSATION_FILTER_OPERATOR_LESS_THAN_OR_EQUAL",
                        "timestampValue":"2024-09-16T22:59:59.999Z"
                    }
                }
            }
        }
    }
}

Sample Response

{
  "id": "14441"
}

In this section:

Uniphore Customer Portal