Intent Recognition

intents boolean Default: false

Text Intelligence English (all available regions)

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.

"results": {
    "intents": {
      "segments": [
        {
          "text":"Can I upgrade my phone?",
          "start_word": 12,
          "end_word": 16,
          "intents": [
            {
              "intent": "Upgrade phone", "confidence_score": 0.9750028
            }
          ]
        },
        {
          "text": "I also need to update my address.",
          "start_word": 12,
          "end_word": 18,
          "intents": [
            {
              "intent": "Update address",
              "confidence_score": 0.6320186
            }
          ]
        }
      ]
    }
  }

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.

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

intents=true

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

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)

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.

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

{
  "metadata": {
    "request_id": "65be7382-9d92-4373-bf5e-ef3a3d0cf56c",
    "created": "2024-01-19T17:52:23.970Z",
    "language": "en",
    "intents_info": {
      "model_uuid": "ba5b22e4-b39a-4550-a4bc-d8655f5092bc",
      "input_tokens": 22,
      "output_tokens": 4
    }
  },
  "results": {
    "intents": {
      "segments": [
        {
          "text": "Can I upgrade my phone?",
          "start_word": 12,
          "end_word": 16,
          "intents": [
            {
              "intent": "Upgrade phone", "confidence_score": 0.9750028
            }
          ]
        },
        {
          "text": "I also need to update my address.",
          "start_word": 12,
          "end_word": 18,
          "intents": [
            {
              "intent": "Update address",
              "confidence_score": 0.6320186
            }
          ]
        }
      ]
    }
  }
}

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.

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.

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

Status 400

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

{
  "err_code": "TOKEN_LIMIT_EXCEEDED",
  "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.",
  "request_id": "XXXX"
}

Status 400

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

{
  "err_code":"INVALID_QUERY_PARAMETER",
  "err_msg":"Failed to deserialize query parameters: missing field `language`",
  "request_id":"XXX"
}