Jump to: navigation, search

Insertion API

The Genesys Interaction Recording Insertion API allows users to insert records into the Genesys Interaction Recording system. You can use this API to update the GIR database with records of existing call recordings already stored at a WebDAV storage location, so that they are accessible from the Genesys Interaction Recording user interfaces.

Insert Recording

This request inserts one single record representing one recording into the GIR database.

Request URL /internal-api/contact-centers/{id}/recordings
HTTP Method POST
Required Features api-supervisor-recording

Prerequisites

Contact Center ID

The HTTP request URI you use to insert a new recording contains a "contact-center-id" that represents the Business Unit for which the request is to be made. For more information about how to get the contact center ID for your deployment, see Configuring the Storage Credentials for Web Services in the Configuration for Voice Recordings section of the Genesys Interaction Recording Solution Guide.

Authentication

This API uses a different authentication model than the other Interaction Recording Web Services APIs. For those APIs, you make a request with a username and password that belong to a normal user of the Genesys environment who also exists in Configuration Server. To use this Genesys Interaction Recording Insertion API, the HTTP request must send a Basic Authentication header with the opsUsername and opsUserPassword defined in the application.yaml file.

Cross Site Request Forgery Protection Header

As with any POST request to Interaction Recording Web Services, you must add the Cross Site Request Forgery Protection (CSRF) headers to the requests. See Cross Site Request Forgery Protection for details about how to get the values for these HTTP headers.

Request Body

The request body contains information for one single recorded interaction. This API accepts only a body of the request with Content-Type "application/json", and the request body is a JSON object. The following is a description of the format of the JSON object.

Attribute JSON Data Type Description Mandatory
id String This is the unique ID of the recording resource being created. If the ID does not already exist in the GIR database, a new record for this recording is created. If the ID already exists in the GIR database, it merges the existing record with information from the POST request. At this time, Genesys does not support updating an existing record by using an existing ID in the POST request, and it’s the HTTP client’s responsibility to ensure the ID is unique Yes
callerPhoneNumber String The phone number for the caller who initiated the phone call. Yes
dialedPhoneNumber String The phone number dialed to initiated the phone call. Yes
region String The region in which the recording occurred. Yes
mediaFiles Array A recording for a specific call may consist of one or more media files. See Media File Descriptor for details. Yes
eventHistory Array A history of events relevant to the call recording that occurred during the lifetime of the call. See Event History Descriptor for details. No
callType String Call type can be one of the following values:
  • Internal
  • Inbound
  • Outbound
  • Consult
  • Unknown
 No

Media File Descriptor

The request body can contain one or more Media File Descriptors. Here is a description of the format of this structure:

Attribute JSON Data Type Description Mandatory
callUUID String The call UUID associated with the given media file. It does not have to be unique. This value is not used by the GIR system and is simply be returned when the recording is queried. Yes
startTime String The time at which the media file began recording. This must be in the ISO datetime format. For example: 2013-05-17T11:45:32.000-0800 Yes
stopTime String The time at which the media file finished recording. This must be in the ISO datetime format. For example: 2013-05-17T11:45:32.000-0800 Yes
mediaId String Unique identifier for the media file that is used by clients. It is the client’s responsibility to ensure this ID is unique. Yes*
type String The MIME type of the media file. For example: audio/mp3 No
duration String The duration of the media file, in milliseconds. No
size String The size of the media file, in bytes. No
tenant String The name of the tenant to which this recording belongs. It should match the name of a tenant on your Genesys Configuration Server. No
ivrprofile String The name of the IVR Profile that serviced this recording. No
parameters JSON Object This is some additional information related to the recording. You should populate the parameters described in the following rows in order to realize full GIR functionality. Yes*
parameters.username String If the media recording is recorded on an agent, set this parameter to the agent username as it exists in Configuration Server. Otherwise, don't include this parameter. No
parameters.agentId String If parametres.username exists, set this paramter to the name of the agent login object in Configuration Server used on the switch for this recording. Otherwise, don't include this parameter. No
parameters.recordDN String The DN the on which SIP Server pinned the recording. This can be the agent extension DN if parameters.username exists. If the recording is pinned on a Trunk DN or an IVR, parameters.username is not provided and parameters.recordDN is just a DN. No
parameters.dnis String The number being dialed for this recording segment. No
parameters.ani String The number from which the call was made for this recording segment. No
parameters.callUuid String A unique ID for the call that generated this recording segment. It should match the callUUID for this media file. Yes*
parameters.id String A unique ID used for external cross-referencing by SpeechMiner. You may use the CallUUID for this media file for this parameter. Yes*
masks JSON Array A JSON array specifying the time stamps of the pause and resume periods if the recording is masked by a client application. Each object contains the time and type property.

For example: 

"masks": [
     {"time": "2013-02-06T10:23:10.034Z", "type": "paused"},
    {"time": "2013-02-06T10:32:14.034Z", "type": "resume"}
]
 No
