Intent Recognition

intents boolean   Default: false

Intent Recognition accepts an input text, divides it into a list of segments comprised of sections of the text, and assigns a description of intent to each text segment.

1
"results": {
2
    "intents": {
3
      "segments": [
4
        {
5
          "text":"Can I upgrade my phone?",
6
          "start_word": 12,
7
          "end_word": 16,
8
          "intents": [
9
            {
10
              "intent": "Upgrade phone", "confidence_score": 0.9750028
11
            }
12
          ]
13
        },
14
        {
15
          "text": "I also need to update my address.",
16
          "start_word": 12,
17
          "end_word": 18,
18
          "intents": [
19
            {
20
              "intent": "Update address",
21
              "confidence_score": 0.6320186
22
            }
23
          ]
24
        }
25
      ]
26
    }
27
  }

For example, if the input text comes from a chatbot interface for a banking application, one segment of text may include the statement “I need to check my account balance.” Deepgram’s intent recognition system would recognize that the user’s intent is to inquire about their account balance and then assign a description of “Check balance”.

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 text. You may also choose to use the optional custom-intent parameter to provide a custom intent you want detected if present within the provided text.

Enable Feature

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

intents=true

Basic Text Request

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

$
curl -vX POST \
>
 -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>
 -H "Content-Type: application/json" \
>
 -d '{"text": "YOUR_TEXT_INPUT"}' \
>
 "https://api.deepgram.com/v1/read?intents=true&language=en"

Basic URL Request

To analyze text from a hosted file, run the following curl command in a terminal or your favorite API client. (Try testing it out with the hosted file https://static.deepgram.com/examples/aura.txt)

$
curl -vX POST \
>
 -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>
 -H "Content-Type: application/json" \
>
 -d '{"url": "https://YOUR_FILE_URL.txt"}' \
>
 "https://api.deepgram.com/v1/read?intents=true&language=en"

Custom Intent Request

To tell the model to only return intents from your own custom list of intents, add custom_intent_mode=strict and custom_intent= followed by the list of intents. (Use the URL encoding%20 to represent a space between each word in the list.)

If you want to return your own custom list of intents in addition to Deegpram’s list of intents, set custom_intent_mode=extended and add your custom list.

$
curl -vX POST \
>
 -H "Authorization: Token YOUR_DEEPGRAM_API_KEY" \
>
 -H "Content-Type: application/json" \
>
 -d '{"text": "YOUR_TEXT_INPUT"}' \
>
 "https://api.deepgram.com/v1/read?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
    "request_id": "65be7382-9d92-4373-bf5e-ef3a3d0cf56c",
4
    "created": "2024-01-19T17:52:23.970Z",
5
    "language": "en",
6
    "intents_info": {
7
      "model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc",
8
      "input_tokens": 22,
9
      "output_tokens": 4
10
    }
11
  },
12
  "results": {
13
    "intents": {
14
      "segments": [
15
        {
16
          "text": "Can I upgrade my phone?",
17
          "start_word": 12,
18
          "end_word": 16,
19
          "intents": [
20
            {
21
              "intent": "Upgrade phone", "confidence_score": 0.9750028
22
            }
23
          ]
24
        },
25
        {
26
          "text": "I also need to update my address.",
27
          "start_word": 12,
28
          "end_word": 18,
29
          "intents": [
30
            {
31
              "intent": "Update address",
32
              "confidence_score": 0.6320186
33
            }
34
          ]
35
        }
36
      ]
37
    }
38
  }
39
}

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 Error Responses

Unsupported Language

Status 400

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 error message below.

1
{
2
  "err_code":"INVALID_QUERY_PARAMETER",
3
  "err_msg":"Request specified unsupported language: <language_name>. Only English is supported.",
4
  "request_id":"XXXX"
5
}

Token Limit Exceeded

Status 400

If the request’s input length exceeded the 150k token rate limit per request, you will get the error message below.

1
{
2
  "err_code": "TOKEN_LIMIT_EXCEEDED",
3
  "err_msg": "Text input for <api_name> currently supports up to 150K tokens. Please revise your text input to fit within the defined token limit. For more information, please visit our API documentation.",
4
  "request_id": "XXXX"
5
}

Missing Query Parameter

Status 400

If the request sent contained only the feature parameter (intents) but not the language parameter, you will receive this error.

1
{
2
  "err_code":"INVALID_QUERY_PARAMETER",
3
  "err_msg":"Failed to deserialize query parameters: missing field `language`",
4
  "request_id":"XXX"
5
}