Riferimento API

Notifiche

Manda una notifica all’app desktop IntelligenceBox di un utente — un titolo, una descrizione, un’icona e un link che apre la schermata giusta quando ci si clicca sopra. Le notifiche vengono salvate prima di essere consegnate, così una inviata mentre l’app era chiusa ricompare nella campanella al lancio successivo invece di sparire.

Come avviene la consegna

Ogni notifica viene prima scritta nel feed dell’utente, poi emessa via WebSocket verso le app connesse. Se non è connesso nessuno la riga resta comunque lì — è questo che rende l’API utilizzabile per build fallite, job notturni e qualsiasi altra cosa scatti fuori orario.

Inviare una notifica#

POST/api/public/notificationsAPI key

Crea e consegna una notifica. Restituisce la notifica salvata, con il suo id.

curl -X POST BOX_URL/api/public/notifications \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy finished",
    "description": "api-gateway v2.4.1 is live in production.",
    "type": "success",
    "category": "backgroundTasks",
    "icon": "Rocket",
    "name": "CI pipeline",
    "deepLink": "/inter/chat/deploy-log-2f8a"
  }'

Corpo della richiesta

Campo

titlestringobbligatorio: Il titolo. Compare come titolo del toast e come titolo della riga nella campanella. Massimo 200 caratteri.
descriptionstring: Il testo sotto il titolo. body è accettato come alias. Massimo 2000 caratteri.
type"info" | "success" | "error": Decide il colore d’accento e il tono dell’icona. Gli errori tengono il toast a schermo più a lungo.Predefinito: "info".
categorystring: Raggruppa la notifica e ne sceglie il simbolo predefinito. Vedi categorie.Predefinito: "system".
deepLinkstring: Percorso interno all’app aperto quando si clicca sulla notifica, ad esempio /calendar. Deve iniziare con / — vedi link diretti.
iconstring: Nome di un’icona Lucide in PascalCase, ad esempio Rocket, AlertTriangle, Package.
namestring: Da chi arriva la notifica, ad esempio «CI pipeline». Compare accanto all’icona.
senderobject: Controllo completo sull’elemento visivo iniziale — vedi mittente. Ha la precedenza su icon e name.
previewstring: Riga secondaria breve. Preferita rispetto a description quando ci sono entrambe.
readboolean: Creala già letta. Finisce nello storico senza far salire il contatore dei non letti — utile per le voci di tracciamento.Predefinito: false.
dedupeKeystring: Accorpa le ripetizioni: un secondo invio con la stessa chiave aggiorna la riga esistente invece di aggiungerne una nuova.
resurfaceboolean: Ha senso solo insieme a dedupeKey. Metti false per uno stato persistente («la sincronizzazione è in pausa»), così viene annunciato una volta sola e resta silenzioso a ogni invio identico successivo.Predefinito: true.
silentToastboolean: Mantiene il popup di sistema e la riga nella campanella, salta il toast dentro l’app.Predefinito: false.
silentboolean: Solo salvataggio. La riga compare nella campanella senza popup e senza toast.Predefinito: false.
chatIdstring: Apre questa conversazione al clic e aggiunge al toast un pulsante «Apri chat».
userIdstring: Consegna a un altro utente invece che al proprietario della chiave. Richiede un contesto di organizzazione — vedi inviare a qualcun altro.
metadataobject: JSON libero restituito quando la notifica viene letta. Massimo 8 KB serializzati.

Risposta

JSON

{
  "delivered": true,
  "persisted": true,
  "notification": {
    "id": "5c1e0f2a-9d84-4a1b-8f3c-2b7e0a6d1f45",
    "title": "Deploy finished",
    "description": "api-gateway v2.4.1 is live in production.",
    "type": "success",
    "category": "backgroundTasks",
    "deepLink": "/inter/chat/deploy-log-2f8a",
    "chatId": null,
    "icon": "Rocket",
    "sender": { "kind": "system", "name": "CI pipeline", "icon": "Rocket" },
    "read": false,
    "seen": false,
    "createdAt": "2026-08-03T09:14:22.401Z"
  }
}

