Skip to main content

Consuming Trackers with Trackers Management API


In Beta

This feature is in Beta. If you have questions or comments, email support@symbl.ai.

Trackers can be consumed via the Management API, which maintains these entities for you and stores the data on Symbl backend servers. The Management API provides an easy-to-consume REST interface for managing these entities.

All Trackers created using Management API are saved and can be reused for other operations such as PUT, UPDATE and DELETE.

To read about the capabilities of the Management API, see the Management API page.

You can also create, view, edit and delete Trackers via the Trackers Management UI. To access this feature, log in to theSymbl Platform

  • Using punctuations: You can only pass periods ., apostrophes ' and dashes - in the trackers vocabulary. Other punctuations like ?, ,, !, :are not allowed.
  • Vocabulary terms: You must add atleast 5 and a maximum of 50 vocabulary terms per Tracker.
  • Trackers limitation: You can create up to 500 trackers per account.

Before creating the Trackers, go through the Best Practices document to learn about the dos and don'ts of the Tracker vocabulary creation.

Step 1: Create Trackers​


Create Trackers by sending a POST request to the Trackers Management API endpoint:

Authentication​

Before using the API, ensure that you have your Authentication Token (AUTH_TOKEN) handy. To learn about how to get your auth token, see the step-by-step instructions on the Authentication page.

API Endpoint​

POST "https://api.symbl.ai/v1/manage/tracker"
Using Punctuations in Trackers Vocabulary

You can only pass the following punctuations in trackers vocabulary:

  • Periods .
  • Apostrophes '

Using any other punctuation mark such as ?, ,, !, : is not allowed.

You can define the phrases and keywords in the vocabulary of the request body as shown below:

{
"name":"Promotion Mention",
"vocabulary":[
"We have a special promotion going on if you book this before",
"I can offer you a discount of 10 20 percent you being a new customer for us",
"We have our month special this month",
"We have a sale right now on"
]
}

This creates a Tracker and returns the following response. Note that every Tracker has a unique id.

{
"tracker": {
"id": "4476908732794496",
"name": "Promotion Mention",
"vocabulary": [
"We have a special promotion going on if you book this before",
"I can offer you a discount of 10 20 percent you being a new customer for us",
"We have our month special this month",
"We have a sale right now on"
]
}
}

Step 2: Submit files using Async API with enableAllTrackers flag​


When you send a recorded audio, video or text using Async API, set enableAllTrackers=True and POST the file to Symbl.

Given below is an example of a POST request to Async Audio API for processing an audio recording with enableAllTrackers set to true. By default this is set to false.

API Endpoint​

POST "https://api.symbl.ai/v1/process/audio?enableAllTrackers=true"
Specifying the "enableAllTrackers" parameter in the request

The enableAllTrackers parameter must be sent mandatorily in the Async API to detect Trackers. The purpose of this flag is to enable detection of all the Trackers created with the Management API that maintains your entities with Symbl at the account level.

enableAllTrackers accepts a boolean value which must be passed in the Async APIs either as a query param or in the request body depending on which Async API you are using. See the complete list of Async APIs and how each accepts this parameter:

As a query-paramAsync Audio File API, Async Video File API.
In Request BodyAsync Audio URL API, Async Video URL API, Async Text API.

On successful processing of the job, you will get the conversationId and the jobId as shown below:

Response​

{
"conversationId": "6186250391257088",
"jobId": "78422976-e461-41cf-ba35-20397d16619e"
}

You can use the jobId to get the job status using the Job Status API.

note

Ensure that you wait for the job to complete before proceeding to Step 3.

Step 3: Get detected messages containing Trackers​


Using the conversationId from Step 2, you can GET the detected Trackers using the following endpoint:

API Endpoint​

GET "https://api.symbl.ai/v1/conversations/{{conversation_id}}/trackers-detected"

Response​

{
"type": "vocabulary",
"value": "Can you reiterate that one more time",
"messageRefs": [
{
"id": "6428676305453056",
"text": "So I am not showing that here but you can have that, you know, for particular sentence and, you know, then aggregate based on the whole conversation.",
"offset": -1
},
{
"id": "6035928066818048",
"text": "Give that intent and name and that's it.",
"offset": -1
}
],
"insightRefs": [
{
"text": "Yeah, and you So from sentiment analysis perspective, right?",
"offset": -1,
"type": "question",
"id": "5794360651153408"
}
]
}
Important

If the conversationId used in this Step is not processed with enableAllTrackers=true in the Async API, Trackers will not be detected. Using this flag as illustrated in Step 2 is mandatory.

Supported API Operations with Management API​

OperationEndpoint
Create TrackerPOST v1/manage/tracker
Create Trackers in BulkPOST v1/manage/trackers
Get Tracker with IDGETv1/manage/tracker/{trackerId}
Get Tracker with nameGET v1/manage/trackers?&name={trackerName}
Update TrackerPUTv1/manage/tracker/{trackerId}
Delete TrackerDELETEv1/manage/tracker/{trackerId}
Old Endpoint

The old endpoint for fetching Trackers (given below) is deprecated and not recommended to be used GET https://api.symbl.ai/v1/conversations/{conversationId}/trackers

Read more​