Revision as of 03:44, February 15, 2017 by Sschlich (talk | contribs) (→‎Creating Label Definitions)
Jump to: navigation, search

Recording Label API

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

Create a new page titled Recording Label API which will be under the Interaction Recording Web Services API on the left nav bar to document Label Definitions and Adding, Updating and Deleting Labels from Recordings, described below.. Put the following text in the 2 pages: 1. Recording Label API, right after the Pre-requisites 2. https://docs.genesys.com/Documentation/CR/DRAFT/Solution/Permissions, at the beginning of the section titled "Configuring permissions for Recording Labels" A Label Definition provides the basic definition of a label, with a name, displayName and description. A Label can then be added to a voice recording by referring to the name of the label definition.

Label Definitions

Creating Label Definitions

Method Path Required Roles Required Permissions Notes
POST /api/v2/recording-label-definitions
  • Supervisor
  • Agent
 RECORDING_PERMISSION_ADD_LABEL_DEFINITION 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 Notes 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) if the required payload attributes are missing 2 (InvalidRequestParameter) if the constraints of payload attributes are not met 3 (OperationForbidden) if the requesting user does not have the permissions required or is attempti ng to create with reserved name 5 (Unauthorized) if the requesting user does not have the roles required 18 (ResourceAlreadyExists) if a label definition with the same name exists already 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, opti onal): The display name of the label definition description (string, optio nal): The description of the label definition N/A The newly created label definition or existing one in case of attempt to create an already existing one. Examples : { "statusCode": 0, "labelDefinition": { "path": "/api/v2/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": "/api/v2/recording-label-definitions/a6a6f1d9-788a-47b4-bdeb-80b3d598cfa6", "name": "ExistingLabelDefinition", "displayName": "Existing Label Definition", "description": "An existing label definition" } } Updating Label Definitions Method Path Required Roles Required Permissions PUT /api/v2/recording-label-definitions/{labelDefinitionId} Supervisor Agent RECORDING_PERMISSION_ADD_LABEL_DEFINITION Create a link to https://docs.genesys.com/Documentation/CR/DRAFT/Solu tion/Permissions The path attribute fr om the response returned by the GET or POST operations for label definition can be used here. 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 Notes 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) if the required payload attributes are missing 2 (InvalidRequestParameter) if the constraints of payload attributes are not met 3 (OperationForbidden) if the requesting user does not have the permissions required or is attempting to update with different name 5 (Unauthorized) if the requesting user does not have the roles required 6 (ResourceNotFound) if the specified label definition cannot be found 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, op tional): The display name of the label definition description (string, optio nal): The description of the label definition path (string, optional): The path of the label definition N/A Examples: { "statusCode": 0, "labelDefinition": { "path": "/api/v2/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": 5, "statusMessage": "Access denied." } { "statusCode": 6, "statusMessage": "Custom label definition cannot be found." } Deleting Label Definitions Method Path Required Roles Required Permissions DELETE /api/v2/recording-label-definitions/{labelDefinitionId} Supervisor Agent RECORDING_PERMISSION_DELETE_LABEL_DEFINITION Create a link to https://docs.genesys.com/Documentation/CR/DRAFT/Solu tion/Permissions The path attribute fr om the response returned by the GET or POST operations for label definition can be used here. Response HTTP Status Status Codes 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 label definition was deleted 3 (OperationForbidden) if the requesting user does not have the permissions required 5 (Unauthorized) if the requesting user does not have the roles required 6 (ResourceNotFound) if the specified label definition cannot be found 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 GET /api/v2/recording-label-definitions Method Path Required Roles Required Permissions Notes GET /api/v2/recording-label-definitions CC Admin Supervisor Agent N/A Returns all the label definitions. Parameters 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 back for the label definition path is always returned Using "*" returns all fields Response HTTP Status Fields Possible Values Situations 200 OK statusCode 0 (Ok) the retrieval of all the label definitions succeeded 7 (PartialResponse) the retrieval of some of the label definitions failed 12 (UnableToRetrieveResource) the retrieval of all the label definitions failed labelDefinitions an array of label definitions if fields parameter is present, labelDefinitions will be shown in the response but it can be empty: if it could not be retrieved paths an array of paths to label definitions if fields parameter is absent, the paths of all label definitions are returned Label Definition response data Fields Description name the name of the label definition path the path of the label definition displayName the display name of the label definition description the description of the label definition Examples: 200 OK GET /api/v2/recording-label-definitions { "statusCode": 0, "paths": [ "/api/v2/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a", "/api/v2/recording-label-definitions/bc34345a-da45-4436-a1d8-ecffad0aedd4", "/api/v2/recording-label-definitions/cf9dc6f8-639b-4132-a85c-3d9b984e1120", "/api/v2/recording-label-definitions/68b3219c-6e18-4ad8-af80-87bbc4078bfc", "/api/v2/recording-label-definitions/1a64ae51-28d6-41e5-b3b8-3d179f71ea79" ] } GET /api/v2/recording-label-definitions?fields=* { "statusCode": 0, "labelDefinitions": [ { "path": "/api/v2/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a", "name": "comment", "displayName": "Comment", "description": "A label for recording comment." }, { "path": "/api/v2/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B", "name": "importantTag", "displayName": "Important", "description": "A label to tag recordings that are important." } ] } GET /api/v2/recording-label-definitions?fields=name,displayName { "statusCode": 0, "labelDefinitions": [ { "path": "/api/v2/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550a", "name": "comment", "displayName": "Comment" }, { "path": "/api/v2/recording-label-definitions/feda71ce-ea61-4960-b39a-c0a3063d550B", "name": "importantTag", "displayName": "Important" } ] }

