> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gnani.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Intent classification for Indian languages

> Classify customer messages in Hindi, Kannada and other languages into intents your code can route, using a JSON schema.

Early access
**Gnani Evon v3.5** is now available as an API to early access registrants.

Route customer messages to the right queue without writing rules for every language. Send the message with a [JSON schema](https://docs.gnani.ai/api/LLM/structured-outputs.md), and get back the intent, the language and a short English summary.

## When to use this

* Messages arrive in Hindi, Kannada, English or a mix, and you route them to teams or flows.
* You need a fixed set of labels that your code can switch on.
* You want an English summary for agents who do not read the customer's language.

***

## Classify one message

```bash cURL theme={null}
curl https://api.vachana.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: $GNANI_API_KEY" \
  -d '{
    "model": "evon-v3.5",
    "reasoning_effort": "none",
    "temperature": 0,
    "messages": [
      {"role": "system", "content": "Classify the customer message for an online store. intent is one of: order_status, refund, payment_issue, cancel_order, other. language is the ISO 639-1 code of the language, even if it is written in Latin script. summary is one short English sentence without personal details."},
      {"role": "user", "content": "मेरे पैसे कट गए लेकिन UPI पेमेंट फेल दिखा रहा है"}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "customer_intent",
        "schema": {
          "type": "object",
          "properties": {
            "intent": {"type": "string", "enum": ["order_status", "refund", "payment_issue", "cancel_order", "other"]},
            "language": {"type": "string"},
            "summary": {"type": "string"}
          },
          "required": ["intent", "language", "summary"],
          "additionalProperties": false
        }
      }
    }
  }'
```

```python Python (OpenAI SDK) theme={null}
import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.vachana.ai/v1",
    api_key=os.environ["GNANI_API_KEY"],
)

INTENTS = ["order_status", "refund", "payment_issue", "cancel_order", "other"]

SYSTEM = (
    "Classify the customer message for an online store. intent is one of: " + ", ".join(INTENTS) + ". "
    "language is the ISO 639-1 code of the language, even if it is written in Latin script. "
    "summary is one short English sentence without personal details."
)

SCHEMA = {
    "type": "object",
    "properties": {
        "intent": {"type": "string", "enum": INTENTS},
        "language": {"type": "string"},
        "summary": {"type": "string"},
    },
    "required": ["intent", "language", "summary"],
    "additionalProperties": False,
}

completion = client.chat.completions.create(
    model="evon-v3.5",
    reasoning_effort="none",
    temperature=0,
    messages=[
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": "मेरे पैसे कट गए लेकिन UPI पेमेंट फेल दिखा रहा है"},
    ],
    response_format={"type": "json_schema", "json_schema": {"name": "customer_intent", "schema": SCHEMA}},
)

choice = completion.choices[0]
if choice.finish_reason != "stop":
    raise RuntimeError(f"Incomplete reply: {choice.finish_reason}")
result = json.loads(choice.message.content)
if result.get("intent") not in INTENTS:
    result["intent"] = "other"
print(result)
```

```javascript JavaScript (OpenAI SDK) theme={null}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.vachana.ai/v1",
  apiKey: process.env.GNANI_API_KEY,
});

const INTENTS = ["order_status", "refund", "payment_issue", "cancel_order", "other"];

const SYSTEM =
  `Classify the customer message for an online store. intent is one of: ${INTENTS.join(", ")}. ` +
  "language is the ISO 639-1 code of the language, even if it is written in Latin script. " +
  "summary is one short English sentence without personal details.";

const SCHEMA = {
  type: "object",
  properties: {
    intent: { type: "string", enum: INTENTS },
    language: { type: "string" },
    summary: { type: "string" },
  },
  required: ["intent", "language", "summary"],
  additionalProperties: false,
};

const completion = await client.chat.completions.create({
  model: "evon-v3.5",
  reasoning_effort: "none",
  temperature: 0,
  messages: [
    { role: "system", content: SYSTEM },
    { role: "user", content: "मेरे पैसे कट गए लेकिन UPI पेमेंट फेल दिखा रहा है" },
  ],
  response_format: { type: "json_schema", json_schema: { name: "customer_intent", schema: SCHEMA } },
});

const choice = completion.choices[0];
if (choice.finish_reason !== "stop") {
  throw new Error(`Incomplete reply: ${choice.finish_reason}`);
}
const result = JSON.parse(choice.message.content);
if (!INTENTS.includes(result.intent)) result.intent = "other";
console.log(result);
```

```python Python (requests) theme={null}
import json
import os
import requests

INTENTS = ["order_status", "refund", "payment_issue", "cancel_order", "other"]

response = requests.post(
    "https://api.vachana.ai/v1/chat/completions",
    headers={"X-API-Key-ID": os.environ["GNANI_API_KEY"]},
    json={
        "model": "evon-v3.5",
        "reasoning_effort": "none",
        "temperature": 0,
        "messages": [
            {"role": "system", "content": "Classify the customer message for an online store. intent is one of: "
                                          + ", ".join(INTENTS) + ". language is the ISO 639-1 code of the language, "
                                          "even if it is written in Latin script. summary is one short English "
                                          "sentence without personal details."},
            {"role": "user", "content": "मेरे पैसे कट गए लेकिन UPI पेमेंट फेल दिखा रहा है"},
        ],
        "response_format": {
            "type": "json_schema",
            "json_schema": {
                "name": "customer_intent",
                "schema": {
                    "type": "object",
                    "properties": {
                        "intent": {"type": "string", "enum": INTENTS},
                        "language": {"type": "string"},
                        "summary": {"type": "string"},
                    },
                    "required": ["intent", "language", "summary"],
                    "additionalProperties": False,
                },
            },
        },
    },
    timeout=60,
)
response.raise_for_status()
choice = response.json()["choices"][0]
if choice["finish_reason"] != "stop":
    raise RuntimeError(f"Incomplete reply: {choice['finish_reason']}")
print(json.loads(choice["message"]["content"]))
```

The reply's `content` (illustrative):

```json theme={null}
{"intent": "payment_issue", "language": "hi", "summary": "Money was debited but the UPI payment shows as failed."}
```

> [accordion] Classify a batch of messages
>
> Send one request per message. On Free and Pay-as-you-go plans only one request can run at a time, so the loop sends them one after another and waits a second between them. OpenAI's SDKs retry `429` responses for you.
>
> ```python Python (OpenAI SDK) expandable theme={null}
> import json
> import os
> import time
> from openai import OpenAI
>
> client = OpenAI(
>     base_url="https://api.vachana.ai/v1",
>     api_key=os.environ["GNANI_API_KEY"],
> )
>
> INTENTS = ["order_status", "refund", "payment_issue", "cancel_order", "other"]
> SYSTEM = (
>     "Classify the customer message for an online store. intent is one of: " + ", ".join(INTENTS) + ". "
>     "language is the ISO 639-1 code of the language, even if it is written in Latin script. "
>     "summary is one short English sentence without personal details."
> )
> SCHEMA = {
>     "type": "object",
>     "properties": {
>         "intent": {"type": "string", "enum": INTENTS},
>         "language": {"type": "string"},
>         "summary": {"type": "string"},
>     },
>     "required": ["intent", "language", "summary"],
>     "additionalProperties": False,
> }
>
> # Synthetic sample messages.
> MESSAGES = [
>     "मेरे पैसे कट गए लेकिन UPI पेमेंट फेल दिखा रहा है",
>     "ನನ್ನ ಆರ್ಡರ್ ರದ್ದು ಮಾಡಿ",
>     "ನನ್ನ ರೀಫಂಡ್ ಇನ್ನೂ ಬಂದಿಲ್ಲ",
>     "Mera parcel abhi tak nahi aaya",
>     "Do you deliver to Mysuru?",
> ]
>
>
> def classify(text: str) -> dict:
>     completion = client.chat.completions.create(
>         model="evon-v3.5",
>         reasoning_effort="none",
>         temperature=0,
>         messages=[{"role": "system", "content": SYSTEM}, {"role": "user", "content": text}],
>         response_format={"type": "json_schema", "json_schema": {"name": "customer_intent", "schema": SCHEMA}},
>     )
>     choice = completion.choices[0]
>     if choice.finish_reason != "stop":
>         return {"intent": "other", "language": "", "summary": f"Not classified ({choice.finish_reason})"}
>     result = json.loads(choice.message.content)
>     if result.get("intent") not in INTENTS:
>         result["intent"] = "other"
>     return result
>
>
> for text in MESSAGES:
>     result = classify(text)
>     print(f"{result['intent']:<14} {result['language']:<3} {result['summary']}")
>     time.sleep(1)  # stay within 1 request per second
> ```
>
> The output looks something like this:
>
> ```text theme={null}
> payment_issue  hi  Money was debited but the UPI payment shows as failed.
> cancel_order   kn  The customer wants to cancel their order.
> refund         kn  The customer has not received their refund yet.
> order_status   hi  The customer's parcel has not arrived yet.
> other          en  The customer asks whether delivery is available in Mysuru.
> ```

***

## How it works

* The `system` message, in English, names the labels and says what each field means. The customer's message can be in another language.
* `response_format` with `json_schema` makes the reply a JSON object with exactly the keys you listed.
* `reasoning_effort: "none"` and `temperature: 0` make the call fast and repeatable. Classification does not need thinking.
* Your code checks `finish_reason`, parses `content`, and falls back to `other` for an unexpected label.

***

## Options

| Change | How |
| - | - |
| More or different intents | Edit `INTENTS`. Keep an `other` label so every message has somewhere to go. |
| Extra fields, such as an order ID | Add a property to the schema and to `required`, and describe it in the `system` message. |
| Less strict output | Use `{"type": "json_object"}` and describe the keys in the prompt. See [JSON output](https://docs.gnani.ai/api/LLM/structured-outputs.md). |
| Reply in the customer's language as well | Make a second request without `response_format`, or use the [support bot recipe](https://docs.gnani.ai/api/LLM/recipes/support-bot.md). |

***

## Gotchas

> [!WARNING]
>
> **Personal data is masked in replies, including inside JSON.** If the model copies a phone number, UPI ID or account number into a field, it arrives as a placeholder such as `[REDACTED_PHONE]`. Extract such identifiers from the original text in your own code. See [Safety and privacy](https://docs.gnani.ai/api/LLM/safety.md).

* **Check `finish_reason` before parsing.** With `length`, the JSON is cut off.
* **Validate the values, not just the keys.** Map anything outside your list to `other`.
* **Romanised and mixed-language text** ("Mera parcel abhi tak nahi aaya") is common in chat. Test with your own samples, and check the `language` field before you route on it.
* **Batches count toward your limits.** Each message is one request and uses your [daily token quota](https://docs.gnani.ai/api/LLM/limits.md). Keep the `system` message short: it is sent with every request.

***

## Related

> [card] [JSON output](https://docs.gnani.ai/api/LLM/structured-outputs.md)
>
> `json_object` and `json_schema` in detail.

> [card] [Indian languages](https://docs.gnani.ai/api/LLM/indian-languages.md)
>
> Working with Indian scripts and mixed-language text.

> [card] [Customer support bot](https://docs.gnani.ai/api/LLM/recipes/support-bot.md)
>
> Answer the customer once you know the intent.

> [card] [Limits](https://docs.gnani.ai/api/LLM/limits.md)
>
> Request rates and the daily token quota.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.