Quando serve davvero l'API di AI SNS CHAT, come usare chiavi, streaming SSE e webhook firmati, rispettando i limiti di frequenza e la privacy.
Il vostro assistente AI risponde bene su WhatsApp e sul sito, ma a un certo punto serve qualcosa che nessun pulsante di configurazione offre: un gestionale interno da interrogare, un'interfaccia di chat su misura, un sistema che reagisca a ciò che accade nelle conversazioni. In questi casi la REST API di AI SNS CHAT è lo strumento giusto. Questa guida spiega quando conviene usarla, quali sono i componenti, quali limiti rispettare e come metterla in produzione senza sorprese.
Quando l'API è lo strumento giusto (e quando no)
Prima di scrivere una riga di codice, chiedetevi se il risultato che cercate esiste già come funzione integrata. AI SNS CHAT offre un lungo elenco di canali pronti, tra cui widget sul sito, WhatsApp, Messenger, Instagram, Telegram, Slack ed email, oltre a integrazioni preconfigurate. Per queste strade non serve alcuno sviluppo: si collega il canale e l'agente risponde.
L'API ha senso quando il vostro caso è davvero specifico. Alcuni esempi tipici per una piccola o media impresa:
- una web app o un portale clienti con un'interfaccia di chat progettata da voi, non il widget standard;
- un'app mobile aziendale in cui la conversazione deve integrarsi con login e dati dell'utente;
- un sistema interno che deve ricevere una notifica quando una conversazione richiede attenzione;
- un flusso che collega le conversazioni a un software gestionale non coperto dalle integrazioni esistenti.
Al contrario, se vi serve soltanto "mettere l'assistente su WhatsApp e Messenger", l'API è eccessiva: costa tempo di sviluppo, richiede manutenzione e non aggiunge nulla.
I componenti di base
L'API di AI SNS CHAT è una REST API che scambia dati in JSON. Per un integratore i pezzi da conoscere sono pochi.
Chiavi API
Si creano da Impostazioni dello spazio di lavoro → Chiavi API. La chiave viene mostrata una sola volta al momento della creazione: copiatela subito in un luogo sicuro, perché non sarà più visibile. Le chiavi sono revocabili in qualsiasi momento, il che permette di sostituirle senza fermare tutto il resto. L'uso delle chiavi richiede il piano Hobby o superiore.
Richieste e risposte
Le richieste di chat restituiscono la risposta dell'agente in JSON. Per i dettagli di percorsi, parametri e formati fate sempre riferimento alla documentazione API pubblicata, che è la fonte aggiornata: evitate di dedurre comportamenti da esempi trovati altrove.
Streaming con SSE
Se volete mostrare la risposta mentre viene generata, come nelle chat moderne, potete attivare lo streaming con il parametro stream=1. Le risposte arrivano come Server-Sent Events, un flusso a senso unico dal server al client, semplice da gestire anche in un browser. È una scelta utile per ridurre la percezione di attesa nelle risposte lunghe.
Webhook firmati
Per essere avvisati di ciò che accade, AI SNS CHAT può chiamare un vostro indirizzo con webhook firmati tramite HMAC. La firma vi permette di verificare che la richiesta provenga davvero dalla piattaforma e non da qualcuno che finge di essere lei. Esiste anche un registro delle consegne, dove controllare cosa è stato inviato e con quale esito.
- 01Il vostro sistema o app
- 02Richiesta API con chiave
- 03Agente AI SNS CHAT risponde (JSON o SSE)
- 04Webhook firmato verso il vostro server
Rispettate i limiti di frequenza pubblicati
L'API ha limiti di frequenza documentati, e conviene progettare l'integrazione tenendoli a mente fin dall'inizio, non dopo il primo blocco in produzione. I valori pubblicati sono questi:
| Ambito | Limite |
|---|---|
| Autenticazione | 20 richieste ogni 5 minuti per IP |
| Chat pubblica | 30 richieste al minuto per IP |
| Polling | 120 richieste al minuto |
Qualche conseguenza pratica:
- Non fate polling aggressivo. Se avete bisogno di sapere quando qualcosa cambia, un webhook è più efficiente e più economico di interrogazioni ripetute.
- Attenzione al limite per IP. Se molti utenti passano da un unico indirizzo, per esempio un ufficio dietro lo stesso router o un server che inoltra tutte le chiamate, condividono lo stesso budget di richieste.
- Gestite le risposte di rifiuto. Quando un limite viene superato, il vostro codice deve attendere e riprovare con intervalli crescenti, senza martellare il servizio.
- Autenticatevi una volta sola e riutilizzate la sessione, invece di ripetere l'autenticazione a ogni richiesta: il limite è di sole 20 ogni 5 minuti.
Un esempio ipotetico: se il vostro sito riceve picchi di visite dopo una campagna e ogni visitatore apre una chat dallo stesso server proxy, 30 richieste al minuto per IP possono diventare un collo di bottiglia. Meglio verificarlo in fase di test che il giorno del lancio.
Schemi di progetto che funzionano
Il vostro server fa da intermediario
Evitate di inserire la chiave API nel codice che gira nel browser o nell'app: chiunque potrebbe leggerla. Fate passare le richieste da un vostro server, che custodisce la chiave e decide cosa può fare ciascun utente.
Webhook al posto del polling
Quando dovete reagire a un evento, per esempio avvisare un collega o aggiornare un gestionale, ricevete la notifica su un indirizzo vostro e rispondete rapidamente. Fate il lavoro pesante in un secondo momento, in coda, così da non tenere occupata la connessione.
Operazioni ripetibili
I webhook possono arrivare più di una volta, per esempio dopo un tentativo di riconsegna. Scrivete il codice in modo che elaborare due volte lo stesso evento non produca duplicati, come due ordini o due email di conferma.
Streaming dove serve, risposta intera altrove
Usate stream=1 nelle interfacce in cui una persona legge in diretta. Per i processi automatici, dove nessuno guarda, la risposta completa in JSON è più semplice da elaborare.
Tenete il perimetro stretto
Dare all'integrazione solo ciò che le serve riduce i rischi. Se il gestionale deve soltanto leggere lo stato di un ordine, non fornite credenziali con permessi di modifica. Per le consultazioni a sola lettura, AI SNS CHAT offre già un catalogo di strumenti di lookup (come Shopify, WooCommerce o Google Sheets) che potrebbe rendere superfluo il codice.
Controlli di sicurezza prima del lancio
Una checklist breve, da spuntare prima di andare online:
- Chiave custodita lato server. Mai nel codice del browser, in un repository pubblico o in un messaggio di chat.
- Una chiave per ambiente. Usatene una per i test e una per la produzione, così potete revocare l'una senza toccare l'altra.
- Piano di rotazione. Sapete già chi, come e quando sostituirà la chiave se dovesse trapelare? Ricordate che si può revocare in qualsiasi momento.
- Verifica della firma HMAC. Ogni webhook in arrivo va controllato con il segreto condiviso prima di essere considerato attendibile. Una richiesta senza firma valida va scartata.
- Niente segreti nei log. Registrate gli eventi, ma non le chiavi né i dati personali non necessari.
- Minimizzazione dei dati. In ottica GDPR, trasmettete e conservate solo ciò che serve allo scopo. Le pratiche di AI SNS CHAT sono progettate con riferimento a GDPR e APPI; le scelte sul vostro lato, come finalità, informative e basi giuridiche, restano vostre e vanno valutate con il vostro consulente.
- Informativa agli utenti. Chi chatta deve sapere che dall'altra parte c'è un assistente AI e come vengono trattati i suoi dati.
- Accessi al pannello protetti. Attivate l'autenticazione a due fattori per chi gestisce le chiavi e limitate i ruoli ai soli collaboratori che ne hanno bisogno.
Test e rilascio graduale
Un'integrazione ben costruita si distingue da una fragile per come viene provata.
- Cominciate dal Playground. Verificate che l'agente risponda come desiderate prima di collegarvi via codice, così separate i problemi di contenuto da quelli tecnici.
- Provate con dati di prova. Usate conversazioni fittizie, non clienti reali, finché il flusso non è stabile.
- Simulate i casi limite. Che cosa succede se il vostro server è spento quando arriva un webhook? E se la rete cade a metà di uno streaming? E se superate un limite di frequenza?
- Controllate il registro delle consegne. I webhook hanno un registro: usatelo per capire se le notifiche partono e con quale esito.
- Rilasciate a piccoli passi. Aprite l'integrazione prima a un gruppo ristretto, per esempio ai soli dipendenti, e poi ai clienti, osservando le Chat logs in Attività.
- Tenete d'occhio i crediti. Una risposta equivale a un credito: un'integrazione che genera molte chiamate consuma il piano più in fretta del previsto. Un esempio ipotetico: se un'automazione invia 300 domande al mese, sono 300 crediti, da sommare al traffico degli altri canali. Controllate la pagina Utilizzo.
Farlo in AI SNS CHAT
Ecco il percorso concreto, passo per passo.
1. Verificate il piano. Le chiavi API richiedono Hobby o superiore. I prezzi mostrati su /pricing sono letti dal sistema al momento della visita, quindi consultate sempre quella pagina per i valori aggiornati.
2. Preparate l'agente. Create e perfezionate l'agente con la procedura guidata, caricate le fonti nella sezione Fonti dati e provatelo nel Playground. Se volete confrontare modelli diversi, c'è anche il confronto A/B nel Playground. Dalle impostazioni dell'agente, in AI, scegliete il modello; i modelli avanzati e il fallback richiedono Hobby o superiore.
3. Create la chiave. Andate in Impostazioni dello spazio di lavoro → Chiavi API, generate la chiave e copiatela subito: viene mostrata una sola volta.
4. Valutate il canale "API". Nell'elenco Canali compare anche la voce API, dove trovate le indicazioni per collegare l'agente al vostro sistema. Per sapere quali altri canali sono già pronti, consultate /connections e /features.
5. Collegate i webhook. Registrate l'indirizzo del vostro server, verificate la firma HMAC a ogni richiesta e controllate il registro delle consegne mentre testate.
6. Passaggio a una persona. Se l'integrazione deve coinvolgere il vostro team, ricordate che nel Servizio assistenza (piano Standard o superiore) potete impostare i turni in Pianificazione, e gli avvisi di passaggio possono arrivare a Slack, Teams, WhatsApp, email o a un webhook.
7. Dominio personalizzato. Se il widget o il link dell'agente deve comparire sul vostro dominio, in Agente → Impostazioni → Domini personalizzati trovate la verifica tramite CNAME (Hobby o superiore).
8. Tracciate le modifiche. In Impostazioni dello spazio di lavoro → Attività, titolari e amministratori vedono chi ha creato, modificato o eliminato cosa, con data e ora: utile quando più persone toccano chiavi e integrazioni.
Per i dettagli sulle misure di protezione, come cifratura dei segreti, autenticazione a due fattori e filtri anti-abuso per agente, consultate /security. Se volete partire con un account di prova, la registrazione è su /signup.
Domande frequenti
Di quale piano ho bisogno per usare la REST API?
Le chiavi API sono disponibili dal piano Hobby in su. Il piano Free non le include. I prezzi correnti si leggono su /pricing, perché la pagina li carica dal sistema e possono essere aggiornati.
Posso trasmettere le risposte in streaming nella mia interfaccia?
Sì. Con il parametro stream=1 la risposta arriva come flusso SSE (Server-Sent Events), così potete mostrarla man mano che viene generata. Per le elaborazioni automatiche, in cui nessuno legge in diretta, è più comodo ricevere la risposta completa in JSON.
Come faccio a sapere che un webhook proviene davvero da AI SNS CHAT?
I webhook sono firmati con HMAC. Il vostro server deve controllare la firma con il segreto condiviso prima di fidarsi del contenuto e scartare le richieste che non la superano. Nel registro delle consegne potete inoltre vedere cosa è stato inviato e con quale esito.
Quali sono i limiti di frequenza?
Quelli pubblicati sono: autenticazione 20 richieste ogni 5 minuti per IP, chat pubblica 30 al minuto per IP, polling 120 al minuto. Progettate l'integrazione con pause e nuovi tentativi graduali e preferite i webhook al polling continuo.
Mi serve l'API per mettere un agente su WhatsApp o Messenger?
No. WhatsApp e Messenger sono canali già pronti nella sezione Canali: li collegate dal pannello, senza scrivere codice. L'API serve solo per esigenze particolari, come un'interfaccia di chat tutta vostra o un collegamento a sistemi interni.