201Creata e consegnata.
202Consegnata dal vivo ma non salvata (persisted: false). L’utente la vede adesso; non la ritroverà nella campanella.
400Validazione fallita — controlla details per sapere quale campo non va.
403Il destinatario è fuori dallo spazio di lavoro dell’organizzazione.

Icona, nome e avatar#

L’elemento visivo iniziale viene scelto dall’oggetto sender. Quattro tipi, ognuno reso in modo diverso.

Mittente

kind"system" | "user" | "assistant" | "email": system disegna icon come simbolo; user e assistant mostrano imageUrl come avatar; email mostra le iniziali del mittente.Predefinito: "system".
namestring: Nome mostrato accanto alla notifica.
imageUrlstring: URL assoluto di un’immagine avatar. Usato dai tipi user e assistant.
iconstring: Nome dell’icona Lucide, usato quando non c’è un’immagine.
colorstring: Tinta esadecimale per lo sfondo del simbolo, ad esempio #3B82F6.
emailstring: Indirizzo del mittente — genera le iniziali di riserva per il tipo email.

JSON

{
  "title": "Marco Rossi mentioned you",
  "description": "\"can you review the Q3 numbers?\"",
  "category": "messaging",
  "deepLink": "/messaggi",
  "sender": {
    "kind": "user",
    "name": "Marco Rossi",
    "imageUrl": "https://example.com/avatars/marco.jpg"
  }
}

Scorciatoia

Nel caso comune di sistema puoi saltare del tutto l’oggetto e mandare icon e name al primo livello. Vengono raccolti in un mittente system per te.

Link diretti#

Dove porta il clic sulla notifica. Funziona qualsiasi percorso interno all’app; questi sono quelli che userai davvero.

Percorso	Apre
`/inter/chat/:chatId`	Una conversazione specifica
`/dc/vector/:vectorId`	Una cartella e i suoi documenti
`/assistants`	L’elenco degli assistenti
`/calendar`	Il calendario
`/email`	La posta unificata
`/messaggi`	I messaggi
`/messaggi?channel=:id`	Un singolo canale di messaggi
`/contacts`	La rubrica
`/work`	Gestione del lavoro
`/recordings`	Le registrazioni audio
`/workbox`	Le automazioni Workbox
`/settings`	Le impostazioni

Solo percorsi interni all’app

deepLink deve iniziare con /. Gli URL assoluti vengono rifiutati con un 400: l’app passa il valore al proprio router, quindi un valore https:// sarebbe nel migliore dei casi un clic a vuoto.

Quando ci sono più destinazioni vince la più specifica: chatId batte deepLink. Un chatId aggiunge anche un pulsante «Apri chat» esplicito al toast.

Categorie#

La categoria decide il simbolo predefinito, l’etichetta sulla riga nella campanella e quale preferenza dell’utente può silenziarla.

Categoria	Usala per	Silenziabile
`system`	Tutto quello che non rientra altrove	No
`backgroundTasks`	Job, build, importazioni, lavori lunghi	Sì
`chat`	Esecuzioni AI e completamenti	Sì
`calendar`	Promemoria ed eventi	Sì
`email`	Attività di posta	Sì
`messaging`	Messaggi e menzioni	No
`scheduler`	Esecuzioni pianificate	Sì
`contacts`	Arricchimento e sincronizzazione contatti	Sì
`transcription`	Trascrizione audio	Sì
`misconduct`	Sicurezza e moderazione	Sì
`appUpdates`	Disponibilità di aggiornamenti dell’app	Sì

Le categorie silenziabili possono essere spente dall’utente

Le categorie contrassegnate come silenziabili corrispondono a un interruttore in Impostazioni → Notifiche. Se l’utente ne ha spenta una, la tua notifica viene accettata ma non mostrata. Per gli avvisi che devono arrivare sempre usa system o messaging — nessuna delle due dipende dall’utente.

Evitare il diluvio di notifiche#

Due manopole per i job che girano a intervalli e continuano a segnalare la stessa cosa.

Aggiornare una riga invece di accumularle

Una build che riporta l’avanzamento ogni minuto non dovrebbe lasciare sessanta righe nella campanella. Dai a ogni invio lo stesso dedupeKey e ognuno aggiorna la riga esistente sul posto, riportandola a non letta.

JSON

