Documentation
Documentation

Categories

Suggest Edits

Categories

VoiceBase enables you to apply speech analytics to a recording and categorize it according to business definitions. Each definition is called a category and it consists of a conditional statement that is applied to the transcription results and any corresponding metadata provided with the recording.

VoiceBase runs the categories when the recording is processed, and returns a boolean result where a 1 equals a match for the category definition and 0 when it does not match.

Categories are especially useful as a discovery tool when used in conjunction with the Analytic Workbench available in your VoiceBase account.

Categories are created using VoiceBase's proprietary query language, VBQL. For a step-by-step guide to syntax and best practices, the VBQL documentation is available for VoiceBase customers, and we are also happy to spend time in training customers on its usage.

Sending calls to the Analytic Database

In order to query calls and begin creating categories in the Analytic Workbench, they must first be published and indexed in the Analytic Database.

Add the following JSON element to your upload configuration when POSTing to /media to designate that media to be published in the Analytic Database:

{
   "publish":{
      "enableAnalyticIndexing":"true",
      }
}

CallDetails - Pre-Indexed Metadata Fields

VoiceBase has useful metadata fields already pre-indexed for querying within the Analytic Database:

For instructions on attaching metadata on upload or existing mediaId, please see the metadata documentation

See the format for the callDetails metadata below:
*All fields are optional and can be left blank if certain values are not applicable to the uploaded recording.

{
  "title":"Test for MetaData with callDetails",
  "description":"File for CallDetails testing",
  "externalId":"CallbackPUT321412342315324563443",
  "externalVersion":"1.0",
  "callDetails": {
     "agent": {
        "externalId": "agentkqrw_7575",
        "fullName": "Roberto Reinger",
        "email": "[email protected]",
        "phone": "1-706-405-9676 x1425"
    },
    "agentSupervisor": {
        "externalId": "supervisorkqrw_77",
        "fullName": "Cristopher Dietrich",
        "email": "[email protected]",
        "phone": "244.899.9887"
    },
    "agentManager": {
        "externalId": "managerkqrw_11",
        "fullName": "Gilbert Krajcik",
        "email": "[email protected]",
        "phone": "719-534-9473 x2939"
    },
    "caller": {
        "externalId": "caller_22619",
        "fullName": "Julius Breitenberg",
        "email": "[email protected]",
        "phone": "220-202-0427 x31744"
    },
    "callDirection": "Inbound",
    "ani": "220-202-0427 x31744",
    "dnis": "1-706-405-9676 x1425",   
    "callStartTime": "2020-05-04T19:19:25.086Z"    
  }
}
  • title - Typically the filename of the file
  • description - Description of the file
  • externalId - A call id or assigned id (This id refer back to the recording platform or storage space of the file being uploaded)
  • externalVersion - the version to reference in an existing ETL schema (typically left as 1.0 unless otherwise instructed)
  • callDetails - metadata associated with the agent/supervisor/manager/customer
  • agent.externalId - an agent`s identification number
  • agent.fullName - an agent`s full name
  • agent.email - an agent`s e-mail
  • agent.phone- an agent`s phone number
  • agentSupervisor.externalId - an agent`s identification number
  • agentSupervisor.fullName - an agent`s full name
  • agentSupervisor.email- an agent`s e-mail
  • agentSupervisor.phone - an agent`s phone number
  • agentManager.externalId - an agent`s identification number
  • agentManager.fullName - an agent`s full name
  • agentManager.email - an agent`s e-mail
  • agentManager.phone - an agent`s phone number
  • caller.externalId - a caller or customer`s identification number
  • caller.fullName - a caller or customer`s full name
  • caller.email - a caller or customer`s e-mail
  • caller.phone - a caller or customer`s phone number
  • callDirection - the direction that the call was placed, Inbound or Outbound are the only acceptable fields
  • ani - Automatic Number Identification, the phone number that placed the call
  • dnis - Dialed Number Identification Service, the phone number dialed
  • callStartTime - the start time of the call listed in ISO 8601 format (*Note: The callstartTime MUST be submitted in the ISO 8601 otherwise the request will return an error)

Indexing Extended Metadata in the Analytics Database

VBQL and the Analytic Workbench have the ability to query and search through extended metadata if the fields have been indexed in the Analytics Database.

Below is a extended metadata sample that needs to be indexed:

{
    "title": "VoiceBase-recording.wav",
        "extended": {
            "source": "Outbound",
            "agent_behavior": "Bad",
            "CSAT": "Neutral",
            "call_type": "Retain",
            "call_driver": "Lounge Dirty",
            "call_disposition": "Call Successful",
            "agent_first_name": "Taylor",
            "agent_last_name": "Wood",
            "caller_first_name": "Rose",
            "caller_last_name": "Gomez",
            "customer_phone": "(212) 555-2773",
            "agent_id": "13478",
            "agent_start_date": "8/15/19T00:00.000Z",
            "manager_first_name": "Marina Garcia",
            "manager_id": "97259",
            "call_date": "2019-12-19",
            "call_time": "7:23:03",
            "uploadversion": "test"
        }
}

