Revision as of 03:27, March 11, 2017 by Sschlich (talk | contribs) (→‎Getting a specific label from a recording)
Jump to: navigation, search

Recording Label API

ENTIRE PAGE IS NEW

Source: https://intranet.genesys.com/display/RP/Summary+of+Label+APIs+to+be+documented

Prerequisites

  • Configure Elasticsearch schema v2 in Interaction Recording Web Services, to enable it to use labels and non-deletion features.
  • For existing deployments, follow the migration steps here: Migrating an Existing Elasticsearch Deployment to Schema V2.
  • New deployments after GIR version 8.5.2xx.xx (TBD) will have Elasticsearch schema v2 enabled by default.

Permissions

Specific permissions support the ability to tag or untag recordings for non-deletion. See: Configuring Permissions for Recording Labels.

Overview

Use this API to create and administer label definitions and label recordings.

  • A Label Definition provides the basic definition of a label: a name, a displayName, and a description.
  • A Label can then be added to a voice recording by referring to the name of the label definition.

Access this API and its Operations at the base path /api/v2. For example:
   http://localhost:8080/api/v2/recording_label_definitions

Creating label definitions

Request URL /recording-label-definitions/
HTTP Method POST
Required Roles
  • Admin (no permissions required)
  • Supervisor
  • Agent
Required Permissions RECORDING_PERMISSION_ADD_LABEL_DEFINITION

Note: Create the label definition, if it does not already exist.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
name String yes N/A The name of the label definition
  • Is case-sensitive
  • Must only contain ASCII characters
  • Must be unique among other label definitions
  • Must not start with two underscores("__") as it is reserved
displayName String no defaults to the value of name The display name of the label definition
description String no empty string The description of the label definition


Example

{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }


Response

HTTP Status
Status Codes Situations
201 CREATED The label definition was created successfully
400 BAD REQUEST Bad Request received
403 FORBIDDEN Forbidden to create the label definition
409 CONFLICT The label definition was not created as one with the same name exists already


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer yes 0 N/A label definition was created
1 (RequiredParameterMissing) The required payload attributes are missing.
2 (InvalidRequestParameter) The constraints of payload attributes are not met.
3 (OperationForbidden) The requesting user does not have the permissions required or is attempting to create with reserved name.
18 (ResourceAlreadyExists) A label definition with the same name exists already.
20 (unauthenticated) The requesting user is ops.
statusMessage String no
  • not specified;
  • a message providing information
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition JSON object no JSON object containing the label definition
  • path (string): The path to the resource
  • name (string): The name of the label definition
  • displayName (string, optional): The display name of the label definition
  • description (string, optional): The description of the label definition
 N/A The newly created label definition or existing one in case of an attempt to create an already existing one.

Examples

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "New Label Definition",
		"description": "A new label definition"
	}
}
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
{
	"statusCode": 18,
	"statusMessage": "Resource exists already."
	"labelDefinition": {
		"path": "/recording-label-definitions/a6a6f1d9-788a-47b4-bdeb-80b3d598cfa6",
		"name": "ExistingLabelDefinition",
		"displayName": "Existing Label Definition."
		"description": "An existing label definition"
	}
}

Updating label definitions

Request URL /recording-label-definitions/{labelDefinitionId}
HTTP Method PUT
Required Roles
  • Admin (permissions not required)
  • Supervisor
  • Agent
Required Permissions RECORDING_PERMISSION_ADD_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
name String yes N/A The name of the label definition
  • Name cannot be updated—must be specified to the same value as the existing name.
displayName String no Default to the value of name if not specified The display name of the label definition
description String no empty string The description of the label definition

Example

{
        "name": "SomeLabelDefinition",
        "displayName": "New Label Definition",
        "description": "A new label definition"
 }


Response

HTTP Status
Status Codes Situations
200 OK The label definition was updated successfully.
400 BAD REQUEST Bad Request received.
403 FORBIDDEN Forbidden to update the label definition.
404 NOT FOUND Cannot find the label definition to update.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer yes 0 N/A label definition was updated
1 (RequiredParameterMissing) The required payload attributes are missing.
2 (InvalidRequestParameter) The constraints of payload attributes are not met.
3 (OperationForbidden) The requesting user does not have the permissions required or is attempting to update with different name.
6 (ResourceNotFound) The specified label definition cannot be found.
20 (Unauthenticated) The requesting user is ops.
statusMessage String no
  • not specified;
  • a message providing information
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.
labelDefinition JSON object yes
  • name (string): The name of the label definition
  • displayName (string, optional): The display name of the label definition
  • description (string, optional): The description of the label definition
  • path (string, optional): The path of the label definition
 N/A

