Intent Recognition

intents boolean   Default: false

Deepgram’s Intent Recognition feature recognizes speaker intent throughout an entire transcript, returning a list of text segments and the intents found within each segment.

The intents that can be identified are not a fixed list; this TSLM powered feature is able to generate intents based on the context of the language content in the transcript. You may also choose to use the optional custom-intent parameter to provide a custom intent you want detected if present within your audio.

Enable Feature

To enable Intent Recognition, use the following parameter in the query string when you call Deepgram’s /listen endpoint:

intents=true

To transcribe audio from a file on your computer, run the following curl command in a terminal or your favorite API client.

$
curl \
>
  --request POST \
>
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
>
  --header 'Content-Type: audio/wav' \
>
  --data-binary @youraudio.wav \
>
  --url 'https://api.deepgram.com/v1/listen?intents=true'

Enable Feature with Custom Intents

$
curl \
>
  --request POST \
>
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
>
  --header 'Content-Type: audio/wav' \
>
  --data-binary @youraudio.wav \
>
  --url 'https://api.deepgram.com/v1/listen?intents=true&language=en&custom_intent_mode=strict&custom_intent=Upgrade%20Phone'

Query Parameters

Analyze Response

When the file is finished processing, you’ll receive a JSON response that has the following basic structure:

1
{
2
  "metadata": {},
3
  "results": {
4
    "channels": [
5
      {
6
        "alternatives": [...]
7
      }
8
    ],
9
    "intents": {
10
      "segments": [
11
        {
12
          "text": "Can I upgrade my phone?",
13
          "start_word": 12,
14
          "end_word": 16,
15
          "intents": [
16
            { "intent": "Upgrade phone", "confidence_score": 0.9750028 }
17
          ]
18
        }
19
      ]
20
    }
21
  }
22
}

The response object values for intents are:

• segments: The list of segments of text identified by the model as containing notable intents.
• intent: The name of the intent detected by the model. This will always be in the form of a verb.
• confidence_score: a floating point from 0 to 1 representing the models confidence in this prediction.

API Warning Response

Warning

If you request Intent Recognition with an unsupported language by specifying a language code such as intents=true&language=es or intents=true&detect_language=true where the detected language is unsupported, you will get the warning message below.

1
"warnings": [
2
  {
3
    "parameter": "intents",
4
    "type": "unsupported_language",
5
    "message": "Intents is only supported for English."
6
  }
7
]

Example Warning

Here is an example of the JSON structure of a request with warning object.

1
{
2
 "metadata": {
3
...
4
       },
5
     "warnings": [
6
       {
7
         "parameter": "intents",
8
         "type": "unsupported_language",
9
         "message": "Intents are only supported for English."
10
       }
11
     ]
12
   },
13
 "results": {
14
       "channels": [
15
            {
16
                "alternatives": [...]
17
            }
18
        ], 
19
20
    }
21
}