# Intent Recognition

:::card{title="Deepgram API Playground" href="https://playground.deepgram.com/?endpoint=listen&intents=true&language=en&model=nova-3"}
Try this feature out in our API Playground.
:::

`intents` _boolean_ Default: `false`

Pre-recorded Streaming\:Nova All available languages

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.

```bash
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

```bash
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'
```

:::callout{intent="warning"}
Replace `YOUR_DEEPGRAM_API_KEY` with your [Deepgram API Key](https://console.deepgram.com/signup?jump=keys).
:::

### Query Parameters

| Parameter            | Value                       | Type    | Description                                                                                                                                                                                                                                                                                                            |
| -------------------- | --------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `intents`            | `true`                      | boolean | Enables intent recognition                                                                                                                                                                                                                                                                                             |
| `language`           | `en`                        | string  | The language of your input audio (Only English is supported at this time)                                                                                                                                                                                                                                              |
| `custom_intent`      | ex: `unsubscribe`           | string  | Optional. A custom intent you want the model to detect within your input audio if present. Submit up to 100.                                                                                                                                                                                                           |
| `custom_intent_mode` | `extended`(default)`strict` | string  | Optional. Sets how the model will interpret strings submitted to the `custom_intent` param. When `strict`, the model will only return intents submitted using the `custom_intent` param. When `extended`, the model will return its own detected intents in addition those submitted using the `custom_intents` param. |

## Analyze Response

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

```json
{
  "metadata": {},
  "results": {
    "channels": [
      {
        "alternatives": [...]
      }
    ],
    "intents": {
      "segments": [
        {
          "text": "Can I upgrade my phone?",
          "start_word": 12,
          "end_word": 16,
          "intents": [
            { "intent": "Upgrade phone", "confidence_score": 0.9750028 }
          ]
        }
      ]
    }
  }
}
```

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.

```json
"warnings": [
  {
    "parameter": "intents",
    "type": "unsupported_language",
    "message": "Intents is only supported for English."
  }
]
```

| Warning Name           | Warning Message                                                  |
| ---------------------- | ---------------------------------------------------------------- |
| `unsupported_language` | Feature isn’t supported with the specified or detected language. |

**Example Warning**

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

```json
{
 "metadata": {
...
       },
     "warnings": [
       {
         "parameter": "intents",
         "type": "unsupported_language",
         "message": "Intents are only supported for English."
       }
     ]
   },
 "results": {
       "channels": [
            {
                "alternatives": [...]
            }
        ], 

    }
}
```

## Related pages

- [Feature Overview](./self-hosted-deployments-6-stt-intelligence-feature-overview.md)
- [Entity Detection](./self-hosted-deployments-6-detect-entities.md)
- [Sentiment Analysis](./self-hosted-deployments-6-sentiment-analysis.md)
- [Summarization](./self-hosted-deployments-6-summarization.md)
- [Topic Detection](./self-hosted-deployments-6-topic-detection.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.