pkcs7 String If the media file is encrypted, this describes the PKCS7 envelop for the encryption performed on the media file. How the media file should be encrypted is out of scope for this API. No
certAlias JSON Array An array of strings of the aliases for the certificates used to encrypt the media file. No
partitions JSON Array A JSON array of strings specifying the partition to which this media file belongs. For more information about partitions, see Access Control for Genesys Interaction Recording Users in the GIR Interaction Recording Solution Guide. No
accessgroups JSON Array A JSON array of strings specifying the Agent Hierarchy group(s) to which this recording belongs. For more information about agent hierarchy and access groups, Access Control for Genesys Interaction Recording Users in the GIR Interaction Recording Solution Guide. No
mediaDescriptor JSON Object A JSON object used to describe the media file. Yes
mediaDescriptor.storage String The type of storage used for the media resource. The only supported value is:
  • webDAV
 Yes
mediaDescriptor.storage_version String The version of the storage being used. It is for information use only. No
mediaDescriptor.path String The storage-specific path to the location where the media is stored. Yes

* - The API accepts a record without this field, but it is still considered mandatory for the GIR solution to function in a consistent way.

Event History Descriptor

The request body may contain one or more event descriptors. There are three types of events: "Joined", "Left" or "Data". Here is a description of the format of this structure:

Attribute JSON Data Type Description Mandatory
occurredAt String The time at which the event happened. This must be in the ISO datetime format. For example: 2013-05-17T11:45:32.000-0800 Yes
event String The type of event. It must be one of the following values:
  • Left
  • Joined
  • Data
 Yes
calluuid String The Call ID associated with this event. No
contact JSON Object Contains information that describes the caller who joined or left the call. Yes, if the event type is Left or Joined.
contact.type String The type of caller. It must be one of the following values:
  • User
  • External
 Yes
contact.phoneNumber String The phone number for the caller. Yes
contact.userName String The user name of the caller. Yes, if the contact type is User.
contact.firstName String The first name of the caller. Yes, if the contact type is User.*
contact.lastName String The last name of the caller. Yes, if the contact type is User.*
eventId String An eventId used to identify the data event. This must be unique between all events across all the recording segments. Yes, if the event type is Data.
data JSON object A JSON object representing the changes in data for an event of type Data. This free-form JSON object can be used to represent arbitrary data and operations (for example, added, deleted, updated, and so on). Yes, if the event type is Data.

* - The API accepts a record without this field, but it is still considered mandatory for the GIR solution to function in a consistent way.

Post Insertion Operations

After inserting recording metadata into Interaction Recording Web Services (RWS), you must also post this metadata to the SpeechMiner Interaction Receiver to be able to access the recording through SpeechMiner. For more information, refer to Re-posting the Recordings to SpeechMiner.

Sample

Request

POST /internal-api/contact-centers/57c0b771-b57c-4ea8-8655-7ef6d3c58ccc/recordings
Content-Type: application/json
 
{ 
   "id":"alex-test-id",
   "callerPhoneNumber":"+14160000000",
   "dialedPhoneNumber":"+14161111111",
   "region":"Can-West",
   "callType":"Inbound",
   "mediaFiles":[ 
      { 
         "callUUID":"123123",
         "startTime":"2015-06-15T23:59:00.000",
         "stopTime":"2015-06-15T23:59:59.000",
         "mediaId":"123123-FFAB-ABAD",
         "type":"audio/mp3",
         "duration":"59000",
         "size":"67324",
         "parameters":{ 
            "username":"agent.bob@example.com"
         },
         "masks":[ 
            { 
               "time":"2015-06-15T23:59:10.034Z",
               "type":"paused"
            },
            { 
               "time":"2013-06-15T23:59:20.034Z",
               "type":"resume"
            }
         ],
         "mediaDescriptor":{ 
            "storage":"webDAV",
            "path":"http://example.com/file1.mp3"
         }
      },
      { 
         "callUUID":"234222",
         "startTime":"2015-06-15T23:58:00.000",
         "stopTime":"2015-06-15T23:58:59.000",
         "mediaId":"123123-FFAB-ABAC",
         "type":"audio/mp3",
         "mediaDescriptor":{ 
            "storage":"webDAV",
            "path":"http://example.com/file2.mp3"
         }
      }
   ],
   "eventHistory":[ 
      { 
         "occurredAt":"2015-06-15T23:58:30.000+0000",
         "calluuid":"234222",
         "eventId":"2015-09-10 13:31:00.887_011AP643CSAPR4FKQGQE31TAES00029B",
         "event":"Data",
         "data":{ 
            "added":{ 
               "drink":"cola",
               "food":"burger"
            }
         }
      },
      { 
         "occurredAt":"2015-06-15T23:58:00.000",
         "calluuid":"234222",
         "event":"Joined",
         "contact":{ 
            "type":"User",
            "phoneNumber":"417001",
            "userName":"agent.bob@example.com",
            "firstName":"Bob",
            "lastName":"Smith"
         }
      }
   ]
}

Response

{
   "statusCode":0
}
Field Description
statusCode Indicates whether the request was correctly handled. It returns 0 if the response was correctly handled by the server, and other values if it was not correctly handled by the server. See Return Values for details.
statusMessage For a status that is not 0, this message provides a human readable reason for reason of failure. See Return Values for details.
This page was last edited on July 17, 2017, at 22:53.
Comments or questions about this documentation? Contact us for support!