Create Trackers

🚧

In Beta

This feature is in Beta. If you have questions or comments, email [email protected].

We're working to improve this content! :star:

Use this operation to create Trackers for further processing.

For more information, see the following tutorials:

You can create several Trackers at the same time as a bulk operation. To learn how, see Create Trackers in Bulk. You can create up to 500 Trackers per account.

Before creating Trackers, it helps to review Best Practices - Trackers.

API Endpoint

POSThttps://api.symbl.ai/v1/manage/tracker

Request Headers

Header NameRequiredDescription
AuthorizationYesBearer <token> The token you get after completing the Authenticate process.
Content-TypeYesapplication/json
x-api-keyNoDEPRECATED.

For better tracking, use prominent keywords and phrases along with a few short sentences.

You can only pass the following punctuations in trackers vocabulary:

  • Periods .
  • Apostrophes '

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

Request Body

{
    "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"
    ]
}

Request Body Parameters

ParameterDescription
nameThis member specifies a uniquely identifiable name given to the group/set of phrases defined by the vocabulary member. It is case-sensitive which means that a Tracker can be created with the same name but with different cases.
vocabularyIt specifies the set of phrases or keywords that need to be tracked in a conversation. Note that the Trackers API finds the matches for the given vocabulary throughout a conversation. For example, the Tracker Voice Message shown above can be used for detecting if the entire conversation is itself an automated reply or contains “contextually similar” phrases in it.

Note that the vocabulary cannot have duplicate phrases/keywords.

This API accepts a request body size up to 1MB. Request bodies exceeding this limit will result in the error 413 - Request Entity Too Large error being returned in the response.

Response

{
    "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"
        ]
    }
}

tracker

This is the wrapper JSON Object which also contains a unique id associated with the Tracker entity that can be later used to instruct Symbl APIs to enhance that specific request with this Tracker for tracking keywords and phrases in a conversation.

This operation can only process one request at a time. To create multiple trackers in a single API call, see Create Trackers in Bulk.

You can also create, view, edit and delete Trackers via the Trackers Management UI. Log in to the Symbl Platform and see the Management API.

Error Codes

If the operation fails, it returns one of the following error codes:

Error CodeDescriptionResolution
409 - ConflictThe 409 response code specifies that the Tracker with that specific name already exists.Modify the name of the Tracker or Update the name of the existing Tracker with that name to resolve the error.
429 - Too many requestsThe 429 response code specifies that the number of concurrent requests surpassed the limit for the API (which is 1 API call at a time).Ensure that your system doesn’t make concurrent API calls that exceed this maximum limit.
400 - Bad RequestThe 400 response code specifies that the request body or the parameters have incorrect key names or their values have types that are different than the ones expected.Please read the message returned in the response to fix this error.
413 - Request Entity Too LargeThe 413 response code specifies that the size of the request body exceeds that of the maximum limit the API supports (which is 1MB).Please ensure that the size of the request body is under this limit to resolve this error.
500 - Internal Server ErrorThe 500 response code specifies that the server failed to handle the request.Please reach out to [email protected] if it persists after multiple attempts.
502 - Bad GatewayThe 502 response code specifies that the server failed to acknowledge the request.This may happen due to multiple reasons. Please reach out to [email protected] if it persists after multiple attempts.
504 - Gateway TimeoutThe 504 response code specifies that the server failed to respond within the timeout duration.Please reach out to mailto:[email protected] if it persists after multiple attempts.

You can create one-time use Trackers. See Create Trackers with Async API or Create Trackers with Streaming API.

We recommend that you create Trackers using the Management API because they are saved and can be reused.

Create Trackers in Bulk

You can create multiple Trackers in one array. If you need a large number of Trackers, creating them in bulk saves time and effort.

API Endpoint

POST https://api.symbl.ai/v1/manage/trackers

Request Headers

Header NameRequiredDescription
AuthorizationYesBearer <token> The token you get after completing the Authenticate process.
Content-TypeYesapplication/json
x-api-keyNoDEPRECATED.

Request Body

