Iniziare con l'API

L’API pubblica di Nuntius è una superficie REST curata — lead, contatti, conversazioni, appuntamenti e ticket del tuo account — pensata per integrare il tuo codice, il tuo CRM o la tua automazione con il tuo account, senza passare dall’interfaccia web. Non è uno specchio di tutto ciò che fa la Piattaforma: esistono rotte solo per questi 5 risorse, qualunque sia il permesso della tua chiave.

Disponibile sui piani Pro ed Enterprise. Con il piano Starter, qualsiasi chiamata restituisce 403 PLAN_NOT_ELIGIBLE anche se la chiave e il permesso sono corretti — vedi Piani e limiti.

1. Crea la tua chiave

Le chiavi API si creano e si gestiscono da Profilo → Le mie chiavi API (o Impostazioni → Chiavi API per una chiave aziendale) — la procedura completa, con screenshot, è nella guida Chiavi API. Quando la crei:

• In “Cosa può fare questa chiave”, premi “Personalizza” e seleziona solo le risorse di cui la tua integrazione ha bisogno — vedi l’elenco completo in Autenticazione. Una chiave senza il permesso di una risorsa riceve 403 PERMISSION_DENIED sulle sue rotte, anche se il resto della chiave funziona.
• La chiave completa viene mostrata una sola volta: copiala in un gestore di segreti prima di chiudere la finestra.

2. Verifica la tua chiave

GET /me non richiede nessun permesso proprio — solo una chiave valida di un tenant con piano idoneo — quindi è il modo più veloce per confermare che tutto sia in ordine:

curl https://api.nuntius.chat/public/v1/me \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"

{
  "tenantId": "b3f5b6b0-...",
  "keyPrefix": "aa_1b2e1ebd",
  "scopes": ["tenant:leads.read", "tenant:leads.manage"],
  "plan": "pro",
  "rateLimit": { "perMinute": 180, "perDay": 50000 }
}

Se scopes non include quello che ti aspettavi, controlla la selezione “Personalizza” della tua chiave (guida delle chiavi API, sezione 7) — la selezione resta fissata alla creazione, non si aggiorna da sola.

3. Fai la tua prima chiamata di business

Con una chiave che ha tenant:leads.read, elenca i lead più recenti:

curl "https://api.nuntius.chat/public/v1/leads?dateFrom=2026-01-01" \
  -H "X-API-Key: aa_TUA_CHIAVE_COMPLETA"

Ogni risposta di lista usa lo stesso formato di paginazione del resto dell’API — controlla il campo meta della risposta per richiedere la pagina successiva.

Prima di automatizzare l’invio di messaggi

POST /public/v1/conversations/{id}/messages e POST /public/v1/conversations/start consegnano il messaggio al canale reale, ma non compaiono all’istante nell’inbox della Piattaforma né nel widget del visitatore — un operatore umano li vede al successivo aggiornamento/riconnessione della sua schermata, non in tempo reale. Se la tua integrazione ha bisogno che un operatore reagisca subito, avvisalo anche per un’altra via (il tuo sistema, un ticket…) oltre a inviare il messaggio. Dettaglio completo nel gruppo Conversazioni della referenza.

Continua da qui

• Autenticazione — l’header X-API-Key, il catalogo completo dei permessi.
• Piani e limiti — quale piano ti serve e quante chiamate puoi fare.
• Errori — l’envelope di errore e il catalogo completo dei codici.
• Casi d’uso — 5 integrazioni reali con esempi di codice brevi.
• Referenza, nella barra laterale — una pagina per operazione, generata dalla definizione OpenAPI reale.

Domande durante l’integrazione? Scrivi a hola@nuntius.chat.