# Avvisi via email e Novità

`GET /v1/notices`

Gli **avvisi dei tuoi numeri e delle tue attivazioni** —un numero scollegato o rimosso, che si collega e scollega, bloccato da Meta o senza carta, invii rifiutati, un modello approvato o bloccato, il webhook che fallisce, la cronologia in scadenza, un numero collegato, vicino ai 1.000 messaggi gratuiti, un calo dell'uso, la scheda dell'attivazione del tuo cliente— restano **sempre** in **Novità** (nel pannello e via API). Scegli tu se arrivano anche via email.

**L'interruttore dell'account.** `GET /v1/account/settings` e `PATCH /v1/account/settings` con `{"emailNotices": false}`. Predefinito: `true`.

**L'eccezione di ogni numero.** `PATCH /v1/connections/{id}` con `emailNotices`: `inherit` (quello che dice l'account, il predefinito), `on` o `off`. Ogni numero porta `emailNotices` e `emailNoticesEffective` (se oggi i suoi avvisi vanno via email). Un avviso di un numero va via email se il numero dice `on`, oppure dice `inherit` e l'account ha `emailNotices: true`; uno che non è di un numero segue l'account.

**Leggerli.** `GET /v1/notices` (il più recente per primo; `connectionId`, `unread=true`, `limit` da 1 a 100, `before` = il `nextBefore` della pagina precedente, `lang`). Ogni avviso porta lo stesso testo dell'email (`subject`, `heading`, `paragraphs`, cosa fare, pulsante) e `emailStatus`: `suppressed_by_preference` = non è partita per il tuo interruttore. `POST /v1/notices/{id}/read` lo segna come letto, anche nel pannello; `POST /v1/notices/read-all` li segna tutti in una volta (restituisce `updated`, quanti ne ha segnati).

**Nel pannello.** **Impostazioni › Notifiche** (l'account e numero per numero) e la casella **Novità**. Ogni email di questi avvisi ha in fondo «Non vuoi ricevere queste email? Configura i tuoi avvisi».

## Esempi

### cURL

```bash
# 1) stop emailing the notices about your numbers (they stay in /v1/notices)
curl -X PATCH https://api.waiaconnect.com/v1/account/settings -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"emailNotices": false}'
# → { "settings": { "emailNotices": false } }

# 2) …but keep emailing this one number (inherit | on | off)
curl -X PATCH https://api.waiaconnect.com/v1/connections/conn_73dc… -H "Authorization: Bearer wc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" -d '{"emailNotices": "on"}'

# 3) read the unread notices, in your language
curl "https://api.waiaconnect.com/v1/notices?unread=true&lang=en" -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "notices": [ { "id": 1234, "type": "connection_disconnected", "connectionId": "conn_73dc…",
#       "emailStatus": "suppressed_by_preference", "subject": "…", "paragraphs": ["…"], "cta": { … } } ],
#     "unreadCount": 1, "nextBefore": null }

# 4) mark one as read (idempotent)
curl -X POST https://api.waiaconnect.com/v1/notices/1234/read -H "Authorization: Bearer wc_live_YOUR_API_KEY"

# 5) …or mark them all as read at once
curl -X POST https://api.waiaconnect.com/v1/notices/read-all -H "Authorization: Bearer wc_live_YOUR_API_KEY"
# → { "updated": 3 }
```

### Node.js

```javascript
const H = { "Authorization": "Bearer wc_live_YOUR_API_KEY", "Content-Type": "application/json" };

// the account switch, and one number that keeps emailing
await fetch("https://api.waiaconnect.com/v1/account/settings", { method: "PATCH", headers: H, body: JSON.stringify({ emailNotices: false }) });
await fetch("https://api.waiaconnect.com/v1/connections/conn_73dc…", { method: "PATCH", headers: H, body: JSON.stringify({ emailNotices: "on" }) });

// the unread notices, newest first
const { notices, unreadCount } = await (await fetch("https://api.waiaconnect.com/v1/notices?unread=true&lang=en", { headers: H })).json();
for (const n of notices) {
  console.log(n.type, n.connectionId, n.subject);
  await fetch(`https://api.waiaconnect.com/v1/notices/${n.id}/read`, { method: "POST", headers: H });
}
```

### PHP

```php
<?php
$h = ["Authorization: Bearer wc_live_YOUR_API_KEY", "Content-Type: application/json"];
$ch = curl_init("https://api.waiaconnect.com/v1/account/settings");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_HTTPHEADER => $h,
  CURLOPT_POSTFIELDS => json_encode(["emailNotices" => false]),
]);
curl_exec($ch);

$ch = curl_init("https://api.waiaconnect.com/v1/notices?unread=true&lang=en");
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => $h]);
$notices = json_decode(curl_exec($ch), true)["notices"];
foreach ($notices as $n) {
  echo $n["type"] . " " . $n["subject"] . "\n";
  $r = curl_init("https://api.waiaconnect.com/v1/notices/" . $n["id"] . "/read");
  curl_setopt_array($r, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_HTTPHEADER => $h]);
  curl_exec($r);
}
```

### Python

```python
import requests
H = {"Authorization": "Bearer wc_live_YOUR_API_KEY"}

# the account switch, and one number that keeps emailing
requests.patch("https://api.waiaconnect.com/v1/account/settings", headers=H, json={"emailNotices": False})
requests.patch("https://api.waiaconnect.com/v1/connections/conn_73dc…", headers=H, json={"emailNotices": "on"})

# the unread notices, newest first
page = requests.get("https://api.waiaconnect.com/v1/notices", headers=H, params={"unread": "true", "lang": "en"}).json()
for n in page["notices"]:
    print(n["type"], n["connectionId"], n["subject"])
    requests.post(f"https://api.waiaconnect.com/v1/notices/{n['id']}/read", headers=H)
```

## Note

- **Arrivano sempre via email**, qualunque cosa dicano gli interruttori: fatturazione e pagamenti, sicurezza e accesso, avvisi legali, risposte dell'assistenza e il benvenuto.
- Un `emailNotices` dell'account che non sia `true`/`false` restituisce `400 SETTINGS_INVALID`; quello di un numero che non sia `inherit`, `on` o `off`, `400 CONNECTION_EMAIL_NOTICES_INVALID`.
- Un parametro non valido di `GET /v1/notices` restituisce `400 NOTICES_QUERY_INVALID`; un `connectionId` di un altro account, `404 CONNECTION_NOT_FOUND`; un avviso di un altro account, `404 NOTICE_NOT_FOUND`.
- `type` è un testo aperto (`connection_disconnected`, `template_first_approved`…): si aggiungono tipi nuovi.