[{
    "name": "Voice Message",
    "vocabulary": [
        "At the tone please record",
        "Please leave message after tone",
        "Call back during normal office hours",
        "If you are calling about an emergency",
        "Our offices are currently closed",
        "Our repesentatives are unavailable at this time",
        "Please leave message",
        "start recording message",
        "Begin recording message",
        "sending you to his voicemail",
        "Leave Name and contact info",
        "Leave name and number",
        "I can call after",
        "Leave message with name",
        "leave message with number",
        "press to listen",
        "press to record",
        "press to send",
        "Record your message",
        "Return call ASAP",
        "return your call as soon as possible",
        "get back soon",
        "get back as quickly as possible",
        "Sorry we missed your call",
        "sorry we missed you",
        "You have reached office"
    ]
}]

The request body is an array of tracker entities, each of which is created separately during backend processing.

Request Parameters

ParameterDescription
nameThe name acts as a unique identifier assigned to the Tracker. It is case-sensitive which means that a Tracker can be created with the same name but with different cases.
vocabularyThe vocabulary contains a set of phrases/keywords which signify the context of the Tracker. In other words, these are a set of sentences that are commonly used while talking about the said Tracker in different contexts.

Note: The vocabulary cannot have duplicate phrases/keywords.

The request body has a size limit of 1MB. Request bodies exceeding this limit return an error: 413 - Request Entity Too Large error.

If you need to create Tracker entity(s) greater than this size, consider splitting it into multiple Tracker entities with the vocabulary of the Tracker split across these instances.

Response

{
    "trackers": [{
        "id": "7476908732794496",
        "name": "Voice Message",
        "vocabulary": [
            "At the tone please record",
            "Please leave message after tone",
            "Call back during normal office hours",
            "If you are calling about an emergency",
            "Our offices are currently closed",
            "Our repesentatives are unavailable at this time",
            "Please leave message",
            "start recording message",
            "Begin recording message",
            "sending you to his voicemail",
            "Leave Name and contact info",
            "Leave name and number",
            "I can call after",
            "Leave message with name",
            "leave message with number",
            "press to listen",
            "press to record",
            "press to send",
            "Record your message",
            "Return call ASAP",
            "return your call as soon as possible",
            "get back soon",
            "get back as quickly as possible",
            "Sorry we missed your call",
            "sorry we missed you",
            "You have reached office"
        ]
    }]
}

trackers

The trackers is the wrapper JSON array which contains all the Tracker entities.

It also contains a unique id associated with the Tracker entity that you can use later to enhance other API requests with this Tracker for tracking keywords and phrases.

You can only submit one request at a time.

Error Codes

If the operation fails, it returns one of the following error codes:

Error CodeDescriptionResolution
409 - ConflictThe 409 response code specifies that the Tracker with that specific name already exists.Modify the name of the Tracker or Update the name of the existing Tracker with that name to resolve the error.
429 - Too many requestsThe 429 response code specifies that the number of concurrent requests surpassed the limit for the API (which is 1 API call at a time).Ensure that your system doesn’t make concurrent API calls that exceed this limit.
400 - Bad RequestThe 400 response code specifies that the request body or the parameters have incorrect key names or their values have types that are different than the ones expected.Please read the message returned in the response to fix this error.
413 - Request Entity Too LargeThe 413 response code specifies that the size of the request body exceeds that of the maximum limit the API supports (which is 1 MB).Please ensure that the size of the request body is under this limit to resolve this error.
500 - Internal Server ErrorThe 500 response code specifies that the server failed to handle the request.Please reach out to [email protected] if it persists after multiple attempts.
502 - Bad GatewayThe 502 response code specifies that the server failed to acknowledge the request. This may happen due to multiple reasons.Please reach out to [email protected] if it persists after multiple attempts.
504 - Gateway TimeoutThe 504 response code specifies that the server failed to respond within the timeout duration.Please reach out to mailto:[email protected] if it persists after multiple attempts.

Best Practices

Best practices for creating Trackers:

  • Don't densely pack your vocabulary with information. For example: "What’s the price?"
  • Don't preface your information with lots of words that don’t convey meaning. For example: "I was wondering if you could tell me about your pricing structure."
  • Do use simple sentences or phrases. A short sentence: "I want to understand your product." A short phrase: "understand your product"
  • Avoid using complex sentence structure. For example: "I want to make sure that I have a full understanding of your product".

Tutorials