Sync Genesys Cloud Metadata to Calabrio ONE

You can define which Genesys Cloud metadata values are synced with Genesys Cloud contacts into Calabrio ONE. Metadata can be collected from two Genesys Cloud API responses. From there, the metadata must be correctly formatted before it can be added to Calabrio ONE. Configuration is complete once the Genesys Cloud metadata is added to Calabrio ONE and mapped to a metadata label.

This topic details the procedure for collecting and formatting metadata from Genesys Cloud API responses, the Calabrio ONE mapping procedure, examples from both types of Genesys Cloud API responses, and a list of supported and unsupported arrays.

After mapped, metadata can be used to add a variety of trackable information to a customer contact in Calabrio ONE. Metadata fields can be found in the Contact Information Details panel on the Interactions page (Interactions tab > select a contact). You can view, edit, or delete a metadata field from your system.

Prerequisites

A metadata field must first be created in Metadata Manager in Calabrio ONE (located at Application Management > QM > QM Configuration > Metadata Manager) for each Genesys Cloud metadata field to be mapped.

  • You must select Text from the Metadata Type drop-down list on the Metadata Manager page for the metadata to map.
  • Ensure None is selected from the ACD Data drop-down list on the Metadata Manager page. All other fields on the Metadata Manager page can be configured as desired.

Page Location

Application Management > Global > System Configuration > ACD Configuration

Procedures

Collect and format Genesys Cloud metadata

This procedure details how to collect and format appropriate metadata from two types of possible Genesys Cloud API responses before you map it to Calabrio ONE metadata labels. One of the two API responses is ConversationRecording (/api/v2/conversations/{conversationId}/recordings), also known as audioRecording. This response is returned by the GenesysClient that hits RecordingApi.

The second API response is ConversationDetails (/api/v2/conversations/{conversationId}/details). This response is returned by the GenesysClient that hits ConversationsApi.

  1. Select the appropriate prefix based on the Genesys Cloud API response.

    Enter audioRecording as the prefix when mapping values from ConversationRecording API responses.

    Enter, conversationDetails as the prefix when mapping values from ConversationDetails API responses.

  2. Collect metadata values for each relevant part of the API response's hierarchical chain.
  3. Separate each section of the metadata value with a period.
  4. If there are no hierarchy levels in the metadata you are collecting, format the metadata value as follows, with no spaces between the text.

    <prefix>.<metadata>

    EXAMPLE   audioRecording.conversationId
    See Obtain and format conversationId from a ConversationRecording API response to learn more about how this metadata value was formed.

  5. If there are hierarchy levels in the metadata you are collecting, format the metadata value as follows, with no spaces between the text.

    <prefix>.<level-one-metadata>.<level-two-metadata>.<level-three-metadata>

    EXAMPLE   conversationDetails.participants.sessions.mediaType
    See Obtain and format mediaType from a ConversationDetails API response to learn more about how this metadata value was formed.

  6. Your Genesys Cloud metadata is now ready to be mapped to Calabrio ONE metadata labels.

Map Genesys Cloud metadata in Calabrio ONE

  1. Navigate to the Genesys Cloud Configuration page.
  2. Within the Metadata Mapping section, click Add Mapping.
  3. In the text box under ACD Metadata Name, enter a Genesys Cloud metadata value you configured during the previous procedure.
  4. Click the drop-down list under the Metadata Label column, and select a metadata label from the list of options.
  5. Click the check icon to save the metadata mapping.
  6. (Optional) Click Add Mapping to add additional metadata mappings and repeat as desired.
  7. Click Save.

ConversationRecording API Examples

This is a sample ConversationRecording API response. In this example let's say you want to map two pieces of metadata from this response, conversationId and mediaUri.

NOTE   waveFormData has hundreds of items. For the purposes of this example, it has been abbreviated to five. Additionally, some data has been modified and abbreviated for security purposes.

Copy
[{
    "id": "c0189a3b-9288-4e1e-a97a-9ac568470933",
    "conversationId": "187377ad-723e-46b7-940b-9d4556add110",
    "startTime": "2022-05-11T08:34:06.955Z",
    "endTime": "2022-05-11T08:34:58.325Z",
    "media": "audio",
    "annotations": [],
    "fileState": "AVAILABLE",
    "mediaUris": {
        "0": {
            "mediaUri": "https://prod-usw2-recording-playback.s3.us-west-2.amazonaws.com/MediaCache/18e...",
            "waveformData": [
                0.50000465,
                0.5,
                0.5,
                0.5,
                0.5
            ]
        }
    },
    "actualTranscodeTimeMs": 1050,
    "maxAllowedRestorationsForOrg": 100,
    "remainingRestorationsAllowedForOrg": 100,
    "sessionId": "0cd6bece-e5a6-410f-a61e-334919088f6d",
    "originalRecordingStartTime": "2022-05-11T08:34:06.955Z",
    "creationTime": "2022-05-11T08:35:02.231Z",
    "selfUri": "/api/v2/conversations/187377ad-723e-46b7-940b-9d4556add110/recordings/c0189a3b-9288-4e1e-a97a-9ac568470933"
}]

Obtain and format conversationId from a ConversationRecording API response

  1. Locate "conversationId". Note that "conversationId" is in line three in the example above.
  2. Use the audioRecording prefix because this is a ConversationRecording API response.
  3. Add a period to separate the different parts of the metadata, resulting in audioRecording.
  4. Add conversationId. Do not add a period at the end.

    You now have the full Genesys Cloud metadata value, audioRecording.conversationId, to map to a Calabrio ONE metadata label.

