8x8 Contact Center Data Augmentation API

Updated: 04/22/2024

Overview

Interaction data augmentation is a mechanism to enrich the data associated with a particular interaction. The source of data could be from collecting information from users - through web forms/IVR etc, from data dips (eg Salesforce , Netsuite, DB …), speech analytics (sentiment of the caller), etc. The data associated with the interaction can serve multiple purposes:

Used for routing decisions in the script
For displaying to the agent when offering the interaction.
For routing the interaction to the best-matched agent.
For analytics, auto logs, etc.

The 8x8 Interaction Data Augmentation API is an HTTP API that allows tenants to set and retrieve variables(meta data) associated with an interaction. This document describes the supported parameters for calling the Interaction Data Augmentation API. Example use cases are provided for reference.

For security reasons, the Interaction Data Augmentation API only accepts requests using HTTPS, so that request headers and response data are encrypted.

Base URL

All URLs referenced in the documentation have the following base:

https://vcc-sb1.8x8.com/api/v1/interaction/data/

Revise your query URL based on the login URL of your Tenant. Refer to the 8x8 Contact Center Platform URL Guide to retrieve your login URL.

Authentication

The API is authenticated with HTTP Basic Authentication, which needs tenantId as the username and action token of the tenant as the password.

Examples

Example 1: The following example shows how to set variables for an interaction. The interaction is identified by the SIP call Id of the eIVR leg:

{
    "variables": [{
        "name": "_queueId",
        "value": "201",
        "ivr": "true"
    }, {
           "name": "_SSN",
            "value": "111-22-3333",
            "ivr": "true",
            "privacy": "true"
    }, {
            "name": "_amount",
            "value": "110.55",
            "display": "true",
            "displayName": "Amount Due"
    }, {
            "name": "_dueDate",
            "value": "04 July 2019",
            "ivr": "true",
            "display": "true",
            "displayName": "Due Date",
            "dataType": "date"
    }]
}

Example 2: The following example shows how to set variables for an interaction. The interaction is identified by the interaction guid of the call:

{
    "variables": [{
        "name": "_queueId",
        "value": "201",
        "ivr": "true"
    }, {
        "name": "_SSN",
        "value": "111-22-3333",
        "ivr": "true",
        "privacy": "true"
    }, {
        "name": "_amount",
        "value": "110.55",
        "display": "true",
        "displayName": "Amount Due"
    }, {
        "name": "_dueDate",
        "value": "04 July 2019",
        "ivr": "true",
        "display": "true",
        "displayName": "Due Date",
        "dataType": "date"
    }]
}

Example 3: The following example shows how to get all the context associated with an interaction. The interaction context will be returned as a json object (the format is described below). The interaction is identified by the interaction guid of the call:

curl -H "Content-Type: application/json" -X GET -u acme:00a5c5dd78ba119df8e361288b709e4c2d19ef440c0f2af96d48ead1faa78c9b 'https://vcc-sb1.8x8.com/api/v1/interaction/data/guid/int-1628bb9dbf7-YUTGAUsGrJDvPC9DqMgJr01iy-phone-01-acme'

NOTE: Using curl on Windows you will need to replace the single quotes (') in the example above to standard quotation marks (").

Query Parameters

The following parameters are allowed as POST/GET parameters to be passed along with the Interaction Data Augmentation URL. All the parameter data should be URL encoded.

Parameter Name	Description	Required	Accepted Value
callId	st	N	Interactions are identified by either the SIP call id or the interaction guid
guid	Interaction guid	N

Input JSON description

The API allows the client application to set any number of variables bypassing the data in JSON format. There is no limit on how many number of name/value data can be used to compose the json string. The API supports setting certain metadata about a variable, that allows the caller to control how the variable is used within the application. A description of the meta data is provided in the table below. The following json is used as an example for describing the json format:

{
    "variables": [{
            "name": "_queueId",
            "value": "201",
            "ivr": "true"
        },
        {
            "name": "_SSN",
            "value": "111-22-3333",
            "ivr": "true",
            "privacy": "true"
        },
        {
            "name": "_amount",
            "value": "110.55",
            "display": "true",
            "displayName": "Amount Due"
        },
        {
            "name": "_dueDate",
            "value": "04 July 2019",
            "ivr": "true",
            "display": "true",
            "displayName": "Due Date",
            "dataType": "date"
        }
    ]
}

Attribute Name	Possible Values	Description
name	string	Names must begin with _, alphanumeric, less than 25 characters and contain no space.
ivr	true/false	If set to true, this variable can be used for routing in the IVR. The name of the variable should match the name set in the IVR script - else the variable is ignored.
display	true/false	This value determines if the variable should be included in the list of name-value pairs displayed to the agent when offering an interaction.
displayName	Any string less than 30 characters	This string is used as the name of the variable when displaying to the agent.
dataType	text/number/phone number/date/time/currency	Used as a hint to the TTS engine.
privacy	true/value	If set to true, the application will use the value only for routing purposes. Data is obfuscated /masked before displaying/storing in DB.

Output json description

The API allows a client application to retrieve all context data associated with an interaction. The description of the content of the json object is described in the table below.

Variable Name	Always available	Description
InteractionId	Y	Interaction id of the interaction
Channel	N	The number dialed by the caller(for inbound calls)
CreateTime	Y	Time interaction was created
ANI	N	The caller id of the caller
CallerName	N	The name of the caller
QueueId	N	The queue id of the interaction (if the call was queued).
QueueTime	N	The time the call was queued
Priority	N	Priority of the interaction
AgentId	N	Id of the agent associated with the interaction - either through setAgent or by dialing extension number.
UserInput	N	array of name/value pairs of data collected from the caller in the IVR.

Response Codes

Code Number	Code Label	Description
200 (Status: success)	OK	The request was successful.
400	Bad request	The action type is not supported.
401	Unauthorized	The request was not allowed, usually due to incorrect authentication.
404	Not found	The interaction was not found in the target Tenant.
500	Server Error	Internal server error preventing the request to be completed.