PREV Call Recording API

Interaction Recording Web Services includes the Call Recording API, which you can use to control call recording in your application.

StartCallRecording

Overview

Starts call recording. Recording stops when the call is completed or you use the StopCallRecording operation on either the call or the device.

Request URL /api/v2/me/calls/{id}
HTTP method POST
Required features api-voice-recording

Parameters

Parameter Value
operationName StartCallRecording

Sample

Request

POST /api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V
{
  "operationName": "StartCallRecording"
}

HTTP response

{
  "statusCode": 0
}

CometD notification

{  
   "data":{  
      "notificationType":"CallRecordingStateChange",
      "call":{  
         "id":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "state":"Established",
         "callUuid":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "connId":"007102719818001f",
         "deviceUri":"http://127.0.0.1:8080/api/v2/devices/631608b3-ceb1-472b-ba05-2ae39555b0d1",
         "participants":[  
            {  
               "e164Number":"",
               "formattedPhoneNumber":"15001",
               "phoneNumber":"15001",
               "digits":"15001"
            }
         ],
         "dnis":"15001",
         "callType":"Internal",
         "capabilities":[  
            "UpdateUserData",
            "SendDtmf",
            "InitiateConference",
            "Hold",
            "SingleStepTransfer",
            "InitiateTransfer",
            "AttachUserData",
            "DeleteUserDataPair",
            "SingleStepConference",
            "DeleteUserData",
            "Hangup",
            "PauseCallRecording",
            "StopCallRecording"
         ],
         "userData":{  
            "GSIP_RECORD":"ON",
            "IW_BundleUid":"717f9130-a1d9-4092-f8b9-7804ee2592ea",
            "IW_CaseUid":"d7e2c775-edaa-4d1e-b65c-bd48371b43ad",
            "GSIP_REC_FN":"01RCC3N118B1V0SL8O7GK2LAES00000V_15000_15000_15001_2015-10-16_14-26-23_hpe-voicevm-70-dot-genesyslab-dot-com__%3Ccont_center_id%3E"
         },
         "duration":"34",
         "mute":"Off",
         "recordingState":"Recording",
         "supervisorListeningIn":false,
         "monitoredUserMuted":false,
         "monitoring":false,
         "uri":"http://127.0.0.1:8080/api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V",
         "path":"/calls/01RCC3N118B1V0SL8O7GK2LAES00000V"
      },
      "phoneNumber":"15000",
      "messageType":"CallStateChangeMessage"
   },
   "channel":"/v2/me/calls"
}

PauseCallRecording

Overview

Temporarily stops recording the specified phone call.

Request URL /api/v2/me/calls/{id}
HTTP method POST
Required features api-voice-recording

Parameters

Parameter Value
operationName PauseCallRecording

Sample

Request

POST /api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V
{
  "operationName": "PauseCallRecording"
}

HTTP response

{
  "statusCode": 0
}

CometD notification

{  
   "data":{  
      "notificationType":"CallRecordingStateChange",
      "call":{  
         "id":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "state":"Established",
         "callUuid":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "connId":"007102719818001f",
         "deviceUri":"http://127.0.0.1:8080/api/v2/devices/631608b3-ceb1-472b-ba05-2ae39555b0d1",
         "participants":[  
            {  
               "e164Number":"",
               "formattedPhoneNumber":"15001",
               "phoneNumber":"15001",
               "digits":"15001"
            }
         ],
         "dnis":"15001",
         "callType":"Internal",
         "capabilities":[  
            "UpdateUserData",
            "SendDtmf",
            "InitiateConference",
            "Hold",
            "SingleStepTransfer",
            "InitiateTransfer",
            "AttachUserData",
            "DeleteUserDataPair",
            "SingleStepConference",
            "DeleteUserData",
            "Hangup",
            "ResumeCallRecording",
            "StopCallRecording"
         ],
         "userData":{  
            "GSIP_RECORD":"PAUSED",
            "IW_BundleUid":"717f9130-a1d9-4092-f8b9-7804ee2592ea",
            "IW_CaseUid":"d7e2c775-edaa-4d1e-b65c-bd48371b43ad",
            "GSIP_REC_FN":"01RCC3N118B1V0SL8O7GK2LAES00000V_15000_15000_15001_2015-10-16_14-33-31_hpe-voicevm-70-dot-genesyslab-dot-com__%3Ccont_center_id%3E"
         },
         "duration":"498",
         "mute":"Off",
         "recordingState":"Paused",
         "supervisorListeningIn":false,
         "monitoredUserMuted":false,
         "monitoring":false,
         "uri":"http://127.0.0.1:8080/api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V",
         "path":"/calls/01RCC3N118B1V0SL8O7GK2LAES00000V"
      },
      "phoneNumber":"15000",
      "messageType":"CallStateChangeMessage"
   },
   "channel":"/v2/me/calls"
}

