Cisco MediaSense Developer Guide, Release 11.0(1)
- Updated:
- August 10, 2015
Chapter: Session Management APIs
Session Management APIs
Introduction
In the Contact Center or in speech analytics environments, a supervisor, an agent or a speech analytics system may need to add a tag to a session that is being recorded or has already been recorded. Or, they may need to better manage their session recording repository by deleting some sessions or saving other sessions to prevent those sessions from being deleted.
MediaSense provides these management capabilities through session management APIs. Using these APIs, third-party clients can add or delete tags to sessions and delete sessions one-at-a-time or in bulk. Clients can also convert a session to supported formats like mp4 or wav and move them to a pre-specified location (on the MediaSense system).
 Note | While you can add or delete tags on both active and completed session recordings, you can only delete completed session recordings. Similarly, you cannot convert a session if it is in the ACTIVE or ERROR state. |
addSessionTag
Use this API to add tags to closed (already recorded) or active (currently being recorded) sessions. A tag is the name assigned by the user to label a recording.
Note | Within Cisco, the accepted protocol when adding tags is to include a prefix and a colon (:) at the beginning of each tag to identify the application that is inserting the tag. For example, the prefix for tags inserted by CCX applications is "CCX:". Following this protocol ensures that multiple, independent client applications can insert tags into MediaSense without inadvertently inserting tag names that are meaningful or confusing to each other. |
URI
https://<host>:<port>/ora/managementService/manage/addSessionTag
Parameter
-
sessionId— It is a required input string. It is a system-generated identifier for a session. See Shared Parameters.
-
tagName— It is an output string. The name that is used to label a recording, which is not case sensitive. See Shared Parameters.
-
tagOffset— It is an optional integer. The number of milliseconds from the start of session for the tag. See Shared Parameters.
Related Event
tagEvent— The event is sent when a tag is added or deleted from a session. For more information, see tagEvent.
Example
HTTPS POST:
https://10.10.10.10:8440/ora/managementService/manage/ addSessionTag
Headers:
Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request>
Body:
{
"requestParameters":
{
"sessionId": "AMS_10.194.118.56_1283550575777_2",
"tagName": "Sample tag",
"tagOffset": 10
}
}
Response:
{
"responseMessage":"Success: Your request was successfully completed.",
"responseCode":2000
}
convertSession (Deprecated)
Use this API to convert a MediaSense session to the format specified in the request. If your request is successful, you receive a list of links of the converted files in the response.
Note | If the MediaSense session exists in the request format, the existing links are returned. New links are not created in the system. If the MediaSense session is in ACTIVE or ERROR state, the session cannot be converted. The system deletes the converted mp4 and wav files after a maximum of 2 hours of their creation or last modification. |
URI
https://<host>:<port>/ora/managementService/manage/convertSession
HTTP Method
POST
Parameters
-
convertedLink— It is an output string. These strings are generated as part of the convertSession API. A comma-separated list of URLs. Each URL points to the audio recording of a session. All values together make up the string.
-
convertedFormat— It is an intput string. The format to convert a MediaSense session. Enumeration value is MP4.
-
sessionId— It is a required input string. The system-generated identifier for a session. See Shared Parameters.
Examples
Example 1
HTTPS POST:
https://10.10.10.10:8440/ora/managementService/manage/ convertSession
Headers:
Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request>
Body:
{ "requestParameters":
{
"sessionId": "AMS_10.10.10.10_1283550575777_2",
"conversionFormat": "mp4"
}
}
Response:
{
"responseMessage":"Success: Your request was successfully completed.",
"responseCode":2000,
"responseBody":
{
"convertedLink":"http://10.10.10.10:8080/
oramedia/mp4/Session-1-10.10.10.10-
1283811989534.mp4"
}
}
Example 2—System Capacity Exceeded
HTTPS POST:
https://10.10.10.10:8440/ora/managementService/manage/ convertSession
Headers:
Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request>
Body:
{ "requestParameters":
{
"sessionId": "AMS_10.10.10.10_1283550575777_2",
"conversionFormat": "mp4"
}
}
Response:
{
“responseCode”: 5006,
“responseMessage”: “Failure: Unable to convert the session. Try again later.”,
"detail": "Capacity Exceeded"
}
deleteSessions
Use this API to delete recorded sessions based on the specified Session IDs.
Note | You cannot delete an active session.
The jobId parameter in a successful response is used in the job query API to retrieve the job status and results. |
URI
https://<host>:<port>/ora/managementService/manage/deleteSessions
HTTP Method
POST
Parameters
-
jobId— It is an output string. It is a system-generated ID. See Shared Parameters.
-
sessionIds— It is an input parameter. A list of sessions IDs.
Example
To delete multiple recordings:
HTTPS POST:
https://10.194.118.64:8440/ora/managementService/manage/ deleteSessions
Headers:
Content-Type: application/json
Body:
{
"requestParameters": {
"sessionIds": [
"4ed31387d58902d1",
"4ed31387d58923a3"
]
}
}
Response:
{
"responseCode": 2000,
"responseMessage": "Successful",
"jobId": "abcd1234"
}
deleteSessionTag
Use this API to delete tags from a session. A tag is the name assigned by the user to label a recording. After you no longer need a label or tag, delete it from this session using this API. The tagName and tagOffset parameters are unique for a tag. When deleting a recording, make sure that you use the same name and offset fields with which it was created (using the addSessionTag API). After you delete a tag, you cannot undo this operation. However, you can add the tag again to the session by specifying the tag name and offset fields.
URI
https://<host>:<port>/ora/managementService/manage/deleteSessionTag
HTTP Method
POST
Parameter
-
sessionId— It is an output string. It is a system-generated identifier for a session. See Shared Parameters.
-
tagName— It is an output string. The name that is used to label a recording. See Shared Parameters.
-
tagOffset— It is an output integer. The offset is calculated from the start of the session or track. See Shared Parameters.
Related Event
tagEvent— The event is sent when a tag is added or deleted from a session. For more information, see tagEvent.
Example
HTTPS POST:
https://10.78.95.207:8440/ora/managementService/manage/ deleteSessionTag
Headers:
Content-Type: application/json JSESSIONID: <the jsessionId received from a signIn request>
Body:
{
"requestParameters":
{
"sessionId": "3212d734fd0a71",
"tagName": "demo",
"tagOffset": 10
}
}
Response:
{
"responseMessage":"Success: Your request was
successfully completed.",
"responseCode":2000
}
Feedback