Examples

{
	"statusCode": 0,
	"labelDefinition": {
		"path": "/recording-label-definitions/2365adc7-67bb-448e-b32d-04731faa9231",
		"name": "SomeLabelDefinition",
		"displayName": "Updated Label Definition",
		"description": "An updated label definition"
	}
}
 
{
	"statusCode": 2,
	"statusMessage": "Invalid value specified."
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

{
	"statusCode": 20,
	"statusMessage": "Access denied."
}

Deleting label definitions

Request URL /recording-label-definitions/{labelDefinitionId}
HTTP Method DELETE
Required Roles
  • Admin (permissions not required)
  • Supervisor
  • Agent
Required Permissions RECORDING_PERMISSION_DELETE_LABEL_DEFINITION

Note: You can use the path attribute from the response returned by the GET or POST operations for label definition.


Why no PAYLOAD table here? Because a deletion request doesn't have a payload?


Response

Status Codes
HTTP Status
Situations Notes
200 OK The label definition was deleted successfully.
403 FORBIDDEN Forbidden to delete the label definition.
404 NOT FOUND Cannot find the label definition to delete.


Payload
Attributes JSON Data Type Mandatory Possible Values Default Value Situations Notes
statusCode Integer yes 0 N/A The label definition was deleted.
3 (OperationForbidden) The requesting user does not have the permissions required.
6 (ResourceNotFound) The specified label definition cannot be found.
20 (Unauthorized) The requesting user is ops.
statusMessage String no
  • not specified;
  • a message providing information
 N/A The statusMessage will provide more information about a failure if statusCode is not 0.

Examples

{
	"statusCode": 0
}
 
{
	"statusCode": 3,
	"statusMessage": "This operation is not allowed."
}
 
{
	"statusCode": 5,
	"statusMessage": "Access denied."
}
 
{
	"statusCode": 6,
	"statusMessage": "Custom label definition cannot be found."
}

Retrieving label definitions

Request URL xxxxxxxxx
HTTP Method xxxxxxxxx
Required Roles
  • Admin (permissions not required)
  • Supervisor
  • Agent
Required Permissions xxxxxxxxx

Note: xxxxxxxxxx

Method Path Required Roles Required Permissions Notes
GET /recording-label-definitions
  • CC Admin
  • Supervisor
  • Agent
 N/A Returns all the label definitions.


Parameters Payload?
Attributes JSON Data Type Mandatory Possible Values Default Value Description Notes
fields comma-separated string of fields no
  • name

displayName
description

N/A The fields to be returned from the label definition path are always returned.

Use "*" to return all fields.

Response

HTTP Status Fields Possible Values Situations
200 OK statusCode 0 (Ok) Retrieval of all label definitions succeeded.
7 (PartialResponse) Retrieval of some label definitions failed.
12 (UnableToRetrieveResource) Retrieval of all label definitions failed.
labelDefinitions An array of label definitions always

Label definition response data

Fields Description
path The path of the label definition
name The name of the label definition
type The type of the label definition
displayName The display name of the label definition
description The description of the label definition

Examples

GET /recording-label-definitions
{
  "statusCode": 0,
  "labelDefinitions": [
    {
	  "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated"
    },
    {
	  "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag"
    }
  ]
}
 
GET /recording-label-definitions?fields=
{
  "statusCode": 0,
  "labelDefinitions": [
    {
	  "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c"
    },
    {
	  "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B"
    }
  ]
}

GET /recording-label-definitions?fields=*
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated",
      "displayName": "Evaluated",
      "type": "Reserved",
      "description": "A label indicating the interaction on which it is applied has been evaluated."
    },
    {
	  "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "type": "Custom",
      "displayName": "Comment",
      "description": "A label for recording comment."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "type": "Custom",
      "displayName": "Important",
      "description": "A label to tag recordings that are important."
    }
  ]
}
 
GET /recording-label-definitions?fields=name,displayName
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated",
      "displayName": "Evaluated"
    },
    {
	  "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "displayName": "Comment"
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "displayName": "Important"
    }
  ]
}
 
