Classifiers¶
A classifier represents a machine speech model which is taught by example how to place a conversation into one of several categories. The categories are entirely up to the discretion of the user and are contained entirely to that model. Once a model is trained, it can be run on uncategorized calls using the Classify processor.
Conversations are most commonly created by either commanding a connection to join a Conference, or by uploading audio directly. If a Conversation has audio data available, it may be analyzed in various ways using the Classify processor or by classifying on a live call via Routines.
The Classifier object¶
Classification objects have the following properties:
| Property | Type | Description |
|---|---|---|
| Required Properties | ||
| model_name | string | The name of the model. Every model controlled by an account has a unique name provided by the user. |
| classes | list | A list of classes that a model can assign to a conversation. |
classes[].
class_name
|
string | The name of the class. |
classes[].
conversations[]
|
list | A list of strings, each of which is a conversation_id. If the original conversation is needed, it can be retrieved by id. |
Train classifiers¶
The train call instructs the model that a given conversation belongs to a class. If the model matching the provided name doesn’t exist, it is created. Similarly, if a class by that name doesn’t exist in that model, it is added.
Take care with model names
A user may only have one model with a given model name. If you train a model that already exists with that name, you will further train the additional model rather than create a new model like you might intend. If in doubt, you may list the classifiers already created and delete unneeded models.
Request¶
| url: | https://api.gridspace.com/v0/classifiers |
|---|---|
| method: | POST |
| content-type: | application/json |
The request body should be a JSON list that contains training events, that identify the model, a conversation, and the class to which that conversation belongs under that model.
| Property | Type | Description |
|---|---|---|
| Required Properties | ||
| training_events | list | A list of training events. |
| training_events[]. conversation_id | string | The ID of the conversation to train with. |
| training_events[]. model_name | string | The unique name of the model to train. |
| training_events[]. class_name | string | The name of the class to which the conversation belongs. |
A training event, together, signfies, “in this model, this conversation belongs to this class.”
Example¶
[
{
"conversation_id": "5d3dc73fc8cf34be",
"model_name": "reason_for_calling",
"class_name": "make_a_payment",
}
]
Response¶
If successful, the response body will contain the new Classification object.
List classifiers¶
Retrieve a list of all classifier objects associated with your account.
Request¶
| url: | https://api.gridspace.com/v0/classifiers |
|---|---|
| method: | GET |
Response¶
Returns a JSON list. Each entry in the list is a Classifier object.
Example¶
[
{
"model_name":"reason_for_calling",
"classes":[
{
"class_name":"make_a_payment",
"trained_conversations":[
"5d3dc73fc8cf34be",
"2af22188c5c97256",
"073aef6aad0883f8"
]
},
{
"class_name":"ask_for_quote",
"trained_conversations":[
"8dc810b13375d41e",
"20ebb5bbfa89d14d",
"27d0c77f68400230"
]
}
]
},
{
"model_name":"customer_satisfaction",
"classes":[
{
"class_name":"satisfied",
"trained_conversations":[
"5d3dc73fc8cf34be",
"2af22188c5c97256"
]
},
{
"class_name":"unsatisfied",
"trained_conversations":[
"8dc810b13375d41e"
]
}
]
}
]
Retrieve a classifier¶
Retrieve the details for a classifier.
Request¶
| url: | https://api.gridspace.com/v0/classifiers/:model_name |
|---|---|
| method: | GET |
Response¶
The response body contains a JSON formatted Classifier object.
Example¶
{
"model_name":"customer_value",
"classes":[
{
"class_name":"high_value",
"trained_conversations":[
"2af22188c5c97256",
"073aef6aad0883f8",
"5d3dc73fc8cf34be",
]
},
{
"class_name":"low_value",
"trained_conversations":[
"8dc810b13375d41e"
]
}
]
}