ResumeCallRecording

Overview

Resumes recording the specified phone call.

Request URL /api/v2/me/calls/{id}
HTTP method POST
Required features api-voice-recording

Parameters

Parameter Value
operationName ResumeCallRecording

Sample

Request

POST http://localhost:8080/api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V
{
  "operationName": "ResumeCallRecording"
}

HTTP response

{
  "statusCode": 0
}

CometD notification

{  
   "data":{  
      "notificationType":"CallRecordingStateChange",
      "call":{  
         "id":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "state":"Established",
         "callUuid":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "connId":"007102719818001f",
         "deviceUri":"http://127.0.0.1:8080/api/v2/devices/631608b3-ceb1-472b-ba05-2ae39555b0d1",
         "participants":[  
            {  
               "e164Number":"",
               "formattedPhoneNumber":"15001",
               "phoneNumber":"15001",
               "digits":"15001"
            }
         ],
         "dnis":"15001",
         "callType":"Internal",
         "capabilities":[  
            "UpdateUserData",
            "SendDtmf",
            "InitiateConference",
            "Hold",
            "SingleStepTransfer",
            "InitiateTransfer",
            "AttachUserData",
            "DeleteUserDataPair",
            "SingleStepConference",
            "DeleteUserData",
            "Hangup",
            "PauseCallRecording",
            "StopCallRecording"
         ],
         "userData":{  
            "GSIP_RECORD":"ON",
            "IW_BundleUid":"717f9130-a1d9-4092-f8b9-7804ee2592ea",
            "IW_CaseUid":"d7e2c775-edaa-4d1e-b65c-bd48371b43ad",
            "GSIP_REC_FN":"01RCC3N118B1V0SL8O7GK2LAES00000V_15000_15000_15001_2015-10-16_14-33-31_hpe-voicevm-70-dot-genesyslab-dot-com__%3Ccont_center_id%3E"
         },
         "duration":"608",
         "mute":"Off",
         "recordingState":"Recording",
         "supervisorListeningIn":false,
         "monitoredUserMuted":false,
         "monitoring":false,
         "uri":"http://127.0.0.1:8080/api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V",
         "path":"/calls/01RCC3N118B1V0SL8O7GK2LAES00000V"
      },
      "phoneNumber":"15000",
      "messageType":"CallStateChangeMessage"
   },
   "channel":"/v2/me/calls"
}

StopCallRecording

Overview

Stop recording the specified phone call.

Request URL /api/v2/me/calls/{id}
HTTP method POST
Required features api-voice-recording

Parameters

Parameter Value
operationName StopCallRecording

Sample

Request

POST /api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V
{
  "operationName": "StopCallRecording"
}

HTTP response

{
  "statusCode": 0
}

CometD notification

{  
   "data":{  
      "notificationType":"CallRecordingStateChange",
      "call":{  
         "id":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "state":"Established",
         "callUuid":"01RCC3N118B1V0SL8O7GK2LAES00000V",
         "connId":"007102719818001f",
         "deviceUri":"http://127.0.0.1:8080/api/v2/devices/631608b3-ceb1-472b-ba05-2ae39555b0d1",
         "participants":[  
            {  
               "e164Number":"",
               "formattedPhoneNumber":"15001",
               "phoneNumber":"15001",
               "digits":"15001"
            }
         ],
         "dnis":"15001",
         "callType":"Internal",
         "capabilities":[  
            "UpdateUserData",
            "SendDtmf",
            "InitiateConference",
            "Hold",
            "SingleStepTransfer",
            "InitiateTransfer",
            "AttachUserData",
            "DeleteUserDataPair",
            "SingleStepConference",
            "DeleteUserData",
            "Hangup",
            "StartCallRecording"
         ],
         "userData":{  
            "GSIP_RECORD":"OFF",
            "IW_BundleUid":"717f9130-a1d9-4092-f8b9-7804ee2592ea",
            "IW_CaseUid":"d7e2c775-edaa-4d1e-b65c-bd48371b43ad",
            "GSIP_REC_FN":"01RCC3N118B1V0SL8O7GK2LAES00000V_15000_15000_15001_2015-10-16_14-26-23_hpe-voicevm-70-dot-genesyslab-dot-com__%3Ccont_center_id%3E"
         },
         "duration":"353",
         "mute":"Off",
         "recordingState":"Stopped",
         "supervisorListeningIn":false,
         "monitoredUserMuted":false,
         "monitoring":false,
         "uri":"http://127.0.0.1:8080/api/v2/me/calls/01RCC3N118B1V0SL8O7GK2LAES00000V",
         "path":"/calls/01RCC3N118B1V0SL8O7GK2LAES00000V"
      },
      "phoneNumber":"15000",
      "messageType":"CallStateChangeMessage"
   },
   "channel":"/v2/me/calls"
}
Comments or questions about this documentation? Contact us for support!