Obtain and format mediaUri from a ConversationRecording API response

  1. Locate "mediaUri". Note that mediaUri is in line eleven in the example above. It is nestled down three levels starting with mediaUris, then 0, and finally mediaUri.
  2. Use the audioRecording prefix because this is a ConversationRecording API response.
  3. Add a period to separate different parts of the metadata, resulting in audioRecording.
  4. Add mediaUris from line nine, and then add a period, resulting in audioRecording.mediaUris.
  5. Add 0 from line ten, and then add a period, resulting in audioRecording.mediaUris.0.
  6. Finally, add mediaUri from line eleven. Do not add a period at the end.

    You now have the full metadata string, audioRecording.mediaUris.0.mediaUri, to add to Calabrio ONE.

ConversationDetails API Example

This is a sample ConversationDetails API response. In this example let's say you want to collect and format mediaType from this response.

NOTE    For the purposes of this example, identifying data, such as phone numbers and names, has been modified.

Copy
{
    "conversationEnd": "2022-05-11T08:35:02.163Z",
    "conversationId": "187377ad-723e-59b7-940b-9d4556add122",
    "conversationStart": "2022-05-11T08:34:06.690Z",
    "divisionIds": [
        "a554eb0d-6ad3-4865-9db4-f331bb5c37df"
    ],
    "mediaStatsMinConversationMos": 4.368250229990883,
    "mediaStatsMinConversationRFactor": 91.14208221435547,
    "originatingDirection": "inbound",
    "participants": [
        {
            "participantId": "94ea46ee-6b7a-43fb-b448-d9895e169492",
            "participantName": "Hastings MN",
            "purpose": "customer",
            "sessions": [
                {
                    "agentBullseyeRing": 1,
                    "ani": "tel:+16511111111",
                    "direction": "inbound",
                    "dnis": "tel:+17631111111",
                    "edgeId": "65db3a5e-aa9d-158e-abfa-59ea62d217b2",
                    "mediaType": "voice",
                    "protocolCallId": "570add0f-1a57-4cd9-a15b-c983j96381cf",
                    "provider": "Edge",
                    "recording": true,
                    "remoteNameDisplayable": "Hastings MN",
                    "requestedRoutings": [
                        "Standard"
                    ],
                    "routingRing": 1,
                    "selectedAgentId": "24f86794-5027-42ef-a74b-0ce668bbd6b0",
                    "sessionDnis": "tel:+17631111111",
                    "sessionId": "0cd6bece-e5a6-410f-a61e-111919088f6d",
                    "usedRouting": "Standard",
                    "mediaEndpointStats": [
                        {
                            "codecs": [
                                "audio/opus"
                            ],
                            "eventTime": "2022-05-11T08:34:16.432Z",
                            "maxLatencyMs": 30,
                            "minMos": 4.882636138492176,
                            "minRFactor": 92.4535140991211,
                            "receivedPackets": 476
                        },
                        {
                            "codecs": [
                                "audio/opus"
                            ],
                            "eventTime": "2022-05-11T08:34:30.812Z",
                            "maxLatencyMs": 30,
                            "minMos": 4.882628922450319,
                            "minRFactor": 92.45320129394531,
                            "receivedPackets": 716
                        },
                        {
                            "codecs": [
                                "audio/opus"
                            ],
                            "discardedPackets": 76,
                            "eventTime": "2022-05-11T08:34:58.245Z",
                            "maxLatencyMs": 205,
                            "minMos": 4.854700896042841,
                            "minRFactor": 91.28653717041016,
                            "receivedPackets": 1371
                        },
                        {
                            "codecs": [
                                "audio/PCMU"
                            ],
                            "discardedPackets": 81,
                            "duplicatePackets": 1,
                            "eventTime": "2022-05-11T08:34:58.284Z",
                            "maxLatencyMs": 64,
                            "minMos": 4.368250229990883,
                            "minRFactor": 91.24299621582031,
                            "receivedPackets": 1644
                        }
                    ],
                    "metrics": [
                        {
                            "emitDate": "2022-05-11T08:34:06.957Z",
                            "name": "nConnected",
                            "value": 1
                        }
                    ],
                    "segments": [
                        {
                            "conference": false,
                            "segmentEnd": "2022-05-11T08:34:06.957Z",
                            "segmentStart": "2022-05-11T08:34:06.690Z",
                            "segmentType": "system"
                        },
                        {
                            "conference": false,
                            "disconnectType": "peer",
                            "queueId": "c292b7e9-7f29-43b9-86c7-29a111d6c1ca",
                            "segmentEnd": "2022-05-11T08:34:58.209Z",
                            "segmentStart": "2022-05-11T08:34:06.957Z",
                            "segmentType": "interact"
                        }
                    ]
                }
            ]
        }
    ]
}

Obtain and format mediaType from a ConversationDetails API response

  1. Note that mediaType is in line twenty-three in the example above. It is nestled down three levels starting with participants, then sessions, and finally mediaType.
  2. Use the conversationDetails prefix because this is a ConversationDetails API response.
  3. Add a period after conversationDetails to separate different parts of the metadata, resulting in conversationDetails.
  4. Add participants from line eleven, and then add a period, resulting in conversationDetails.participants.
  5. Add sessions from line sixteen, and then add a period, resulting in conversationDetails.participants.sessions.
  6. Finally, add mediaType from line twenty-three. Do not add a period.

    You now have the full metadata value, conversationDetails.participants.sessions.mediaType, to add to Calabrio ONE.

Supported and Unsupported Arrays

The following table indicates which arrays are and are not supported (including all details nestled beneath the arrays).

Supported arrays Unsupported arrays
conversationDetails—participants conversationRecording (audioRecording)—annotations
conversationDetails—sessions conversationRecording (audioRecording)—waveformData
conversationDetails—segments conversationDetails—divisionIds
  conversationDetails—requestedRoutings
  conversationDetails—mediaEndpointStats