Indexing can be preformed in the Analytic Workbench. Navigate to the workbench in the VoiceBase Application and the follow the syntax of the following query to index the metadata in the Analytic Database:

ALTER table media DEFINE
metadata:source VARCHAR,
metadata:agent_behavior VARCHAR,
metadata:CSAT VARCHAR,
metadata:call_type VARCHAR,
metadata:call_driver VARCHAR,
metadata:call_disposition VARCHAR,
metadata:agent_first_name VARCHAR,
metadata:agent_last_name VARCHAR,
metadata:caller_first_name VARCHAR,
metadata:caller_last_name VARCHAR,
metadata:customer_phone VARCHAR,
metadata:agent_id VARCHAR,
metadata:agent_start_date VARCHAR,
metadata:manager_first_name VARCHAR,
metadata:manager_id VARCHAR,
metadata:call_date VARCHAR,
metadata:call_time VARCHAR,
metadata:uploadversion VARCHAR
2472

Now a sample query can be performed to search and check the metadata was properly indexed and we get confirmed hits:

select * from media where metadata:agent_first_name = 'Taylor'
2486

As shown in the screenshot, navigating in the Schema sidebar scrolling to metadata and selecting the appropriate field detail(in this example, agent_first_name) will also show indexed fields and their values and count of values stored in the Analytic Database.

Adding Categories

Creating a category in the Analytic Workbench is outlined in the VBQL documentation.

After creating a few categories, there are a few ways to Export these categories to a .csv and upload them into another VoiceBase account via the VoiceBase Application Portal.

Adding categories via the VoiceBase API

To define or update a category, make a PUT request against the /definition/categories/{categoryName} resource.

The JSON body of the request contains the category definition. For example:

{
  "categoryDescription": "This category looks for participants saying hello",
  "query": "SELECT * FROM media MATCH 'hello'",
  "notes": "Notes about creating or maintaining the category can be added here",
  "tags": [
    "hello",
    "greeting",
    "example"
  ],
  "version": "0.0.1"
}

Categories may alternatively be added using the "Publish" option in the Analytic Workbench.

The body of the category definition contains the following fields:

  • categoryName: The key name of the category. The name may not contain any spaces.
  • categoryDescription: The optional description of the category. The description is a string that is limited to ? characters including spaces.
  • query: A condition for evaluating a recording transcription and the accompanying metadata. The condition is written using the VBQL syntax.
  • notes : Optional information that helps the users and managers of the category further understand the category. The notes is a string that is limited to 4,000 characters including spaces.
  • tags : An optional array of terms that helps users and managers of the category further understand the category. Each tag is string that is limited to 64 characters with maximum of 32 tags. The tags are not used anywhere else in the VoiceBase platform.
  • version: An optional string value that helps the users and managers of the category further understand the version of the category. A version is unique to the account and is not used anywhere else in the VoiceBase platform.

Listing categories

To list defined categories, make a GET request against the /definition/categories resource.

For example, if the account has hello and goodbye categories defined, the response would be (fields omitted for clarity):

{
  "categories": [
    {
      "categoryName": "hello",
      "categoryDescription": "This category looks for participants saying hello"
    },
    {
      "categoryName": "goodbye",
      "categoryDescription": "This category looks for participants saying goodbye"
    }
  ]
}

Computing all categories

To enable categorization (computing categories), add a categories section to your configuration when POSTing to /media. The categories configuration is an array. To request that all categories be computed, add a single element consisting of a JSON object with the allCategories flag set to true.

{
   "publish":{
      "enableAnalyticIndexing":"true"
      },
  "categories": [
    { "allCategories": true }
  ]
}

The configuration contains the following fields:

  • categories: The configuration section for categorization
  • allCategories: A flag that indicates all categories should be computed

Computing specific categories

To enable categorization (computing categories) for a specific subset of categories, add a categories section to your configuration when POSTing to /media. The categories configuration is an array. For each category to compute, add an element consisting of a JSON
object with the categoryName key set to the name of the category.

For example:

{
   "publish":{
      "enableAnalyticIndexing":"true",
      },
  "categories": [
    { "categoryName": "hello" },
    { "categoryName": "goodbye" }
  ]
}

The configuration contains the following fields:

  • categories: The configuration section for categorization
  • categoryName: The name of a specific category to compute

Results for categories

Results of categorization (computing categories) are included with responses from GET /v3/media/{mediaId} API, and in callbacks.

For example:

{
  "categories": [
    { "categoryName": "hello", "categoryValue": 1 },
    { "categoryName": "goodbye", "categoryValue": 0 }
  ]
}

This section contains the following fields:

  • categories: the response section for categories
  • categoryName: the name of the category computed
  • categoryValue: the result of computing the category (0 = no match, 1 = match)

Note: Category values are represented as 0 and 1 rather than false and true
to help in aggregation use cases common in reporting.

Updated about 2 years ago