diff --git a/docs/conversation-api/concepts/trackers.md b/docs/conversation-api/concepts/trackers.md index 8be11abd..8bfc3c4d 100644 --- a/docs/conversation-api/concepts/trackers.md +++ b/docs/conversation-api/concepts/trackers.md @@ -119,12 +119,41 @@ The Trackers Management UI allows you to copy the Tracker ID with the copy butto **Trackers limitation**: You can create up to 500 Trackers per account. ::: -## Tutorials - -- [How to create a Tracker](/docs/management-api/trackers/overview#consuming-trackers-with-management-api) -- [How to create Trackers with Async API](/docs/management-api/trackers/overview#consuming-trackers-with-async-apis) -- [How to create Trackers with Streaming API](/docs/management-api/trackers/overview#consuming-trackers-with-streaming-api) -- [Viewing detected Trackers with Async API](/docs/async-api/code-snippets/track-phrases-in-a-conversation/#view-detected-trackers) -- [Detect Key Phrases with Streaming API](/docs/streamingapi/code-snippets/detect-key-phrases/#ontrackerresponse-json-response-example) -- [How to create Trackers in Bulk](/docs/management-api/trackers/create-tracker#create-trackers-in-bulk) -- [How to receive Trackers in Spanish with Streaming API](/docs/streamingapi/code-snippets/receive-trackers-in-spanish) \ No newline at end of file +Read more +--- + +
+
+

API Reference