{
  "title": "Indexing 340/1200 documents",
  "category": "backgroundTasks",
  "dedupeKey": "index-run:2026-08-03"
}

Annunciare uno stato persistente una volta sola

Una condizione che è ancora vera — una sincronizzazione in pausa, una credenziale scaduta — va annunciata una volta, non a ogni controllo. Aggiungi resurface: false: il primo invio notifica, ogni invio identico successivo viene assorbito in silenzio.

JSON

{
  "title": "SharePoint sync paused",
  "description": "Credentials expired — reconnect in Settings.",
  "type": "error",
  "dedupeKey": "sync-paused:sharepoint",
  "resurface": false
}

Inviare a qualcun altro#

Per impostazione predefinita una notifica va all’utente proprietario della chiave API. Per avvisare un collega manda il suo userId insieme a un contesto di organizzazione — entrambi gli account devono appartenere allo stesso spazio di lavoro.

Shell

curl -X POST BOX_URL/api/public/notifications \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Invoice awaiting approval",
    "description": "INV-2026-0412 from Acme Srl — €12,480.",
    "userId": "8f2c1d40-33ab-4e7e-9c15-6a0b2e91d774",
    "deepLink": "/work"
  }'

403O non è stata mandata l’intestazione dell’organizzazione, oppure il destinatario non fa parte di quello spazio di lavoro.

Elencare le notifiche#

GET/api/public/notificationsAPI key

Le notifiche del proprietario della chiave, dalla più recente.

Query

limitinteger: Quante restituirne, da 1 a 200.Predefinito: 50.
offsetinteger: Righe da saltare, per la paginazione.Predefinito: 0.
unreadOnlyboolean: Restituisce solo le notifiche non lette.
categorystring: Filtra su una sola categoria.

Shell

curl "BOX_URL/api/public/notifications?unreadOnly=true&limit=20" \
  -H "x-api-key: YOUR_API_KEY"

JSON

{
  "notifications": [ /* … */ ],
  "unreadCount": 3,
  "pagination": { "total": 41, "limit": 20, "offset": 0, "hasMore": true }
}

Contatore dei non letti#

GET/api/public/notifications/unread-countAPI key

Solo il numero, per un badge da mettere altrove.

JSON

{ "count": 3 }

Leggere una notifica#

GET/api/public/notifications/:idAPI key

La notifica salvata per intero, metadata compresi.

Segnare letta o non letta#

PATCH/api/public/notifications/:idAPI key

Campo

readboolean: Segnala come letta (che la segna anche come vista) o riportala a non letta.
seenboolean: Registra che è stata consegnata senza azzerare il contatore dei non letti.

Shell

curl -X PATCH BOX_URL/api/public/notifications/5c1e0f2a-9d84-4a1b-8f3c-2b7e0a6d1f45 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "read": true }'

Segnare tutto come letto#

POST/api/public/notifications/read-allAPI key

JSON

{ "updated": 12 }

Eliminare una notifica#

DELETE/api/public/notifications/:idAPI key

La rimuove dal feed in modo definitivo.

JSON

{ "success": true }

Ricette#

Avvisare di un job fallito, con il link ai log

Shell

curl -X POST BOX_URL/api/public/notifications \
  -H "x-api-key: $BOX_KEY" -H "Content-Type: application/json" \
  -d '{
    "title": "Nightly import failed",
    "description": "12 of 340 invoices could not be parsed.",
    "type": "error",
    "category": "backgroundTasks",
    "icon": "AlertTriangle",
    "name": "Invoice importer",
    "deepLink": "/dc/vector/'"$FOLDER_ID"'",
    "dedupeKey": "import-failure:invoices"
  }'

Registrare una voce silenziosa di tracciamento

silent insieme a read: true scrive nello storico senza popup, senza toast e senza contatore di non letti — una riga di log che l’utente può trovare se va a cercarla.

JSON

{
  "title": "Contract archived",
  "description": "MSA-Acme-2026.pdf moved to Legal / Archive.",
  "category": "system",
  "silent": true,
  "read": true,
  "metadata": { "documentId": "b71f…", "actor": "retention-bot" }
}

Vedi anche: esegui un assistente e avvisa l’utente quando ha finito, oppure scopri il destinatario che sta dietro alla tua chiave API.