GET /recording-label-definitions?fields=*&type=Custom
{
  "statusCode": 0,
  "labelDefinitions": [
    {
	  "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a",
      "name": "comment",
      "type": "Custom",
      "displayName": "Comment",
      "description": "A label for recording comment."
    },
    {
      "path": "/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B",
      "name": "importantTag",
      "type": "Custom",
      "displayName": "Important",
      "description": "A label to tag recordings that are important."
    }
  ]
}
 
GET /recording-label-definitions?type=Reserved
{
  "statusCode": 0,
  "labelDefinitions": [
    {
      "path": "/recording-label-definitions/211e698a-279e-389b-840a-8c89c8e8b97c",
      "name": "__evaluated"
    }
  ]
}


Adding a label to a recording

Request URL /recordings/<recid>/labels
HTTP Method POST
Required Roles
  • Admin (permissions not required)
  • Supervisor
  • Agent
Required Permissions RECORDING_PERMISSION_ADD_LABEL


Payload
Properties Type Mandatory Default Values Description
name String Yes N/A The name of the label definition to be added to the recordings.
content JSON Object No empty The content associated with the label to be added to the recordings. This is a free-form JSON element that accepts valid JSON types.

Example

Add a Label to a Recording Payload 

201 CREATED
{
  "statusCode": 0,
  "id": "8c9a634f-343d-49b3-8322-b571be520b31",
  "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
}
  
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Cannot add label to recording."
}

Response

HTTP Status Situations
201 CREATED The label has been added to the recording successfully
403 FORBIDDEN
  • The recording requested can be found but label cannot be added to it for whatever reason (e.g. region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.
  • A label instance already exists that is identical to the one to add on the same recording.
  • The label definition name cannot be found.


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok)
  • The label was added to the requested recording successfully
13 (UnableToCreateResource)
  • The label failed to be added to the requested recording
statusMessage String no
  • not specified
  • message providing information
 The statusMessage will provide more information about a failure if statusCode is not 0.
id String no id of the created label HTTP status is 201
path String no path of the created label HTTP status is 201

Example

201 CREATED
{
  "statusCode": 0,
  "id": "8c9a634f-343d-49b3-8322-b571be520b31",
  "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
}
  
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Cannot add label to recording."

Adding a label to multiple recordings

Request URL /recording-labels
HTTP Method POST
Required Roles
  • Admin (permissions not required)
  • Supervisor
  • Agent
Required Permissions RECORDING_PERMISSION_ADD_LABEL


Payload
Level-0 Properties Level-1 Properties Type Mandatory Default Values Description
recordingIds N/A JSON Array Yes N/A The list of recording IDs that the label needs to be added to.
label name String Yes N/A The name of the label to be added to the recordings.
content JSON Object No empty The content associated with the label to be added to the recordings. This is a free-form JSON element that accepts valid JSON types.

Example

Add Label To Recordings Payload Example 
 
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "text" :  "This is an awesome comment!" 
     } 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "importantTag" 
   } 
} 
   
POST /recording-labels 
{ 
   "recordingIds" : [ 
     "bf697521-3ffc-46f1-b840-f7230e940df3" , 
     "76705af9-65d4-46a4-af84-e984ef09ec5d" 
   ], 
   "label" : { 
     "name" :  "comment" , 
     "content" : { 
       "time" :  "2017-08-05T15:07:17Z" , 
       "rating" :  "excellent" , 
       "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
       } 
     } 
   } 
}


Response

HTTP Status Situations
200 OK The requested list of recordings is empty.
201 CREATED The label has been added to all the requested recordings successfully and at least one label resource has been

Created.

207 MULTI-STATUS The label failed to be added to some but not all of the requested recordings, but succeeded for the rest.
403 FORBIDDEN The label failed to be added to all of the requested recordings.

Example

200 OK{
  "statusCode": 0,
  "succeeded": [],
  "failed": []
}
  
201 CREATED
{
  "statusCode": 0,
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "id": "8c9a634f-343d-49b3-8322-b571be520b31",
      "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
    },
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "id": "1574da8d-ed8d-419d-b2e7-f00c1dabe0dc",
      "path": "/recordings/76705af9-65d4-46a4-af84-e984ef09ec5d/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc"
    }
  ],
  "failed": []
}
 
