---
title: Notifiche dirette - chiavi API personali per avvisi immediati
sidebarTitle: Diretto
description: Invia notifiche direttamente con una chiave API personale, senza configurare canali. Crea chiavi dirette e attiva avvisi immediati con titolo, testo e link.
---

# Notifiche dirette

Le notifiche dirette ti permettono di inviare avvisi personali tramite un semplice URL webhook — senza configurare canali, senza modelli, senza iscritti. Basta creare una chiave, chiamare l'URL e ricevere subito la notifica sul tuo dispositivo.

## Che cos'è Diretto?

I canali sono ottimi per notifiche strutturate e basate su modelli, che puoi condividere con altre persone. A volte però ti serve solo una notifica rapida e personale: una build finita, uno script completato, un sensore che si è attivato. Diretto nasce esattamente per questo.

Con Diretto ottieni una chiave API personale associata a un URL webhook univoco. Quando chiami quell'URL con un titolo e un testo, la notifica arriva direttamente a te. Nessuna configurazione di canale.

### Quando usare Diretto e quando i canali

| | Diretto | Canali |
|---|---|---|
| **Configurazione** | Crei una chiave e usi l'URL | Crei un canale e imposti i modelli |
| **Destinatari** | Solo tu | Chiunque si iscriva |
| **Modelli** | Nessuno: indichi titolo e testo a ogni richiesta | Modelli configurabili con variabili |
| **Condizioni** | Nessuna | Consegna condizionale supportata |
| **Ideale per** | Script personali, avvisi rapidi, automazioni | Avvisi condivisi, flussi di lavoro strutturati |

## Primi passi

### 1. Crea una chiave diretta

Nell'app Echobell, tocca **Diretto** in cima all'elenco dei canali. Poi tocca **Crea** per generare una nuova chiave diretta. Dalle un nome descrittivo (ad esempio "Server di build", "Home Lab", "Trading Bot").

### 2. Copia l'URL webhook

Ogni chiave diretta ha un URL webhook univoco in questo formato:

```
https://hook.echobell.one/d/{your-key-token}
```

Puoi trovare e copiare questo URL dalla schermata di dettaglio della chiave diretta nell'app. Per sicurezza il token è nascosto per impostazione predefinita: tocca per mostrarlo.

### 3. Invia una notifica

Chiama l'URL webhook con un body JSON che contenga `title` e `body`:

```http
POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Build Complete",
  "body": "Project X built successfully in 3m 42s"
}
```

Tutto qui: la notifica ti arriva immediatamente.

## Inviare richieste

### Richiesta POST (consigliata)

Invia un body JSON con il contenuto della notifica:

```http
POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Deployment Status",
  "body": "v2.1.0 deployed to production",
  "externalLink": "https://dashboard.example.com/deploys/latest"
}
```

### Richiesta GET

Puoi anche passare i parametri nella query string:

```http
GET https://hook.echobell.one/d/YOUR_KEY_TOKEN?title=Alert&body=CPU+at+95%25
```

### Solo POST

Ogni chiave diretta ha la propria impostazione **Solo POST** nell'app Echobell. È disattivata per impostazione predefinita.

Quando è attiva, solo `POST` può attivare quella chiave. Una `GET` al suo URL webhook viene rifiutata con `405 Method Not Allowed` e non viene inviata nessuna notifica:

```json
{
  "success": false,
  "notificationTriggered": false,
  "message": "This trigger only accepts POST requests; GET triggering is disabled in its settings."
}
```

Le richieste `HEAD` non sono interessate: rispondono `200` e non attivano mai una notifica, che Solo POST sia attivo o meno.

L'impostazione vale per singola chiave, quindi puoi tenere una chiave compatibile con `GET` per i one-liner da shell e una chiave solo POST per gli URL che finiscono incollati in chat o su pagine wiki.

### Campi della richiesta

I nomi dei campi **non fanno distinzione tra maiuscole e minuscole**: `title`, `Title` e `TITLE` vengono trattati allo stesso modo, sia che li passi nel body JSON sia nella query string.

| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `title` | string | No | Titolo della notifica. Se omesso, il valore predefinito è "Direct Notification". |
| `body` | string | No | Testo della notifica. |
| `externalLink` | string | No | Un link cliccabile mostrato nel record della notifica. |
| `notificationType` | string | No | Livello di urgenza della notifica. Accetta `active`, `time-sensitive` o `calling`. Il valore predefinito è `active`. Vedi [Tipi di notifica](#tipi-di-notifica). |

### Tipi di notifica

Puoi controllare il livello di urgenza delle notifiche dirette con il campo `notificationType`:

| Tipo | Descrizione |
|---|---|
| `active` | Notifica normale, consegnata senza priorità particolari. È il valore predefinito. |
| `time-sensitive` | Notifica ad alta priorità, in grado di superare le modalità Full Immersion. |
| `calling` | Avviso in stile chiamata per le situazioni critiche. **Richiede un abbonamento Premium attivo.** Senza Premium viene usato `time-sensitive`. |

Esempio con il tipo di notifica:

```http
POST https://hook.echobell.one/d/YOUR_KEY_TOKEN
Content-Type: application/json

{
  "title": "Server Down",
  "body": "Production server is unresponsive",
  "notificationType": "calling"
}
```

## Formato della risposta

Una richiesta andata a buon fine restituisce:

```json
{
  "success": true,
  "message": "Notification triggered successfully."
}
```

Se la chiave non è valida o non esiste (nota che la risposta HTTP resta `200`):

```json
{
  "success": false,
  "message": "Direct key not found."
}
```

## Gestire le chiavi dirette

### Più chiavi

Puoi creare più chiavi dirette per scopi diversi:

- **"Server CI"** — per le notifiche di build e di deploy
- **"Domotica"** — per gli avvisi dei sensori IoT
- **"Cron job"** — per i risultati delle attività pianificate
- **"Trading Bot"** — per gli avvisi di mercato

Ogni chiave ha il proprio URL webhook indipendente. I record delle notifiche vengono associati automaticamente alla chiave che li ha generati, così capisci al volo quale servizio ha inviato ogni notifica.

### Reimposta il token

Se l'URL webhook di una chiave viene compromesso, puoi reimpostare il token dalla schermata di dettaglio della chiave. Viene generato un nuovo URL e quello vecchio smette di funzionare all'istante. Ricordati di aggiornare gli script e i servizi che usano il vecchio URL.

### Elimina una chiave

Eliminando una chiave diretta, il suo URL webhook diventa definitivamente non valido. Tutte le richieste al vecchio URL falliranno.

## Casi d'uso comuni

### Script di shell

```bash
# Notify when a long-running task finishes
./run-migration.sh && \
curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"title": "Migration Complete", "body": "Database migration finished successfully"}'
```

### Cron job

```bash
# In crontab: notify on backup completion
0 2 * * * /usr/local/bin/backup.sh && curl -s -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN -H "Content-Type: application/json" -d '{"title": "Backup Done", "body": "Nightly backup completed"}'
```

### Python

```python
import requests

requests.post(
    "https://hook.echobell.one/d/YOUR_KEY_TOKEN",
    json={
        "title": "Training Complete",
        "body": f"Model accuracy: {accuracy:.2%}",
        "externalLink": "https://wandb.ai/runs/abc123"
    }
)
```

### Node.js

```javascript
await fetch("https://hook.echobell.one/d/YOUR_KEY_TOKEN", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    title: "Deploy Complete",
    body: `Version ${version} deployed to production`,
  }),
});
```

### GitHub Actions

```yaml
- name: Notify via Echobell Direct
  if: always()
  env:
    ECHOBELL_DIRECT_URL: ${{ secrets.ECHOBELL_DIRECT_URL }}
  run: |
    curl -X POST "$ECHOBELL_DIRECT_URL" \
      -H "Content-Type: application/json" \
      -d '{"title": "Build ${{ job.status }}", "body": "${{ github.repository }} @ ${{ github.sha }}"}'
```

## Best practice

### Sicurezza

- **Tratta gli URL delle chiavi dirette come segreti** — chiunque abbia l'URL può inviarti notifiche
- **Usa le variabili d'ambiente** per conservare i token delle chiavi negli script e nelle pipeline CI/CD
- **Reimposta i token** appena sospetti che una chiave sia stata compromessa
- **Crea chiavi separate** per servizi diversi, così puoi revocarle una alla volta

### Organizzazione

- **Dai alle chiavi nomi descrittivi** — te ne sarai grato quando ne avrai parecchie da gestire
- **Usa una chiave per ogni servizio** — così individui subito la fonte di una notifica e revochi solo quella
- **Elimina le chiavi inutilizzate** — riduci la superficie di attacco

### Gestione degli errori

Quando integri Diretto nei tuoi script, basati sul campo JSON `success` invece che sullo stato HTTP:

- **200 OK**: la richiesta è arrivata. Controlla il body JSON: `success: true` significa che la notifica è stata inviata, `success: false` che non è partita. Una chiave diretta sconosciuta o reimpostata risponde con HTTP `200` e `{ "success": false, "message": "Direct key not found." }`, **non** con un `404`.
- **400 Bad Request**: il token della chiave ha una lunghezza sbagliata. Correggi l'URL.
- **405 Method Not Allowed**: la chiave ha [Solo POST](#solo-post) attivo e la richiesta non era una `POST`. Fai passare il chiamante a `POST` oppure disattiva l'impostazione.

Echobell non applica limiti di frequenza alle chiamate dirette, quindi non esiste una risposta `429`.

## Privacy e sicurezza

### Cosa viene memorizzato

- **Sui nostri server**:
  - i metadati della chiave diretta (nome, token con hash, proprietario)
  - il payload della richiesta, elaborato e conservato temporaneamente per la consegna

- **Sul tuo dispositivo**:
  - il contenuto della notifica (titolo e testo)
  - la cronologia dei trigger e i relativi orari
  - i link esterni

### Cosa non viene memorizzato

- Non conserviamo in modo permanente i payload delle richieste dopo la consegna
- Non analizziamo il contenuto delle notifiche
- Non condividiamo i tuoi dati con terze parti

## Risoluzione dei problemi

### Non ricevi le notifiche

1. **Verifica l'URL webhook** — copialo direttamente dall'app e controlla che non ci siano spazi di troppo
2. **Controlla che la chiave esista ancora** — potrebbe essere stata eliminata o il token reimpostato
3. **Verifica i permessi per le notifiche** — l'app Echobell deve poter inviare notifiche sul tuo dispositivo
4. **Fai una prova con curl** — per escludere problemi del tuo client HTTP:
   ```bash
   curl -X POST https://hook.echobell.one/d/YOUR_KEY_TOKEN \
     -H "Content-Type: application/json" \
     -d '{"title": "Test", "body": "Hello from Direct"}'
   ```

### Errori nelle richieste

- **Errore di parsing JSON**: assicurati che l'header `Content-Type: application/json` sia impostato e che il body sia JSON valido
- **Chiave non trovata**: un body con `"success": false` e `"Direct key not found."` significa che il token è stato reimpostato o che la chiave è stata eliminata (lo stato HTTP resta comunque `200`)

### Hai ancora problemi?

- Visita il nostro [Centro assistenza](/docs/support) per altro supporto
- Scrivici a echobell@weelone.com indicando:
  - una descrizione del problema
  - un esempio di richiesta (con il token oscurato)
  - il comportamento atteso e quello effettivo

## Prossimi passi

- **[Integrazione webhook](/docs/webhook)** — per notifiche condivise e basate su modelli, tramite i canali
- **[Sintassi dei modelli](/docs/template)** — impara a usare i modelli di notifica dei canali
- **[Trigger via email](/docs/email-trigger)** — attiva le notifiche via email
- **[Esplora le integrazioni](/docs/features)** — collega gli strumenti che usi già