> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.deepgram.com/docs/intent-recognition/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.deepgram.com/_mcp/server.

# Intent Recognition

Deepgram API Playground

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.

**`cURL`**

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

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

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

```json 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`**

```json 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`**

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

    }
}
```

> Intent Recognition recognizes speaker intent throughout a transcript.