207 MULTI-STATUS
{
  "statusCode": 7,
  "statusMessage": "Add of label failed on some recordings.",
  "succeeded": [
    {
      "recordingId": "bf697521-3ffc-46f1-b840-f7230e940df3",
      "id": "8c9a634f-343d-49b3-8322-b571be520b31",
      "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31"
    }
  ],
  "failed": [
    {
      "recordingId": "76705af9-65d4-46a4-af84-e984ef09ec5d",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    },
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Internal error."
    }
  ]
}
 
403 FORBIDDEN
{
  "statusCode": 13,
  "statusMessage": "Add of label failed on all the recordings.",
  "succeeded": [],
  "failed": [
    {
      "recordingId": "d0464cf3-f81f-49b5-bc0e-bd166161d756",
      "statusCode": 13,
      "statusMessage": "Cannot add label."
    }
  ]
}


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok) The label is added to all the requested recordings successfully.
7 (PartialResponse) The label succeeded on some of the requested recordings, but failed on the rest.
13 (UnableToCreateResource) The label failed to be added to all the requested recordings.
statusMessage String no
  • not specified
  • a message providing information
 The statusMessage will provide more information about a failure if statusCode is not 0.
succeeded JSON Array yes The recording id to created label URI mapping for the recordings to which label has been successfully added. It will always be displayed in the response but can be empty.
failed JSON Array yes A list of blocks that describes the failures. It will always be displayed in the response but can be empty.

Updating a label on a recording

Request URL /recordings/<labels>
HTTP Method PUT
Required Roles
  • CCadmin
  • Supervisor
  • Agent
Required Permissions RECORDING_PERMISSION_ADD_LABEL


Payload
Properties Type Mandatory Default Values Description
content JSON Object No empty The content associated with the label to be updated to the

recordings. This is a JSON object which can be customized depending on the application. The examples below show a possible use-case of adding user comments on a recording.

Example

PUT /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "text" :  "This is an awesome comment!" 
   } 
} 
   
PUT /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/5dbdb466-5377-4351-bd1e-c4066437d410 
{ 
   "content" : { 
     "time" :  "2017-08-05T15:07:17Z" , 
     "rating" :  "excellent" 
     "by" : { 
         "userName" :  "supervisor_1" , 
         "firstName" :  "super" , 
         "lastName" :  "visor" 
     } 
   } 
}

Effect

When a label is updated:

  • The content of the label is updated to the one that is specified in the payload.
  • The field createTime is updated to the time when the update action was performed.
  • The field createUser is updated to the username of the user who requested the update.

Response

HTTP Status Situations
200 OK The requested label has been updated successfully.
403 FORBIDDEN
  • The recording requested can be found but the label cannot be updated to it for whatever reason (e.g., region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.
404 NOT FOUND The requested label cannot be found.


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok) The label has been updated to the requested recording successfully.
6 (ResourceNotFound) The label cannot be found.
15 (UnableToUpdateResource)
  • The recording requested can be found but the label cannot be updated to it for whatever reason (e.g. region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.
statusMessage String no
  • not specified;
  • a message providing information
 The statusMessage will provide more information about a failure if statusCode is not 0.

Example

Update Label To a Recording Response 

200 OK 
{ 
   "statusCode" : 0 
} 
  
403 FORBIDDEN 
{ 
   "statusCode" : 15, 
   "statusMessage" :  "Cannot update the label for recording." 
} 
   
404 NOT FOUND 
{ 
   "statusCode" : 6, 
   "statusMessage" :  "Requested label cannot be found." 
}

Deleting a label from a recording

Request URL /recordings/<recid>/labels/<id>
HTTP Method DELETE
Required Roles
  • Admin (permissions not required)
  • Supervisor
  • Agent
Required Permissions RECORDING_PERMISSION_DELETE_LABEL


Why no Payload table here? Because a Delete request has no payload?


Response

HTTP Status Situations
200 OK
  • The label has been deleted from the requested recording successfully.
403 FORBIDDEN
  • The recording requested can be found but the label cannot be deleted from it for some reason (e.g., region not matched, requesting user cannot access the recording).
  • The recording requested cannot be found.


Payload
Fields Type Mand-
atory 		Possible
Values 		Situations Notes
statusCode Integer yes 0 (Ok)

The label has been deleted from the requested recording successfully
  OR
The label cannot be found within the requested recording.

14 (UnableToDeleteResource) The label failed to be deleted from the requested recording.
statusMessage String no
  • not specified;
  • a message providing information.
 The statusMessage will provide more information about a failure if statusCode is not 0.

Example

Delete Label Instance From Recording Response 

DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
200 OK 
{ 
   "statusCode" : 0 
} 
   
DELETE /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31 
403 FORBIDDEN 
{ 
   "statusCode" : 14, 
   "statusMessage" :  "Label failed to be deleted from the recording." 
}

Getting all labels from a recording

Request URL /recordings/<recid>/labels
HTTP Method GET
Required Roles
  • CC Admin
  • Supervisor
  • Agent
Required Permissions N/A


Payload
Fields Subfields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok) the label was added to the requested recording successfully
13 (UnableToCreateResource) label failed to be added to the requested recording
18 (ResourceAlreadyExists) there already exists a label instance that is identical to

