# Ticket Telegram Bot Commands

## Main commands

`/start`

Register the Telegram user. New users stay pending until an administrator approves them.

`/help`

Show a short command summary in Telegram.

`/tic <ticket>`

Search similar solved tickets for an existing ticket. If the user has saved filters and the command does not specify an Area/Product/Competence/Client filter, saved filters are applied automatically.

Examples:

```text
/tic 658726
/tic 658726 area
/tic 658726 sottoarea
/tic 658726 prodotto
/tic 658726 competenza
/tic 658726 cliente
/tic 658726 no_cliente
/tic 658726 filtri
/tic 658726 recenti 24
/tic 658726 codice
/tic 658726 media
/tic 658726 alta
```

Filter meanings:

- `area`: only suggestions in the same Area as the query ticket.
- `sottoarea`: only suggestions in the same Sottoarea as the query ticket.
- `prodotto`: only suggestions with the same Product.
- `competenza`: only suggestions with the same Competence.
- `cliente`: only suggestions from the same Client.
- `no_cliente`: exclude suggestions from the same Client.
- `filtri`: apply or reapply the user's saved Product/Competence/Area/Subarea filters.
- `recenti <mesi>`: only suggestions opened in the last N months.
- `codice`: require the same detected error/code token.
- `media`: require at least medium confidence.
- `alta`: require high confidence.

Explicit IDs are also supported:

```text
/tic 658726 area 12
/tic 658726 sottoarea 44
/tic 658726 prodotto 24
/tic 658726 competenza 8
/tic 658726 cliente 1234
```

`/cerca <testo>`

Search similar solved tickets from free text, without needing a source ticket. Saved filters are applied automatically unless the command specifies an Area/Product/Competence/Client filter.

Examples:

```text
/cerca errore fiscality password non valida
/cerca --area 12 errore fiscality password non valida
/cerca --prodotto 24 --ultimi-mesi 18 errore importazione
/cerca --filtri --media errore stampa fattura
```

Supported `/cerca` flags:

- `--area <id>`
- `--sottoarea <id>`
- `--prodotto <id>`
- `--competenza <id>`
- `--cliente <id>`
- `--filtri`
- `--codice`
- `--ultimi-mesi <mesi>`
- `--media`
- `--alta`

## Inline result buttons

Every AI result includes inline buttons:

- `Dettaglio`: open the suggested ticket detail. For `/tic` searches, this also records weak positive feedback as `opened`.
- `Utile`: record useful feedback.
- `Non utile`: record negative feedback.
- `Preferito`: save the suggested ticket in your favorites and record positive feedback.
- `Altri risultati`: fetch the next page of results.
- `Solo area`, `Solo sottoarea`, `Solo prodotto`, `Solo competenza`, `Stesso cliente`, `Escludi cliente`: rerun the search with a stricter filter.
- `Recenti 24m`, `Stesso codice`, `Min media`, `Miei filtri`, `Reset`: rerun the search with the selected control.

Text feedback commands still work:

```text
/utile_<query_ticket>_<suggested_ticket>
/non_utile_<query_ticket>_<suggested_ticket>
```

Feedback is used during future AI ranking. `utile`, `preferito`, and opened details count as positive feedback; `non_utile` counts as negative feedback.

## Ticket detail and favorites

`/Ticket_dettaglio_<ticket>`

Download and send the HTML detail for a ticket.

`/preferito_<ticket>`

Save a ticket in your favorites and notify the administrator.

`/preferiti`

Show your saved favorite tickets. The same list is available from the `💜 Preferiti` keyboard button.

## Saved filters

The main keyboard exposes:

- `🖍 Crea filtro x Competenze`
- `📦 Crea filtro x Prodotto`
- `👥 Crea filtro x Area`
- `👥 Crea filtro x Sott.Area`
- `📌 I mie filtri`
- `✖ Cancella filtro`
- `💜 Preferiti`

Automatic new-ticket notifications use saved filters with AND between different types and OR inside the same type. For example: one Area + one Competence + two Products means Area AND Competence AND (Product 1 OR Product 2).

Generated filter commands:

```text
/_id_c_<competence_id>
/_id_p_<product_id>
/_id_area_<area_id>
/_id_suba_<subarea_id>
```

Generated delete commands:

```text
/Competen_id_cf_<filter_id>
/Prodotto_id_cf_<filter_id>
/Area_id_cf_<filter_id>
/Sottoarea_id_cf_<filter_id>
```

## Notification controls

`/notifiche_status`

Show personal notification settings.

`/notifiche_on`

Resume personal notifications.

`/notifiche_off`

Pause personal notifications.

`/silenzio <ora_inizio> <ora_fine>`

Set quiet hours. Hours are 0-23.

Example:

```text
/silenzio 22 7
```

`/silenzio_off`

Disable quiet hours.

`/digest <minuti>`

Send notifications at most once every N minutes.

Example:

```text
/digest 30
```

`/digest_off`

Disable digest throttling.

`/gravita_alta_on`

Only notify tickets whose gravity text looks high/urgent/critical/blocking.

`/gravita_alta_off`

Notify all gravity levels again.

## Admin commands

`/Approval_<telegram_user_id>`

Approve a pending user. This command is restricted to administrators.

`/ai_stats`

Show indexed ticket count, search count, no-result count, average retrieval time, and feedback totals.

`/ai_no_result`

Show recent AI searches with zero results.

`/ai_negative`

Show recent negative feedback.

`/ai_top_useful`

Show tickets with the most positive feedback.