Sentiment analysis on topics

Topics are key drivers of conversations. They're the most important keywords or phrases used. The topics algorithm provides a framework for you to calibrate and precisely model the relationship among the concepts and understand how the sentiments expressed in the conversation. Sentiment analysis on topics determines whether the topics resulting from the conversation are positive, negative, or neutral.

Note that Sentiment Analysis currently only supports the en-US (English US) language.

Step 1: Process a conversation

Use the Async API in text, audio, or video version to process your conversation.

This example shows how to process an audio file (in `.wav format) via the Async API Process Audio. You can use the same basic steps to process video and text conversations. For more information, see Async API.

Note that you must wait for the job to finish processing before generating Conversation Intelligence. If you make a request from the Conversations API while the job is processing, you might receive incomplete insights. You can find out if a job is still processing by passing the jobId in the Get job status request.

Authentication

Before using this API, you must generate your authentication token (AUTH_TOKEN) as described in Authentication.

Example API Endpoint

POST <https://api.symbl.ai/v1/process/audio>

Request header

Remember to include your bearer token in the authorization header.

curl --location --request POST "https://api.symbl.ai/v1/process/audio \
--header 'Content-Type: audio/wav' \
--header "Authorization: Bearer $AUTH_TOKEN" \
--data-binary '@/file/location/audio.wav'
Header NameRequiredValue
AuthorizationMandatoryBearer <token> The token you get during Authentication.
Content-TypeOptionalThis optional parameter describes the format and codec of the provided audio data. Accepted values are audio/wav, audio/mpeg, audio/mp3 and audio/wave only. If your audio is in a format other than these, do not use this field.

Response body

{
  "conversationId": "5006340993843200",
  "jobId": "f98171b5-0f24-4582-92bc-325c3fa9473b"
}

This Conversation ID is a unique identifier of the conversation you can pass in Get topics to receive sentiment analysis. For details, see step 2.

The job ID is the unique identifier of the job in progress. Use it to Get job status.

You must wait for processing to be complete before you can proceed to the next step. The time taken for the job to complete depends on the file size.

Step 2: Use conversationId in the Get topics request and pass sentiment=true

Pass the conversation ID you received in step 1. Also, make sure that you pass sentiment=true as a query parameter.

Example API Endpoint

​​​​GET <https://api.symbl.ai/v1/conversations/{conversationId}/topics?sentiment=true>

Request header

Remember to include your bearer token in the authorization header of the request.

To learn more about authorization header, see Process audio page.

curl --location --request GET
"https://api.symbl.ai/v1/conversations/{conversationId}/topics?sentiment=true" \
--header 'Content-Type: audio/wav' \
--header "Authorization: Bearer $AUTH_TOKEN" \
--data-binary '@/file/location/audio.wav'
Header NameRequiredValue
AuthorizationRequiredBearer <token> The token you get during Authentication.
Content-TypeOptionalThis optional parameter describes the format and codec of the provided audio data. Accepted values are audio/wav, audio/mpeg, audio/mp3 and audio/wave only. If your audio is in a format other than these, do not use this field.

Response

{
   "topics":[
      {
         "id":"5907389282779136",
         "text":"interns",
         "type":"topic",
         "score":0.7178597920690242,
         "messageIds":[
            "4600982711304192",
            "5487363432120320",
            "6109794119188480"
         ],
         "sentiment":{
            "polarity":{
               "score":0.389
            },
            "suggested":"positive"
         },
         "parentRefs":[
            
         ]
      },
      {
         "id":"5776859730018304",
         "text":"company-wise hiring",
         "type":"topic",
         "score":0.788856914361565,
         "messageIds":[
            "6298570346987520",
            "6330577953226752"
         ],
         "sentiment":{
            "polarity":{
               "score":0.012
            },
            "suggested":"neutral"
         },
         "parentRefs":[
            
         ]
      },
      {
         "id":"6697188878974976",
         "text":"new regulations",
         "type":"topic",
         "score":0.6968750176932417,
         "messageIds":[
            "5356560840654848",
            "5663440783802368",
            "5263998490509312",
            "6082396449406976",
            "4925138187321344"
         ],
         "sentiment":{
            "polarity":{
               "score":-0.809
            },
            "suggested":"negative"
         },
         "parentRefs":[
            
         ]
      }
   ]
} 

The body parameter is defined in the operation's parameters section and includes objects that describe the body data type and structure. For more information, see Speech-to-Text.

Polarity and score

Sentiment Analysis is the interpretation of the general thought, feeling, or sense of an object or a situation. In the Response, you’ll notice the sentiment field which shows the sentiment type (positive, negative, and neutral). It is scored using “polarity” values which shows the intensity of the sentiment. It ranges from -1.0 to 1.0, where -1.0 is the most negative sentiment and 1.0 is the most positive sentiment.

Example code snippet:

{
  "sentiment": {
    "polarity": {
      "score": 0.6
    }
  }
}

We have chosen the following polarity ranges for sentiment type, which covers a wide range of conversations.

Polarity sentiment may vary for your use case. We recommend that you define a threshold that works for you, and then adjust the threshold after testing and verifying the results.

PolaritySuggested Sentiment
-1.0 => x > -0.3negative
-0.3 => x <= 0.3neutral
0.3 < x <= 1.0positive