the one to add on the same recording

statusMessage String no

  • not specified

  • a message providing information

The statusMessage will provide more information about a

failure if statusCode is not 0.

labels





array of labels no Each label will have the fields requested if fields parameter is received
id String no the id of the created label 
if fields parameter is received
path String no the path of the created label if fields parameter is received
name String no the name of the label definition if fields parameter is received
uri String no the uri of the label on the recording if fields parameter is received
createTime String no The time when the label was last updated if fields parameter is received
createUser String no The username of the user who last updated the label on the

recording.

if fields parameter is received
content JSON object no JSON object containing custom content if populated if fields parameter is received The content is a JSON object that can contain custom data

information.

paths array of paths no The array of paths of label instances associated with this

recording

if fields parameter is not present
uris array of uris no The array of uris of label instances associated with this

recording

if fields parameter is not present


Response

HTTP Status Situations
200 OK The retrieval of the labels succeeded or there are no

labels associated with the recording

403 FORBIDDEN
  • The recording for which the labels are requested can be found but cannot be retrieved for some reason (e.g., region not matched, requesting user cannot access the recording).
  • The recording for which the labels are requested cannot be found.


Payload Fields Subfields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok) The label was added to the requested recording successfully.
13 (UnableToCreateResource) The label failed to be added to the requested recording.
18 (ResourceAlreadyExists) There already exists a label instance that is identical to the one to add to the same recording.
statusMessage String no
  • not specified
  • a message providing information
 The statusMessage will provide more information about a failure if statusCode is not 0.
labels array of labels no Each label will have the fields requested. Always.
ID String no The ID of the created label. Always.
path String no The path of the created label. Always.
name String no The name of the label definition. not specified or if fields parameter is received.
createTime String no The time when the label was last updated. If the fields parameter is received.
createUser String no The username of the user who last updated the label on the recording. If the fields parameter is received.
content JSON object no The JSON object containing custom content, if populated. If the fields parameter is received. The content is a JSON object that can contain custom data.

Example

GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df5/labels
200 OK
{
   "statusCode" : 0,
   "labels" : []
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df4/labels
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31" ,
       "name" :  "comment" ,
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31"
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31" ,
      
 "id" :  "8c9a634f-343d-49b3-8322-b571be520b31"
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=content
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31",
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31" ,
       "content" : {
         "time" :  "2017-04-22T12:42:44.000+0000" ,
         "comment" :  "This is an awesome comment!"
       }
     }
   ]
}
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=*
200 OK
{
   "statusCode" : 0,
   "labels" : [
     {
       "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels
/8c9a634f-343d-49b3-8322-b571be520b31" ,
       "name" :  "comment" ,
       "id" :  "8c9a634f-343d-49b3-8322-b571be520b31"
 ,
       "createTime" :  "2017-04-22T12:42:46.000+0000" ,
       "createUser" :  "supervisor" ,
       "content" : {
         "time" :  "2017-04-22T12:42:44.000+0000" ,
         "comment" :  "This is an awesome comment!"
       }
     }
   ]
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels
403 FORBIDDEN
{
   "statusCode" : 12,
   "statusMessage" :  "Recording cannot be found."
}
  
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels?fields=*
403 FORBIDDEN
{
   "statusCode" : 12,
   "statusMessage" :  "Recording cannot be accessed."
}

Getting a specific label from a recording

Request URL /recordings/<recid>/labels/<id>
HTTP Method GET
Required Roles
  • CC Admin
  • Supervisor
  • Agent
Required Permissions xxxxxxxxx


Why no Payload table here?

Response

HTTP Status Situations
200 OK The retrieval of the label succeeded
403 FORBIDDEN
  • The recording for which the label is requested can be found but cannot be retrieved for some reason (e.g., region not matched, requesting user cannot access the recording).
  • The recording for which the label is requested cannot be found.
404 NOT FOUND
  • The label cannot be found by the ID specified.


Payload
Fields Type Mandatory Possible Values Situations Notes
statusCode Integer yes 0 (Ok) Retrieval of the label succeeded.
6 (ResourceNotFound) The label cannot be found.
12 (UnableToRetrieveResource) Retrieval of the label failed.
statusMessage String no
  • not specified
  • a message providing information
 The statusMessage will provide more information about a failure if statusCode is not 0.
label JSON Object no The actual data of the label requested.

A label contains the following information:
Path (string): the path of the label.
Name (string): the name of the label.
Type (string): the type of the label.
ID (string): the ID of the label.
createTime (string): the time the label was last created or updated.
createUser (string): the last user that created or updated the label.
content (a JSON object): an object containing custom data, if populated.

It will only be displayed if the retrieval of the labels succeeded.

Example

GET /recordings/bf697521-3ffc-46f1-b840-f7230e940da3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
200 OK 
{ 
   "statusCode" : 0, 
   "label" : { 
     "path" :  "/recordings/bf697521-3ffc-46f1-b840-f7230e940da3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc" , 
     "name" :  "comment" , 
     "id" :  "1574da8d-ed8d-419d-b2e7-f00c1dabe0dc" , 
     "createTime" :  "2017-04-20T04:11:02.000+0000" , 
     "createUser" :  "supervisor" , 
     "content" : {} 
   } 
} 
   
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
403 FORBIDDEN 
{ 
   "statusCode" : 12, 
   "statusMessage" :  "Recording cannot be found." 
} 
   
GET /recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/1574da8d-ed8d-419d-b2e7-f00c1dabe0dc 
404 NOT FOUND 
{ 
   "statusCode" : 6, 
   "statusMessage" :  "Label cannot be found for the recording." 
}

Getting details of a recording, including labels

Add to the GetRecordings API. Add the following parameter in the Resource details table:

Field Description
labels A collection of labels associated with the recording. Each label will contain the following information:


path (string): the path of the label.
name (string): the name of the label.
type (string): the type of the label.
ID (string): the ID of the label.
createTime (string): the time the label was last created or updated.
createUser (string): the last user that created or updated the label.
content (a JSON object): an object containing custom data, if populated.

Querying Recordings with Labels

Add to the GetRecordings API. Add these 2 parameters in the Parameters table:

Parameter Value
includeLabels Retrieves all recordings for any call that contain all of the labels in the comma-separated string of label names.

The request string is a comma-separated list of label names.
For example: includeLabels=comment_good, rate_good.

excludeLabels Retrieves all recordings for any call that does not contain any of the labels in the comma-separated string of label names.

The request string is a comma-separated list of label names.
For example: excludeLabels=comment_bad, bad.

Example: Label Filter Query Parameter

GET /recordings?includeLabels=comment=*
{
  ...
  "mediaFiles": [...],
  "eventHistory": [...],
  "labels": [
    {
      "path": "/recordings/bf697521-3ffc-46f1-b840-f7230e940df3/labels/8c9a634f-343d-49b3-8322-b571be520b31",
      "name": "comment",
      "id": "8c9a634f-343d-49b3-8322-b571be520b31",
      "createTime": "2017-04-22T12:42:46.000+0000",
      "createUser": "supervisor",
      "content": {
        "time": "2016-04-22T12:42:44.000+0000",
        "text": "This is an awesome comment!"
      }
    }
  ],
  ...
}
 
Update the sample data example at  https://docs.genesys.com/Documentation/CR/DRAFT/API/GIR. with the following:
Sample Data 
  {
  "id":"011AP643CSAPR4FKQGQE31TAES00029V",
  "callerPhoneNumber":"8522001",
  "dialedPhoneNumber":"+14160000001",
  "startTime":"2015-09-10T16:58:22.000+0000",
  "stopTime":"2015-09-10T16:58:34.000+0000",
  "mediaFiles":[
    {
       "mediaUri":"http://htcc1.genesyslab.com/api/v2/recordings/011AP643CSAPR4FKQGQE31TAES00029V/play/4f82ee48-4fe4-40e1-961d-309ba6e38698.mp3",
       "mediaPath":"/recordings/011AP643CSAPR4FKQGQE31TAES00029V/play/4f82ee48-4fe4-40e1-961d-309ba6e38698.mp3",
       "playPath":"/recordings/011AP643CSAPR4FKQGQE31TAES00029V/play/4f82ee48-4fe4-40e1-961d-309ba6e38698.mp3",
       "startTime":"2015-09-10T16:58:22.000+0000",
       "stopTime":"2015-09-10T16:58:34.000+0000",
       "callUUID":"011AP643CSAPR4FKQGQE31TAES00029V",
       "mediaId":"011AP643CSAPR4FKQGQE31TAES00029V_2015-09-10_16-58-22-006B015F-1000427D-00000001.mp3",
       "type":"audio/mp3",
       "duration":"12523",
       "tenant":"Environment",
       "ivrprofile":"CallRecProfile",
       "size":"199296",
       "parameters":{
          "dnis":"+14160000001",
          "connId":"006a0269722cd93f",
          "ani":"8522001",
          "dateTime":"2015-09-10T16:58:22Z",
          "rp.speechminer_uri":"http://135.225.52.210/interactionreceiver",
          "recordDN":"+14160000001",
          "agentId":"+14160000001",
          "rp.speechminer_auth":"rpSys:111111",
          "sipsAppName":"SIP_Server",
          "id":"011AP643CSAPR4FKQGQE31TAES00029V_2015-09-10_16-58-22",
          "username":"screen1@genesys.com",
          "callUuid":"011AP643CSAPR4FKQGQE31TAES00029V"
       },
       "partitions":[
       ],
       "accessgroups":[
          "/"
       ]
    }
  ],
  "eventHistory":[
    {
       "occurredAt":"2015-09-10T16:58:22.000+0000",
       "calluuid":"011AP643CSAPR4FKQGQE31TAES00029V",
       "eventId":"2015-09-10 16:58:22.440_011AP643CSAPR4FKQGQE31TAES00029V",
       "event":"Data",
       "data":{
          "added":{
             "GSIP_RECORD":"ON",
             "GSIP_REC_FN":"011AP643CSAPR4FKQGQE31TAES00029V_2015-09-10_16-58-22"
          }
       }
    },
    {
       "occurredAt":"2015-09-10T16:58:34.000+0000",
       "calluuid":"011AP643CSAPR4FKQGQE31TAES00029V",
       "eventId":"2015-09-10 16:58:34.820_011AP643CSAPR4FKQGQE31TAES00029V",
       "event":"Data",
       "data":{
          "deleted":{
             "GSIP_RECORD":"ON"
          }
       }
    },
    {
       "occurredAt":"2015-09-10T16:58:22.000+0000",
       "calluuid":"011AP643CSAPR4FKQGQE31TAES00029V",
       "contact":{
          "type":"User",
          "phoneNumber":"+14160000001",
          "userName":"screen1@genesys.com",
          "firstName":"Screen",
          "lastName":"GIR"
       },
       "event":"Joined"
    },
    {
       "occurredAt":"2015-09-10T16:58:21.000+0000",
       "calluuid":"011AP643CSAPR4FKQGQE31TAES00029V",
       "contact":{
          "type":"External",
          "phoneNumber":"8522001"
       },
       "event":"Joined"
    },
    {
       "occurredAt":"2015-09-10T16:58:34.000+0000",
       "calluuid":"011AP643CSAPR4FKQGQE31TAES00029V",
       "contact":{
          "type":"User",
          "phoneNumber":"+14160000001",
          "userName":"screen1@genesys.com",
          "firstName":"Screen",
          "lastName":"GIR"
       },
       "event":"Left"
    },
    {
       "occurredAt":"2015-09-10T16:58:34.000+0000",
       "calluuid":"011AP643CSAPR4FKQGQE31TAES00029V",
       "contact":{
          "type":"External",
          "phoneNumber":"8522001"
       },
       "event":"Left"
    }
  ],
  "labels": [
    {
      "id": "646943bc-b9d2-48e7-9304-d9b4c92be2d2",
      "name": "Important",
      "createTime": "2017-01-01T00:00:00.000+0000",
      "createUser": "Agent1"
    }
  ], 
  "callType":"Inbound",
  "region":"region1"
}
Comments or questions about this documentation? Contact us for support!