+ +* [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) +* [`GET` v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +* [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) +* [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) +* [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) + +
+
+
+

Tutorials

+ + +* [How to create and use Trackers- Trackers Management API](/docs/tutorials/trackers/consuming-trackers-management-api/) +* [Creating Trackers with Async APIs](/docs/tutorials/trackers/create-trackers-async-api/) +* [Creating Trackers with Streaming API](/docs/tutorials/trackers/create-trackers-streaming-api/) +* [Using Trackers with Streaming API](/docs/tutorials/trackers/consuming-trackers-streaming-api/) +* [Viewing detected Trackers with Async API](/docs/async-api/code-snippets/track-phrases-in-a-conversation/#view-detected-trackers) +* [Detect Key Phrases with Streaming API](/docs/streamingapi/code-snippets/detect-key-phrases/#ontrackerresponse-json-response-example) +* [How to create Trackers in Bulk](/docs/management-api/trackers/create-tracker#create-trackers-in-bulk) +* [How to receive Trackers in Spanish with Streaming API](/docs/streamingapi/code-snippets/receive-trackers-in-spanish) + + +
+
+ +
+
+
+ +
+
\ No newline at end of file diff --git a/docs/management-api/trackers/create-tracker.md b/docs/management-api/trackers/create-tracker.md index 11c190ff..544c43c8 100644 --- a/docs/management-api/trackers/create-tracker.md +++ b/docs/management-api/trackers/create-tracker.md @@ -10,31 +10,14 @@ slug: /management-api/trackers/create-tracker/ This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. ::: -The endpoints given below creates a Tracker entity which can be consumed in Symbl APIs. +The endpoint given below creates a Tracker entity which can be consumed with Symbl APIs. Currently, the Tracker entities can be consumed with the [Async APIs](/docs/tutorials/trackers/create-trackers-async-api/) and [Streaming APIs](/docs/tutorials/trackers/create-trackers-streaming-api) only. Telephony API does not have support for Trackers yet. -Currently, the Tracker entities can be consumed in the [Async APIs](/docs/async-api/code-snippets/track-phrases-in-a-conversation) and [Streaming APIs](/docs/streamingapi/code-snippets/detect-key-phrases) only. Telephony API does not have support for Trackers yet. +You can create several Trackers at the same time as a bulk operation. To learn how, see [**Bulk Create Trackers**](#create-trackers-in-bulk) section. You can create up to 500 Trackers per account. -You can create Trackers in the following ways: - -- [Using Tracker Management API](#create-trackers-using-tracker-management-api) -- [Using Async APIs](#create-trackers-using-async-apis) -- [Using Streaming API](#create-trackers-using-streaming-api) - -:::info Trackers Management UI -You can create, view, edit and delete Trackers via the Trackers Management UI as well. To access this feature, log in to the [Symbl Platform](https://platform.symbl.ai/#/login). -::: - -You can also add several Trackers at the same time as a bulk operation. To learn how, see [**Bulk Create Trackers**](#create-trackers-in-bulk) section. You can create up to 500 Trackers per account. - -:::info Create Trackers with Management API -While you can create Trackers with Async or Streaming APIs, it is recommended that you create Trackers using Management API because Trackers created with Management APIs are saved and can be reused while the same is not possible with Async or Streaming APIs. +:::tip Best Practises +Before creating the Trackers, go through the [Best Practices](#best-practices) section to learn about how to create Trackers. ::: -## Create Trackers using Tracker Management API - ---- - -The API given below creates a Tracker using the Management API. ### API Endpoint @@ -108,8 +91,10 @@ This API accepts a request body size up to 1MB. Request bodies exceeding this li This is the wrapper JSON Object which additionally 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/phrases in a conversation. -:::info This API has a maximum concurrency of 1 request. If you wish to create multiple trackers in a single API call, go to [Create Trackers in Bulk](#bulk-create-trackers) section. + +:::info Trackers Management UI +You can also create, view, edit and delete Trackers via the Trackers Management UI as well. To access this feature, log in to the [Symbl Platform](https://platform.symbl.ai/#/login). ::: ### Error Codes @@ -125,6 +110,10 @@ Error Code | Description | Resolution `502 - Bad Gateway` | The 502 response code specifies that the server failed to acknowledge the request. | This may happen due to multiple reasons. Please reach out to support@symbl.ai if it persists after multiple attempts. `504 - Gateway Timeout` | The 504 response code specifies that the server failed to respond within the timeout duration. | Please reach out to support@symbl.ai if it persists after multiple attempts. +:::info Create Trackers with Management API +While you can create Trackers with Async or Streaming APIs, it is recommended that you create Trackers using Management API because Trackers created with Management APIs are saved and can be reused while the same is not possible with Async or Streaming APIs. +::: + ## Create Trackers in Bulk --- @@ -257,233 +246,27 @@ Error Code | Description | Resolution `502 - Bad Gateway` | The 502 response code specifies that the server failed to acknowledge the request. This may happen due to multiple reasons. | Please reach out to support@symbl.ai if it persists after multiple attempts. `504 - Gateway Timeout` | The 504 response code specifies that the server failed to respond within the timeout duration. | Please reach out to support@symbl.ai if it persists after multiple attempts. +### Best Practices -## Create Trackers using Async APIs ---- - -Symbl provides a diverse set of Async APIs based on Audio/Video or Textual content. For more details on Async APIs refer to the documentation [here](/docs/async-api/introduction). - -The Trackers once ingested via the request, will then try to detect these in the Conversation. Once the job is complete, you can fetch the Trackers from the Conversation API through the `/trackers` endpoint described below. - -### Async Audio File API -The Tracker entities should be passed in as a **query parameter** in the Async Audio API’s URL like shown below - -### API Endpoint - -```json -"https"://api.symbl.ai/v1/process/audio?trackers=[ - { - "name":"COVID-19", - "vocabulary":[ - "social distancing", - "cover your face with mask", - "vaccination" - ] - } -] -``` -### Request Headers - -Header Name | Required | Description ----------- | ------- | ------- | -```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). -```Content-Type ``` | Optional | `application/json` This header must contain the MIME Type of the audio file’s container. -```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). - -## Async Audio URL API - -The Tracker entities should be passed in as a member of the **request body** of the Async Audio URL API like shown below: - -### API Endpoint - -**POST `https://api.symbl.ai/v1/process/audio/url`** - -### Request Header - -Header Name | Required | Description ----------- | ------- | ------- | -```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). -```Content-Type ``` | Mandatory | `application/json` This header must contain the MIME Type of the audio file’s container. -```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). - - -### Request Body - -```json -{ - "url": "", - "confidenceThreshold": 0.6, - "timezoneOffset": 0, - "trackers": [ - { - "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" - ] - } - ] -} -``` -Notice that the trackers member follows the same structure as mentioned in the Trackers section above. - -### Response - -```json -{ - "conversationId": "5815170693595136", - "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" -} -``` - -### Async Video File API -The Tracker entities should be passed in as a **query parameter** in the Async Video API’s URL like shown below: - -### API Endpoint - -```json -"https"://api.symbl.ai/v1/process/video?trackers=[ - { - "name":"COVID-19", - "vocabulary":[ - "social distancing", - "cover your face with mask", - "vaccination" - ] - } -] -``` - -### Request Header - -Header Name | Required | Description ----------- | ------- | ------- | -```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). -```Content-Type ``` | Optional | `application/json` This header must contain the MIME Type of the audio file’s container. -```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). - -Notice that the trackers query parameter follows the same structure as mentioned in the Trackers section above. - -### Response - -```json -{ - "conversationId": "5815170693595136", - "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" -} -``` +Following are the best practices to be followed while creating Trackers: -### Async Video URL API -The Tracker entities should be passed in as a member of the request body of the Async Video URL API like shown below: +Dos' and Don'ts | Example | +---------- | ------- | +Densely pack your vocabulary with information | "What’s the price?" | +Don't preface your information with lots of words that don’t convey meaning | "I was wondering if you could tell me about your pricing structure". | +Use simple sentences or phrases | Short sentence: "I want to understand your product". Phrase: "understand your product" | +Avoid using complex sentence structure | "I want to make sure that I have a full understanding of your product". -### API Endpoint -**POST `https://api.symbl.ai/v1/process/video/url`** -### Request Headers - -Header Name | Required | Description ----------- | ------- | ------- | -```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). -```Content-Type ``` | Mandatory | `application/json` This header must contain the MIME Type application/json. -```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). - -### Request Body -```json -{ - "url": "", - "confidenceThreshold": 0.6, - "timezoneOffset": 0, - "trackers": [ - { - "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" - ] - } - ] -} -``` -Notice that the trackers member follows the same structure as mentioned in the Trackers section above. - -### Response - -```json -{ - "conversationId": "5815170693595136", - "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" -} -``` - -### Async Text API -The Tracker entities should be passed in as a member of the **request body** of the Async Text API like shown below: - -### API Endpoint - -**POST `https://api.symbl.ai/v1/process/text`** - - -### Request Headers - -Header Name | Required | Description ----------- | ------- | ------- | -```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). -```Content-Type ``` | Mandatory | `application/json` This header must contain the MIME Type application/json. -```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). - -### Request Body - -```json -{ - "name": "My Sales Conversation", - "conversationType": [ - "sales" - ], - "messages": [ - { - "payload": { - "content": "", - "contentType": "text/plain" - }, - "from": { - "name": "John", - "userId": "john@example.com" - } - } - ], - "trackers": [ - { - "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" - ] - } - ] -} -``` -Notice that the trackers member follows the same structure as the Trackers section above. - -### Response - -```json -{ - "conversationId": "5815170693595136", - "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" -} -``` - -## Create Trackers using Streaming API - -You can create and consume Trackers in real-time using the Streaming APIs. +## Tutorials +--- -To view the detailed documentation go to the Trackers with [Streaming API](/docs/streaming-api/code-snippets/consume-trackers-with-streaming-api) page. +You might find the following tutorials useful: +- [How to create and use Trackers- Trackers Management API](/docs/tutorials/trackers/consuming-trackers-management-api/) +- [Creating Trackers with Async APIs](/docs/tutorials/trackers/create-trackers-async-api/) +- [Creating Trackers with Streaming API](/docs/tutorials/trackers/create-trackers-streaming-api/) +- [Using Trackers with Async API](/docs/tutorials/trackers/consuming-trackers-async-api//) +- [Using Trackers with Streaming API](/docs/tutorials/trackers/consuming-trackers-streaming-api/) diff --git a/docs/management-api/trackers/delete-tracker.md b/docs/management-api/trackers/delete-tracker.md index 133ac2e6..601fd6fc 100644 --- a/docs/management-api/trackers/delete-tracker.md +++ b/docs/management-api/trackers/delete-tracker.md @@ -11,15 +11,12 @@ slug: /management-api/trackers/delete-tracker/ This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. ::: -The Delete Tracker API will delete the Tracker entity against the `trackerId` provided. +This API will delete the Tracker entity against the `trackerId` provided. -:::info -Currently, the Tracker entities can be consumed in the [Async APIs](/docs/async-api/introduction) only. Support for the other APIs will be added soon. -::: - -:::note Trackers Management UI +:::info Trackers Management UI You can create, view, edit and delete Trackers via the Trackers Management UI as well. To access this feature, log in to the[Symbl Platform](https://platform.symbl.ai/#/login) ::: + ### API Endpoint **DELETE `https://api.symbl.ai/v1/manage/tracker/{trackerId}`** diff --git a/docs/management-api/trackers/get-tracker.md b/docs/management-api/trackers/get-tracker.md index ef3d4630..ecd523f6 100644 --- a/docs/management-api/trackers/get-tracker.md +++ b/docs/management-api/trackers/get-tracker.md @@ -11,15 +11,17 @@ slug: /management-api/trackers/get-tracker/ This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. ::: -:::note Trackers Management UI -You can create, view, edit and delete Trackers via the Trackers Management UI as well. To access this feature, log in to the[Symbl Platform](https://platform.symbl.ai/#/login) -::: - You can GET Trackers in the following ways with the Management API: - [GET All Trackers](#get-all-trackers) - [GET Tracker by ID](#get-tracker-by-id) - [GET Tracker by name](#get-tracker-by-name) +:::info Trackers Management UI +You can create, view, edit and delete Trackers via the Trackers Management UI as well. To access this feature, log in to the[Symbl Platform](https://platform.symbl.ai/#/login) +::: + + + ## GET All Trackers This API call lists all the Trackers registered to the Management API at the account level. diff --git a/docs/management-api/trackers/overview.md b/docs/management-api/trackers/overview.md index 2fd23c24..95831dcb 100644 --- a/docs/management-api/trackers/overview.md +++ b/docs/management-api/trackers/overview.md @@ -1,7 +1,7 @@ --- id: trackers-overview -title: Using Trackers API (Beta) -sidebar_label: Overview +title: Trackers API (Beta) +sidebar_label: Introduction slug: /management-api/trackers/overview/ --- import Tabs from '@theme/Tabs'; @@ -13,382 +13,23 @@ import TabItem from '@theme/TabItem'; This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. ::: -This section contains step-by-step instructions on how to create and use Trackers.
+You can use the Trackers API with the following:
-This page provides information about: - -- [Consuming Trackers with Management APIs](#consuming-trackers-with-management-api) -- [Consuming Trackers with Async APIs](#consuming-trackers-with-async-apis) -- [Consuming Trackers with Streaming API](#consuming-trackers-with-streaming-api) +- [Trackers with Management APIs](/docs/tutorials/trackers/consuming-trackers-management-api/) +- [Trackers with Async APIs](/docs/tutorials/trackers/consuming-trackers-async-api/) +- [Trackers with Streaming API](/docs/tutorials/trackers/consuming-trackers-streaming-api/) :::info Create Trackers with Management API While you can create Trackers with Async or Streaming APIs, it is recommended that you create Trackers using Management API because Trackers created with Management APIs are saved and can be reused while the same is not possible with Async or Streaming APIs. ::: -## Consuming Trackers with Management API ---- - -Trackers can be consumed via the Management API, which takes the onus of maintaining these entities from the developer and shifts it to Symbl’s backend. 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](/docs/management-api/introduction) page. - -:::note Trackers Management UI -You can also create, view, edit and delete Trackers via the Trackers Management UI. To access this feature, log in to the[Symbl Platform](https://platform.symbl.ai/#/login) - -- **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. -::: - -### Step 1: Create Trackers ---- - - Create Trackers by sending a `POST` request to the Trackers Management API endpoint given below: - -```shell -POST "https://api.symbl.ai/v1/manage/tracker" -``` - -:::note 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: - -```json -{ - "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`. - -```json -{ - "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](http://localhost:3000/docs/async-api/introduction), 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`. - -```shell -POST "https://api.symbl.ai/v1/process/audio?enableAllTrackers=true" -``` -:::note 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](#tracker-consumption-with-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-param | Async Audio File API, Async Video File API. -In Request Body | Async Audio URL API, Async Video URL API, Async Text API. -::: - -On successful processing by the above mentioned API, you will get the `conversationId` and the `jobId` as shown below: - -#### Response -```json -{ - "conversationId": "6186250391257088", - "jobId": "78422976-e461-41cf-ba35-20397d16619e" -} -``` -You can use the `jobId` to get the job status using the [Job Status API.](/docs/async-api/overview/jobs-api/#get-job-status) - -:::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 Trackers for the conversation. - -```shell -GET "https://api.symbl.ai/v1/conversations/{{conversation_id}}/trackers-detected" -``` -#### Response - -```json -{ - "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" - } - ] -} -``` -:::caution 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 +## Endpoints Operation | Endpoint ---------- | ------- Create Tracker | [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) -Create Trackers in Bulk | [`POST` v1/manage/trackers](/management-api/trackers/create-tracker/#create-trackers-in-bulk) -Get Tracker with ID| [`GET`v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +Create Trackers in Bulk | [`POST` v1/manage/trackers](/management-api/trackers/create-tracker#bulk-create-trackers-api) +Get Tracker with ID| [`GET` v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) Get Tracker with name | [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) Update Tracker| [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) -Delete Tracker| [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) - - -## Consuming Trackers with Async APIs - -### Step 1: Create a Tracker ---- - -The first step is to create a Tracker with a set of phrases and keywords using Async APIs. - -:::tip -If you want to create multiple trackers in bulk, use [Trackers Management API for bulk creation](/docs/management-api/trackers/create-tracker#create-trackers-in-bulk). The Trackers Management API handles Trackers at your account level and is recommended for usecases where where you want to use multiple Trackers. -::: - -Given below is an example of an [Async Audio URL API](/docs/management-api/trackers/create-tracker#async-audio-url-api): - -#### API Endpoint - -```shell -POST https://api.symbl.ai/v1/process/audio/url -``` - -#### Request Body -```json -{ - "url": "", - "confidenceThreshold": 0.6, - "timezoneOffset": 0, - "trackers": [ - { - "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" - ] - } - ] -} -``` - -#### Response - -This creates a Tracker and returns the following response. Note that every Tracker has a unique `id`. - -```json -{ - "conversationId": "5815170693595136", - "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" -} -``` -:::note -To create Trackers with Async APIs, see detailed documentation in the links given below. -- [Create Trackers- Async Audio File API](/docs/management-api/trackers/create-tracker#async-audio-file-api) -- [Create Trackers- Async Audio URL API](/docs/management-api/trackers/create-tracker#async-audio-url-api) -- [Create Trackers- Async Video File API](/docs/management-api/trackers/create-tracker#async-video-file-api) -- [Create Tracker- Async Video URL API](/docs/management-api/trackers/create-tracker#async-video-url-api) -- [Create Trackers- Async Text API](/docs/management-api/trackers/create-tracker#async-text-api) -::: - -After creating the Tracker, you can: - -👉   [Verify that all the trackers has been added by making a `GET` request.](/docs/management-api/trackers/get-tracker) - -👉   [If any Trackers need to be updated, send a `PUT` request.](/docs/management-api/trackers/update-tracker) - -### Step 2: Get the detected messages containing Trackers ---- - -Using the `conversation_id` you get from Step 1, you can `GET` the Trackers for the conversation. - -```shell -GET "https://api.symbl.ai/v1/conversations/{{conversation_id}}/trackers-detected" -``` -#### Response - -```json -[ - { - "id": "4527907378937856", - "name": "Promotion Mention", - "matches": [ - { - "messageRefs": [ - { - "id": "4670860273123328", - "text": "We're running a sale right now", - "offset": -1 - } - ], - "type": "vocabulary", - "value": "run sale", - "insightRefs": [] - } - ] - }, - ... -] -``` - -### Detecting Trackers with Async API - -You can also use the Async API to detect Trackers by sending a list of Tracker IDs of previously created trackers (from the Management API). The Trackers will be searched in the submitted Async API request containing the conversation. - -#### Example -In the example given below, we will send the following trackers IDs in the Async API request assuming they were already created: -```shell -"trackers": [ - { - "id": "5123033831841280" - }, - { - "id": "6174043823841420" - }, -``` -#### Full Request Sample -Given below is an example of an Async Text API call sent with Tracker IDs: - -```shell -curl --location --request POST 'https://api.symbl.ai/v1/process/text' \ ---header "Authorization: Bearer $AUTH_TOKEN" \ -# Set your access token here. See https://docs.symbl.ai/docs/developer-tools/authentication ---header 'Content-Type: application/json' \ ---data-raw '{ - "name": "Afternoon Business Meeting", - "detectPhrases": true, - "confidenceThreshold": 0.6, - "entities": [ - { - "customType": "Company Executives", - "value": "Marketing director", - "text": "Marketing director" - } - ], - "detectEntities": true, - "messages": [], - "trackers": [ - { - "id": "5123033831841280" - }, - { - "id": "6174043823841420" - }, - ] -}' -``` - -## Consuming Trackers with Streaming API ---- - -Below is an example that shows how to pass Trackers in the config object for the `startRealtimeRequest` of the Symbl’s JS SDK. This example also shows how to consume the results of the detected Trackers in real-time. - -```js -const connection = await sdk.startRealtimeRequest({ - id, - insightTypes: ['action_item', 'question'], - trackers: [ - { - 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" - ] - } - ], - config: { - meetingTitle: "My Meeting", - confidenceThreshold: 0.7, - languageCode: "en-US", - sampleRateHertz: 48000, - trackers: { - "interimResults": true - } - }, - speaker: { - // Optional, if not specified, will simply not send an email in the end. - userId: "john@example.com", // Update with valid email - name: "John", - }, - handlers: { - onTrackerResponse: (data) => { - // When a tracker is detected in real-time - console.log('onTrackerResponse', JSON.stringify(data, null, 2)); - if (!!data) { - data.forEach((tracker) => { - console.log(`Detected Tracker Name: ${tracker.name}`); - console.log(`Detected Matches`); - tracker.matches.forEach((match) => { - console.log(`Tracker Value: ${match.value}`); - console.log(`Messages detected against this Tracker`); - match.messageRefs.forEach((messageRef) => { - console.log(`Message ID: ${messageRef.id}`); - console.log(`Message text for which the match was detected: ${messageRef.text}`); - console.log(`\n`); - }); - console.log(`\n\n`); - - console.log(`Insights detected against this Tracker`); - match.messageRefs.forEach((insightRef) => { - console.log(`Insight ID: ${insightRef.id}`); - console.log(`Insight text for which the match was detected: ${insightRef.text}`); - console.log(`Insight Type: ${insightRef.type}`); - console.log(`\n`); - }); - console.log(`\n\n`); - }); - }); - } - }, - }, -}) -``` -For detailed description of the parameters, see [Streaming API for Trackers](/docs/streaming-api/code-snippets/consume-trackers-with-streaming-api) documentation. - -:::caution 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` -::: \ No newline at end of file +Delete Tracker| [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) \ No newline at end of file diff --git a/docs/management-api/trackers/update-tracker.md b/docs/management-api/trackers/update-tracker.md index 5ec5b219..b9ba88b7 100644 --- a/docs/management-api/trackers/update-tracker.md +++ b/docs/management-api/trackers/update-tracker.md @@ -13,7 +13,7 @@ This feature is in the Beta phase. If you have any questions, ideas or suggestio To update an existing Tracker, send a PUT Tracker API request with Management API. This updates a Tracker entity against the `trackerId` which can be consumed in Symbl APIs. -:::note Trackers Management UI +:::info Trackers Management UI You can create, view, edit and delete Trackers via the Trackers Management UI as well. To access this feature, log in to the[Symbl Platform](https://platform.symbl.ai/#/login) ::: diff --git a/docs/streamingapi/reference/reference.md b/docs/streamingapi/reference/reference.md index 2181eb2c..87e2d1b7 100644 --- a/docs/streamingapi/reference/reference.md +++ b/docs/streamingapi/reference/reference.md @@ -379,7 +379,8 @@ const connection = await sdk.startRealtimeRequest({ confidenceThreshold: 0.7, sampleRateHertz: 48000, trackers: { - "interimResults": true + "interimResults": true, + "enableAllTrackers": true } }, speaker: { @@ -437,7 +438,9 @@ Let’s go over all the parameters passed in the configuration object in the abo c. `sampleRateHertz`: The sample rate of the incoming audio data which is being pushed to Symbl. - d. `trackers`: `{ interimResults }`: The `interimResults` flag tells Symbl to send the `tracker` results as soon as they are detected. If false, the `tracker` results are detected for the finalized transcription responses. + d. `trackers.interimResults`| The `interimResults` flag tells Symbl to send the tracker results as soon as they are detected. If `false`, the tracker results are detected for the finalized transcription responses. + + e. `trackers.enableAllTrackers`| The `enableAllTrackers` parameter must be sent to detect all the 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. 5. `speaker`: The details of the speaker in this conversation. @@ -449,6 +452,45 @@ Let’s go over all the parameters passed in the configuration object in the abo a. `onTrackerResponse`: This function is invoked when Symbl detects a Tracker in real-time. The structure of the **Tracker** object is shown in the above code snippet. +### Tracker Response + +The following reponse is returned when Tracker object is passed in the Streaming API: + +```js +"trackers":[ + { + "name":"Documents Tracker", + "matches":[ + { + "type":"vocabulary", + "value":"Documents", + "messageRefs":[ + { + "id":"53867534-0459-4d22-b590-984ee82166aa", + "text":"Anyways, so I will submit documents tomorrow.", + "offset":26 + }, + { + "id":"4d20d90c-50a7-4594-bb10-2995dcd4bbd1", + "text":"I will submit documents tomorrow.", + "offset":14 + } + ], + } +``` + +Field Name | Description +---------- | ------- | +`name` | The name of the Tracker detected | +`matches` | Array of match objects which contain the references to messages and insights detected in that conversation. | +`type` | The match type for the text. In the above example, the match is of type vocabulary. | +`value` | The textual value of the vocabulary for which this match was detected. | +`messageRefs` | Array of messages for which this Tracker was detected. | +`messageRefs.id`| The unique identifier of the message. | +`messageRefs.text` | The text body of the message. | +`messageRefs.offset`| The closest match of the text in the message. Offset of -1 means that an exact match for that specific vocabulary wasn’t found and this was the similar match. An offset greater than 0 indicates an exact match for the tracker in the payload of the message. + + ### Streaming API Logs You can view the logs of your Streaming API request on your Symbl Platform account. To view the logs, sign in to [Symbl Platform](https://platform.symbl.ai/#/login). The logs provide the following: diff --git a/docs/tutorials/trackers/consuming-trackers-async-api.md b/docs/tutorials/trackers/consuming-trackers-async-api.md new file mode 100644 index 00000000..3e891660 --- /dev/null +++ b/docs/tutorials/trackers/consuming-trackers-async-api.md @@ -0,0 +1,210 @@ +--- +id: consuming-trackers-async-api +title: Consuming Trackers with Async API +sidebar_label: Consuming Trackers with Async API +slug: /tutorials/trackers/consuming-trackers-async-api/ +--- + +--- +:::note In Beta Phase +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + +To use Trackers with Async API, follow the steps given below: + +### Step 1: Create a Tracker +--- + +The first step is to create a Tracker with a set of phrases and keywords using Async APIs. + +:::tip +If you want to create multiple trackers in bulk, use [Trackers Management API for bulk creation](/docs/management-api/trackers/create-tracker#create-trackers-in-bulk). The Trackers Management API handles Trackers at your account level and is recommended for usecases where where you want to use multiple Trackers. +::: + +:::tip Best Practises +Before creating the Trackers, go through the [Best Practices](#best-practices) section to learn about how to create Trackers. +::: + +Given below is an example of an [Async Audio URL API](/docs/management-api/trackers/create-tracker#async-audio-url-api): + +#### API Endpoint + +```shell +POST https://api.symbl.ai/v1/process/audio/url +``` + +#### Request Body +```json +{ + "url": "", + "confidenceThreshold": 0.6, + "timezoneOffset": 0, + "trackers": [ + { + "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" + ] + } + ] +} +``` + +#### Response + +This creates a Tracker and returns the following response. Note that every Tracker has a unique `id`. + +```json +{ + "conversationId": "5815170693595136", + "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" +} +``` +:::note +To create Trackers with Async APIs, see detailed documentation in the links given below. +- [Create Trackers- Async Audio File API](/docs/management-api/trackers/create-tracker#async-audio-file-api) +- [Create Trackers- Async Audio URL API](/docs/management-api/trackers/create-tracker#async-audio-url-api) +- [Create Trackers- Async Video File API](/docs/management-api/trackers/create-tracker#async-video-file-api) +- [Create Tracker- Async Video URL API](/docs/management-api/trackers/create-tracker#async-video-url-api) +- [Create Trackers- Async Text API](/docs/management-api/trackers/create-tracker#async-text-api) +::: + +After creating the Tracker, you can: + +👉   [Verify that all the trackers has been added by making a `GET` request.](/docs/management-api/trackers/get-tracker) + +👉   [If any Trackers need to be updated, send a `PUT` request.](/docs/management-api/trackers/update-tracker) + +### Step 2: Get the detected messages containing Trackers +--- + +Using the `conversation_id` you get from Step 1, you can `GET` the Trackers for the conversation. + +```shell +GET "https://api.symbl.ai/v1/conversations/{{conversation_id}}/trackers-detected" +``` +#### Response + +```json +[ + { + "id": "4527907378937856", + "name": "Promotion Mention", + "matches": [ + { + "messageRefs": [ + { + "id": "4670860273123328", + "text": "We're running a sale right now", + "offset": -1 + } + ], + "type": "vocabulary", + "value": "run sale", + "insightRefs": [] + } + ] + }, + ... +] +``` + +### Detecting Trackers with Async API + +You can also use the Async API to detect Trackers by sending a list of Tracker IDs of previously created trackers (from the Management API). The Trackers will be searched in the submitted Async API request containing the conversation. + +#### Example +In the example given below, we will send the following trackers IDs in the Async API request assuming they were already created: +```shell +"trackers": [ + { + "id": "5123033831841280" + }, + { + "id": "6174043823841420" + }, +``` +#### Full Request Sample +Given below is an example of an Async Text API call sent with Tracker IDs: + +```shell +curl --location --request POST 'https://api.symbl.ai/v1/process/text' \ +--header "Authorization: Bearer $AUTH_TOKEN" \ +# Set your access token here. See https://docs.symbl.ai/docs/developer-tools/authentication +--header 'Content-Type: application/json' \ +--data-raw '{ + "name": "Afternoon Business Meeting", + "detectPhrases": true, + "confidenceThreshold": 0.6, + "entities": [ + { + "customType": "Company Executives", + "value": "Marketing director", + "text": "Marketing director" + } + ], + "detectEntities": true, + "messages": [], + "trackers": [ + { + "id": "5123033831841280" + }, + { + "id": "6174043823841420" + }, + ] +}' +``` +:::caution 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` +::: + +### Best Practices + +Following are the best practices to be followed while creating Trackers: + +Dos' and Don'ts | Example | +---------- | ------- | +Densely pack your vocabulary with information | "What’s the price?" | +Don't preface your information with lots of words that don’t convey meaning | "I was wondering if you could tell me about your pricing structure". | +Use simple sentences or phrases | Short sentence: "I want to understand your product". Phrase: "understand your product" | +Avoid using complex sentence structure | "I want to make sure that I have a full understanding of your product". + + +## Read more +--- +
+
+

API Reference

+ +* [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) +* [`GET` v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +* [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) +* [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) +* [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) + +
+
+
+

Tutorials

+ + +* [How to create and use Trackers- Trackers Management API](/docs/tutorials/trackers/consuming-trackers-management-api/) +* [Creating Trackers with Async APIs](/docs/tutorials/trackers/create-trackers-async-api/) +* [Creating Trackers with Streaming API](/docs/tutorials/trackers/create-trackers-streaming-api/) +* [Using Trackers with Streaming API](/docs/tutorials/trackers/consuming-trackers-streaming-api/) + + +
+
+ +
+
+
+ +
+
\ No newline at end of file diff --git a/docs/tutorials/trackers/consuming-trackers-streaming-api.md b/docs/tutorials/trackers/consuming-trackers-streaming-api.md new file mode 100644 index 00000000..02f27e8a --- /dev/null +++ b/docs/tutorials/trackers/consuming-trackers-streaming-api.md @@ -0,0 +1,199 @@ +--- +id: consuming-trackers-streaming-api +title: Consuming Trackers with Streaming API +sidebar_label: Consuming Trackers with Streaming API +slug: /tutorials/trackers/consuming-trackers-streaming-api/ +--- + +--- +:::note In Beta Phase +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + + +To pass a Tracker in the Streaming API, utilize the `config` object. + +Given below is an example that shows how to pass Trackers in the `config` object for the `startRealtimeRequest` of the Symbl’s JS SDK. This example also shows how to consume the results of the detected Trackers in real-time. + +:::info Using Enable All Trackers functionality +Additionally, you can pass the parameter `enableAllTrackers` in the `config` object for `trackers` to use all the Trackers linked to your Symbl account. See the sample below to understand how to pass this. +::: + +:::tip Best Practises +Before creating the Trackers, go through the [Best Practices](#best-practices) section to learn about how to create Trackers. +::: + +```js +const connection = await sdk.startRealtimeRequest({ + id, + insightTypes: ['action_item', 'question'], + trackers: [ + { + 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" + ] + } + ], + config: { + meetingTitle: "My Meeting", + confidenceThreshold: 0.7, + languageCode: "en-US", + sampleRateHertz: 48000, + trackers: { + "interimResults": true, + "enableAllTrackers": true + } + }, + speaker: { + // Optional, if not specified, will simply not send an email in the end. + userId: "john@example.com", // Update with valid email + name: "John", + }, + handlers: { + onTrackerResponse: (data) => { + // When a tracker is detected in real-time + console.log('onTrackerResponse', JSON.stringify(data, null, 2)); + if (!!data) { + data.forEach((tracker) => { + console.log(`Detected Tracker Name: ${tracker.name}`); + console.log(`Detected Matches`); + tracker.matches.forEach((match) => { + console.log(`Tracker Value: ${match.value}`); + console.log(`Messages detected against this Tracker`); + match.messageRefs.forEach((messageRef) => { + console.log(`Message ID: ${messageRef.id}`); + console.log(`Message text for which the match was detected: ${messageRef.text}`); + console.log(`\n`); + }); + console.log(`\n\n`); + + console.log(`Insights detected against this Tracker`); + match.messageRefs.forEach((insightRef) => { + console.log(`Insight ID: ${insightRef.id}`); + console.log(`Insight text for which the match was detected: ${insightRef.text}`); + console.log(`Insight Type: ${insightRef.type}`); + console.log(`\n`); + }); + console.log(`\n\n`); + }); + }); + } + }, + }, +}) +``` +### Parameter Description + +Let’s go over all the parameters passed in the configuration object in the above function: + +Field | Required | +---------- | ------- | +`id` | A unique UUID that represents this WebSocket API Session. +`insightType` | The types of Insights to be detected for this Conversation. +`trackers`| The Trackers to be detected in real-time for that Conversation. Follows the same structure as described in the [Trackers section](/docs/management-api/trackers/create-tracker#sample-request-body). +`config`| The config object encapsulates the metadata for the WebSocket API’s session. +`meetingTitle`| The title for this conversation/meeting. +`confidenceThreshold` | The insights having confidence scores greater than this threshold will be the ones detected for the Conversation. +`languageCode` | The language-code in BCP-47 format. +`sampleRateHertz`| The sample-rate of the incoming audio data which is being pushed to Symbl. +`trackers.interimResults`| The `interimResults` flag tells Symbl to send the tracker results as soon as they are detected. If `false`, the tracker results are detected for the finalized transcription responses. +`trackers.enableAllTrackers`| The `enableAllTrackers` parameter must be sent to detect all the 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. +`speaker` | The details of the speaker in this Conversation +`userId`| Unique identifier to represent the User. +`name` | The name of the User. +`handlers` | The object encapsulating the call-back functions to be invoked on detection of those specific entities. For more information on various such handlers, check out this [link](/docs/javascript-sdk/tutorials/receive-ai-insights-from-your-computer/). +`onTrackerResponse`| This function is invoked when Symbl detects a Tracker in real-time. The structure of the Tracker object is shown in the above code snippet. + +## Response + +```js +"trackers":[ + { + "name":"Testing Tracker Dev User 75", + "matches":[ + { + "type":"vocabulary", + "value":"Documents", + "messageRefs":[ + { + "id":"53867534-0459-4d22-b590-984ee82166aa", + "text":"Anyways, so I will submit documents tomorrow.", + "offset":26 + }, + { + "id":"4d20d90c-50a7-4594-bb10-2995dcd4bbd1", + "text":"I will submit documents tomorrow.", + "offset":14 + } + ], + "insightRefs":[ + { + "id":"4d20d90c-50a7-4594-bb10-2995dcd4bbd1", + "text":"James needs to submit documents tomorrow.", + "type":"action_item", + "offset":22 + } + ] + } +``` +Field Name | Description +---------- | ------- | +`name` | The name of the Tracker detected | +`matches` | Array of match objects which contain the references to messages and insights detected in that conversation. | +`type` | The match type for the text. In the above example, the match is of type vocabulary. | +`value` | The textual value of the vocabulary for which this match was detected. | +`messageRefs` | Array of messages for which this Tracker was detected. | +`messageRefs.id`| The unique identifier of the message. | +`messageRefs.text` | The text body of the message. | +`messageRefs.offset`| The closest match of the text in the message. Offset of -1 means that an exact match for that specific vocabulary wasn’t found and this was the similar match. An offset greater than 0 indicates an exact match for the tracker in the payload of the message. + + +### Best Practices + +Following are the best practices to be followed while creating Trackers: + +Dos' and Don'ts | Example | +---------- | ------- | +Densely pack your vocabulary with information | "What’s the price?" | +Don't preface your information with lots of words that don’t convey meaning | "I was wondering if you could tell me about your pricing structure". | +Use simple sentences or phrases | Short sentence: "I want to understand your product". Phrase: "understand your product" | +Avoid using complex sentence structure | "I want to make sure that I have a full understanding of your product". + + +## Read more +--- +
+
+

API Reference

 + +* [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) +* [`GET` v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +* [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) +* [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) +* [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) + +
+
+
+

Tutorials

 + + +* [How to create and use Trackers- Trackers Management API](/docs/tutorials/trackers/consuming-trackers-management-api/) +* [Creating Trackers with Async APIs](/docs/tutorials/trackers/create-trackers-async-api/) +* [Creating Trackers with Streaming API](/docs/tutorials/trackers/create-trackers-streaming-api/) +* [Using Trackers with Async API](/docs/tutorials/trackers/consuming-trackers-async-api/) + + +
+
+ +
+
+
+ +
+
diff --git a/docs/tutorials/trackers/consuming-trackers.md b/docs/tutorials/trackers/consuming-trackers.md new file mode 100644 index 00000000..6a3cf454 --- /dev/null +++ b/docs/tutorials/trackers/consuming-trackers.md @@ -0,0 +1,214 @@ +--- +id: consuming-trackers-management-api +title: How to Create and Use Trackers- Trackers Management API +sidebar_label: Creating and using Trackers- Trackers Management API +slug: /tutorials/trackers/consuming-trackers-management-api/ +--- + +--- +:::note In Beta Phase +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + + +Trackers can be consumed via the Management API, which takes the onus of maintaining these entities from the developer and shifts it to Symbl’s backend. 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](/docs/management-api/introduction) page. + +:::note Trackers Management UI +You can also create, view, edit and delete Trackers via the Trackers Management UI. To access this feature, log in to the[Symbl Platform](https://platform.symbl.ai/#/login) + +- **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. +::: + +### Step 1: Create Trackers +--- + + Create Trackers by sending a `POST` request to the Trackers Management API endpoint given below: + +```shell +POST "https://api.symbl.ai/v1/manage/tracker" +``` + +:::note 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. +::: + +:::tip Best Practises +Before creating the Trackers, go through the [Best Practices](#best-practices) section to learn about how to create Trackers. +::: + +You can define the phrases and keywords in the **vocabulary** of the request body as shown below: + +```json +{ + "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`. + +```json +{ + "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](http://localhost:3000/docs/async-api/introduction), 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`. + +```shell +POST "https://api.symbl.ai/v1/process/audio?enableAllTrackers=true" +``` +:::note 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](#tracker-consumption-with-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-param | Async Audio File API, Async Video File API. +In Request Body | Async Audio URL API, Async Video URL API, Async Text API. +::: + +On successful processing by the above mentioned API, you will get the `conversationId` and the `jobId` as shown below: + +#### Response +```json +{ + "conversationId": "6186250391257088", + "jobId": "78422976-e461-41cf-ba35-20397d16619e" +} +``` +You can use the `jobId` to get the job status using the [Job Status API.](/docs/async-api/overview/jobs-api/#get-job-status) + +:::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 Trackers for the conversation. + +```shell +GET "https://api.symbl.ai/v1/conversations/{{conversation_id}}/trackers-detected" +``` +#### Response + +```json +{ + "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" + } + ] +} +``` +:::caution 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 + +Operation | Endpoint +---------- | ------- +Create Tracker | [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) +Create Trackers in Bulk | [`POST` v1/manage/trackers](/management-api/trackers/create-tracker/#create-trackers-in-bulk) +Get Tracker with ID| [`GET`v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +Get Tracker with name | [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) +Update Tracker| [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) +Delete Tracker| [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) + + +:::caution 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` +::: + +### Best Practices + +Following are the best practices to be followed while creating Trackers: + +Dos' and Don'ts | Example | +---------- | ------- | +Densely pack your vocabulary with information | "What’s the price?" | +Don't preface your information with lots of words that don’t convey meaning | "I was wondering if you could tell me about your pricing structure". | +Use simple sentences or phrases | Short sentence: "I want to understand your product". Phrase: "understand your product" | +Avoid using complex sentence structure | "I want to make sure that I have a full understanding of your product". + + +## Read more +--- +
+
+

API Reference

 + +* [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) +* [`GET` v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +* [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) +* [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) +* [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) + +
+
+
+

Tutorials

 + + +* [Creating Trackers with Async APIs](/docs/tutorials/trackers/create-trackers-async-api/) +* [Creating Trackers with Streaming API](/docs/tutorials/trackers/create-trackers-streaming-api/) +* [Using Trackers with Async API](/docs/tutorials/trackers/consuming-trackers-async-api/) +* [Using Trackers with Streaming API](/docs/tutorials/trackers/consuming-trackers-streaming-api/) + + +
+
+ +
+
+
+ +
+
diff --git a/docs/tutorials/trackers/creating-trackers-async-api.md b/docs/tutorials/trackers/creating-trackers-async-api.md new file mode 100644 index 00000000..8774eca5 --- /dev/null +++ b/docs/tutorials/trackers/creating-trackers-async-api.md @@ -0,0 +1,284 @@ +--- +id: create-trackers-async-api +title: Creating Trackers with Async API +sidebar_label: Creating Trackers with Async API +slug: /tutorials/trackers/create-trackers-async-api/ +--- + +--- +:::note In Beta Phase +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: + +Symbl provides a diverse set of Async APIs based on Audio/Video or Textual content. For more details on Async APIs refer to the documentation [here](/docs/async-api/introduction). + +The Trackers once ingested via the request, will then try to detect these in the Conversation. Once the job is complete, you can fetch the Trackers from the Conversation API through the `/trackers` endpoint described below. + +:::info Creating Trackers with Management API +While you can create Trackers with Async or Streaming APIs, it is recommended that you create Trackers using Management API because Trackers created with Management APIs are saved and can be reused while the same is not possible with Async or Streaming APIs. +::: + + +### Async Audio File API +The Tracker entities should be passed in as a **query parameter** in the Async Audio API’s URL like shown below + +:::tip Best Practises +Before creating the Trackers, go through the [Best Practices](#best-practices) section to learn about how to create Trackers. +::: + +### API Endpoint + +```json +"https"://api.symbl.ai/v1/process/audio?trackers=[ + { + "name":"COVID-19", + "vocabulary":[ + "social distancing", + "cover your face with mask", + "vaccination" + ] + } +] +``` +### Request Headers + +Header Name | Required | Description +---------- | ------- | ------- | +```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). +```Content-Type ``` | Optional | `application/json` This header must contain the MIME Type of the audio file’s container. +```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). + +## Async Audio URL API + +The Tracker entities should be passed in as a member of the **request body** of the Async Audio URL API like shown below: + +### API Endpoint + +**POST `https://api.symbl.ai/v1/process/audio/url`** + +### Request Header + +Header Name | Required | Description +---------- | ------- | ------- | +```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). +```Content-Type ``` | Mandatory | `application/json` This header must contain the MIME Type of the audio file’s container. +```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). + + +### Request Body + +```json +{ + "url": "", + "confidenceThreshold": 0.6, + "timezoneOffset": 0, + "trackers": [ + { + "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" + ] + } + ] +} +``` +Notice that the trackers member follows the same structure as mentioned in the Trackers section above. + +### Response + +```json +{ + "conversationId": "5815170693595136", + "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" +} +``` + +### Async Video File API +The Tracker entities should be passed in as a **query parameter** in the Async Video API’s URL like shown below: + +### API Endpoint + +```json +"https"://api.symbl.ai/v1/process/video?trackers=[ + { + "name":"COVID-19", + "vocabulary":[ + "social distancing", + "cover your face with mask", + "vaccination" + ] + } +] +``` + +### Request Header + +Header Name | Required | Description +---------- | ------- | ------- | +```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). +```Content-Type ``` | Optional | `application/json` This header must contain the MIME Type of the audio file’s container. +```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). + +Notice that the trackers query parameter follows the same structure as mentioned in the Trackers section above. + +### Response + +```json +{ + "conversationId": "5815170693595136", + "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" +} +``` + +### Async Video URL API +The Tracker entities should be passed in as a member of the request body of the Async Video URL API like shown below: + +### API Endpoint + +**POST `https://api.symbl.ai/v1/process/video/url`** + +### Request Headers + +Header Name | Required | Description +---------- | ------- | ------- | +```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). +```Content-Type ``` | Mandatory | `application/json` This header must contain the MIME Type application/json. +```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). + +### Request Body +```json +{ + "url": "", + "confidenceThreshold": 0.6, + "timezoneOffset": 0, + "trackers": [ + { + "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" + ] + } + ] +} +``` +Notice that the trackers member follows the same structure as mentioned in the Trackers section above. + +### Response + +```json +{ + "conversationId": "5815170693595136", + "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" +} +``` + +### Async Text API +The Tracker entities should be passed in as a member of the **request body** of the Async Text API like shown below: + +### API Endpoint + +**POST `https://api.symbl.ai/v1/process/text`** + + +### Request Headers + +Header Name | Required | Description +---------- | ------- | ------- | +```Authorization``` | Mandatory | `Bearer ` The token you get from our [authentication process](/docs/developer-tools/authentication). +```Content-Type ``` | Mandatory | `application/json` This header must contain the MIME Type application/json. +```x-api-key``` | Optional | DEPRECATED. The JWT token you get from our [authentication process](/docs/developer-tools/authentication). + +### Request Body + +```json +{ + "name": "My Sales Conversation", + "conversationType": [ + "sales" + ], + "messages": [ + { + "payload": { + "content": "", + "contentType": "text/plain" + }, + "from": { + "name": "John", + "userId": "john@example.com" + } + } + ], + "trackers": [ + { + "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" + ] + } + ] +} +``` +Notice that the trackers member follows the same structure as the Trackers section above. + +### Response + +```json +{ + "conversationId": "5815170693595136", + "jobId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" +} +``` + +### Best Practices + +Following are the best practices to be followed while creating Trackers: + +Dos' and Don'ts | Example | +---------- | ------- | +Densely pack your vocabulary with information | "What’s the price?" | +Don't preface your information with lots of words that don’t convey meaning | "I was wondering if you could tell me about your pricing structure". | +Use simple sentences or phrases | Short sentence: "I want to understand your product". Phrase: "understand your product" | +Avoid using complex sentence structure | "I want to make sure that I have a full understanding of your product". + +## Read more +--- +
+
+

API Reference

 + +* [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) +* [`GET` v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +* [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) +* [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) +* [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) + +
+
+
+

Tutorials

 + + +* [How to create and use Trackers- Trackers Management API](/docs/tutorials/trackers/consuming-trackers-management-api/) +* [Creating Trackers with Streaming API](/docs/tutorials/trackers/create-trackers-streaming-api/) +* [Using Trackers with Async API](/docs/tutorials/trackers/consuming-trackers-async-api/) +* [Using Trackers with Streaming API](/docs/tutorials/trackers/consuming-trackers-streaming-api/) + + +
+
+ +
+
+
+ +
+
diff --git a/docs/streamingapi/code-snippets/consume-trackers-with-streaming-api.md b/docs/tutorials/trackers/creating-trackers-streaming-api.md similarity index 51% rename from docs/streamingapi/code-snippets/consume-trackers-with-streaming-api.md rename to docs/tutorials/trackers/creating-trackers-streaming-api.md index f610d7ed..99cdf90e 100644 --- a/docs/streamingapi/code-snippets/consume-trackers-with-streaming-api.md +++ b/docs/tutorials/trackers/creating-trackers-streaming-api.md @@ -1,15 +1,26 @@ --- -id: consume-trackers -title: Consume Trackers with Streaming API -sidebar_label: Consume Trackers with Streaming API -slug: /streaming-api/code-snippets/consume-trackers-with-streaming-api/ +id: create-trackers-streaming-api +title: Creating Trackers with Streaming API +sidebar_label: Creating Trackers with Streaming API +slug: /tutorials/trackers/create-trackers-streaming-api/ --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; --- +:::note In Beta Phase +This feature is in the Beta phase. If you have any questions, ideas or suggestions please reach out to us at devrelations@symbl.ai. +::: -Below is an example that shows how to pass Trackers in the config object for the startRealtimeRequest of the Symbl’s JS SDK. This example also shows how to consume the results of the detected Trackers in real-time. +You can create and consume Trackers in real-time using the Streaming APIs. + +Below is an example that shows how to pass Trackers in the `config` object for the `startRealtimeRequest` of the Symbl’s JS SDK. This example also shows how to consume the results of the detected Trackers in real-time. + +:::info Creating Trackers with Management API +While you can create Trackers with Async or Streaming APIs, it is recommended that you create Trackers using Management API because Trackers created with Management APIs are saved and can be reused while the same is not possible with Async or Streaming APIs. +::: + +:::tip Best Practises +Before creating the Trackers, go through the [Best Practices](#best-practices) section to learn about how to create Trackers. +::: ```js @@ -32,7 +43,8 @@ const connection = await sdk.startRealtimeRequest({ languageCode: "en-US", sampleRateHertz: 48000, trackers: { - "interimResults": true + "interimResults": true, + "enableAllTrackers": true } }, speaker: { @@ -80,16 +92,63 @@ Let’s go over all the parameters passed in the configuration object in the abo Field | Required | ---------- | ------- | `id` | A unique UUID that represents this WebSocket API Session. -`insightType` | The types of Insights to be detected for this Conversation. +`insightTypes` | The types of Insights to be detected for this Conversation. `trackers`| The Trackers to be detected in real-time for that Conversation. Follows the same structure as described in the [Trackers section](/docs/management-api/trackers/create-tracker#sample-request-body). `config`| The config object encapsulates the metadata for the WebSocket API’s session. `meetingTitle`| The title for this conversation/meeting. `confidenceThreshold` | The insights having confidence scores greater than this threshold will be the ones detected for the Conversation. `languageCode` | The language-code in BCP-47 format. `sampleRateHertz`| The sample-rate of the incoming audio data which is being pushed to Symbl. -`trackers: { interimResults }`| The interimResults flag tells Symbl to send the tracker results as soon as they are detected. If false, the tracker results are detected for the finalized transcription responses. +`trackers.interimResults`| The interimResults flag tells Symbl to send the tracker results as soon as they are detected. If false, the tracker results are detected for the finalized transcription responses. +`trackers.enableAllTrackers`| The `enableAllTrackers` parameter must be sent to detect all the 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. `speaker` | The details of the speaker in this Conversation `userId`| Unique identifier to represent the User. `name` | The name of the User. `handlers` | The object encapsulating the call-back functions to be invoked on detection of those specific entities. For more information on various such handlers, check out this [link](/docs/javascript-sdk/tutorials/receive-ai-insights-from-your-computer/). -`onTrackerResponse`| This function is invoked when Symbl detects a Tracker in real-time. The structure of the Tracker object is shown in the above code snippet. \ No newline at end of file +`onTrackerResponse`| This function is invoked when Symbl detects a Tracker in real-time. The structure of the Tracker object is shown in the above code snippet. + +### Best Practices + +Following are the best practices to be followed while creating Trackers: + +Dos' and Don'ts | Example | +---------- | ------- | +Densely pack your vocabulary with information | "What’s the price?" | +Don't preface your information with lots of words that don’t convey meaning | "I was wondering if you could tell me about your pricing structure". | +Use simple sentences or phrases | Short sentence: "I want to understand your product". Phrase: "understand your product" | +Avoid using complex sentence structure | "I want to make sure that I have a full understanding of your product". + + +## Read more +--- +
+
+

API Reference

 + +* [`POST` v1/manage/tracker](/management-api/trackers/create-tracker) +* [`GET` v1/manage/tracker/{trackerId}](/management-api/trackers/get-tracker#get-tracker-by-id) +* [`GET` v1/manage/trackers?&name={trackerName}](/management-api/trackers/get-tracker#get-tracker) +* [`PUT`v1/manage/tracker/{trackerId}](/management-api/trackers/update-tracker) +* [`DELETE`v1/manage/tracker/{trackerId}](/management-api/trackers/delete-tracker) + +
+
+
+

Tutorials

 + + +* [How to create and use Trackers- Trackers Management API](/docs/tutorials/trackers/consuming-trackers-management-api/) +* [Creating Trackers with Async APIs](/docs/tutorials/trackers/create-trackers-async-api/) +* [Using Trackers with Async API](/docs/tutorials/trackers/consuming-trackers-async-api/) +* [Using Trackers with Streaming API](/docs/tutorials/trackers/consuming-trackers-streaming-api/) + + +
+
+ +
+
+
+ +
+
diff --git a/sidebars.js b/sidebars.js index 0555961a..12b93ce3 100644 --- a/sidebars.js +++ b/sidebars.js @@ -406,7 +406,6 @@ id: 'developer-tools/postman', 'streamingapi/code-snippets/receive-live-captioning', 'streamingapi/code-snippets/receive-live-topics', 'streamingapi/code-snippets/receive-ai-insights', - 'streamingapi/code-snippets/consume-trackers', 'streamingapi/code-snippets/receive-speech-to-text-for-different-languages', 'streamingapi/code-snippets/receive-trackers-in-spanish', ], @@ -449,6 +448,18 @@ id: 'developer-tools/postman', 'tutorials/summarization/refreshing-summary', 'tutorials/summarization/adding-speaker-info', ], +}, +{ + label: 'Trackers API (Beta)', + type: 'category', + collapsed: true, + items: [ + 'tutorials/trackers/consuming-trackers-management-api', + 'tutorials/trackers/create-trackers-streaming-api', + 'tutorials/trackers/consuming-trackers-async-api', + 'tutorials/trackers/create-trackers-async-api', + 'tutorials/trackers/consuming-trackers-streaming-api', + ], }, { label: "Pre-built UI", diff --git a/src/css/custom.css b/src/css/custom.css index dd723987..c5ae6524 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -409,6 +409,13 @@ th:empty { margin-bottom: 20px; } } + + .card21 { + box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2); /* this adds the "card" effect */ + padding: 16px; + text-align: left; + width: 100%; +} /* Button element */ .button {