ChatReact
HomeDocumentazione

REST API

La REST API v1 di ChatReact le offre accesso programmatico alle operazioni supportate dalla dashboard: chatbot, knowledge base e crawling, prezzi strutturati, FAQ, revisione delle chat e Improvement Agent, lead, moduli di contatto, live chat, azienda e team, Email Assistant, analytics e notifiche. Le azioni vincolate al browser (pagamenti, autorizzazione mailbox, passkey, cancellazione account e gestione delle chiavi API) restano nella dashboard.

Preferisce parlare con un assistente AI? Le stesse funzionalità sono disponibili come strumenti MCP — veda MCP Server Integration. L'API Explorer interattiva con schemi di richiesta e risposta è disponibile su /api-reference, dove può anche scaricare la specifica OpenAPI 3.0.

Autenticazione

  1. Vai a Dashboard → Azienda → scheda API e clicchi Crea chiave API
  2. Scegli un nome e gli scope di permesso necessari per la chiave (vedere sotto)
  3. Copi la chiave — inizia con cr_ ed è mostrata una sola volta

Invii la chiave con ogni richiesta:

curl https://www.chatreact.ai/api/v1/chatbots \
  -H "Authorization: Bearer cr_your_api_key"

Un header X-API-Key: cr_your_api_key è accettato anch'esso. Le chiavi API appartengono a una singola azienda ed eseguono con i permessi del proprietario dell'azienda; i limiti del piano e i gate delle funzionalità si applicano esattamente come nella dashboard.

L'accesso API è disponibile nei piani a pagamento — veda la pagina dei Prezzi. Le chiavi possono essere revocate in qualsiasi momento dalla dashboard.

Scope

Ogni chiave porta uno o più scope. Un endpoint restituisce 403 quando la chiave non dispone dello scope richiesto.

ScopeConcessioni
chatbots:read / chatbots:writeConfigurazione chatbot: persona, lingue, widget, comportamento, restrizioni, istruzioni principali, codice embed, fase di apprendimento, template chatbot, impostazioni widget FAQ
knowledge:read / knowledge:writeKnowledge base: documenti, crawling del sito, pagine crawl-ate
faqs:read / faqs:writeFAQ, categorie FAQ, suggerimenti, traduzioni
chats:read / chats:writeCronologia chat, valutazioni chat, categorie di confidenza, live chat (le azioni dell'agente richiedono chats:write)
leads:read / leads:writeLead, categorie lead, impostazioni di acquisizione lead, export
forms:read / forms:writeModuli di contatto e invii
analytics:readStatistiche, serie di attività, funnel, stato di confidenza
company:read / company:writeProfilo e impostazioni azienda, membri del team, inviti
email:read / email:writeConnessioni Email Assistant, categorie, contatti, attività
prices:readLettura delle voci di prezzo strutturato, revisioni, idoneità e suggerimenti
prices:writeCreare e modificare bozze di prezzo, importare CSV e applicare un suggerimento come bozza; richiede il proprietario dell'azienda
prices:approveApprovare versioni esatte o archiviare voci; richiede il proprietario dell'azienda
blog:read / blog:writeContenuti del blog della piattaforma (interno a ChatReact)
any valid key/v1/me, utilizzo dell'account, le sue notifiche

Convenzioni

  • Base URL: https://www.chatreact.ai/api/v1, JSON in ingresso e in uscita (Content-Type: application/json).
  • Risposte: { "success": true, "data": … }; le liste aggiungono "pagination": { "total", "page", "pageSize", "totalPages" }. Utilizzi page e pageSize (max 100) negli endpoint che ritornano liste; alcuni endpoint offrono paginazione con cursore (cursor / nextCursor).
  • Errori: { "success": false, "error": "message", "code": "BAD_REQUEST" } con opzionale details per gli errori di validazione. Codici di stato: 400 input non valido, 401 chiave mancante o non valida, 403 scope mancante, funzione del piano non inclusa o ruolo insufficiente, 404 risorsa non trovata (anche per risorse di altre aziende), 409 conflitto, 429 limite di velocità superato.
  • Aggiornamenti parziali: gli endpoint PATCH modificano solo i campi che invia; i campi sconosciuti vengono rifiutati.
  • Rate limit: 30 richieste al minuto per indirizzo IP.
  • Operazioni di lunga durata (crawl, generazione AI, traduzioni) ritornano rapidamente con un job o un risultato che può essere interrogato; consumano i token e il budget di crawl del suo piano.

Endpoint

Prices & services

Salvataggio, modifica, importazione e applicazione di un suggerimento creano bozze senza approvazione. Le operazioni di approvazione e archiviazione revisionano versioni esatte; una versione obsoleta restituisce un conflitto. Le chiavi esistenti non acquisiscono automaticamente permessi prezzi. Solo il proprietario dell'azienda può concedere permessi di scrittura o approvazione. Per il flusso cliente, veda Prices & services.

MethodPathDescrizioneScope
GET/api/v1/chatbots/{id}/pricesElenca voci di prezzo e idoneitàprices:read
POST/api/v1/chatbots/{id}/pricesCrea una bozzaprices:write
GET/api/v1/chatbots/{id}/prices/{itemId}Legge dettagli e cronologia paginataprices:read
PATCH/api/v1/chatbots/{id}/prices/{itemId}Crea una bozza modificata da una versione attesaprices:write
GET/api/v1/chatbots/{id}/prices/{itemId}/stateLegge lo stato completo dell'elementoprices:read
POST/api/v1/chatbots/{id}/prices/{itemId}/approveApprova una versione esattaprices:approve
POST/api/v1/chatbots/{id}/prices/{itemId}/archiveArchivia una versione esattaprices:approve
POST/api/v1/chatbots/{id}/prices/approve-manyApprova in modo atomico una selezione esplicita di versioneprices:approve
POST/api/v1/chatbots/{id}/prices/importImporta bozze da CSV con un ID di importazione stabileprices:write
GET/api/v1/chatbots/{id}/prices/suggestionsElenca suggerimenti di prezzoprices:read
POST/api/v1/chatbots/{id}/prices/suggestions/{suggestionId}/applyApplica un suggerimento selezionato come bozzaprices:write

Chatbots

MethodPathDescrizioneScope
GET/api/v1/chatbotsElenca chatbotchatbots:read
POST/api/v1/chatbotsCrea chatbotchatbots:write
GET/api/v1/chatbots/{id}Ottieni chatbotchatbots:read
PATCH/api/v1/chatbots/{id}Aggiorna chatbotchatbots:write
DELETE/api/v1/chatbots/{id}Elimina chatbotchatbots:write
GET/api/v1/chatbots/{id}/personalityOttieni personalità del chatbotchatbots:read
PATCH/api/v1/chatbots/{id}/personalityAggiorna personalità del chatbotchatbots:write
GET/api/v1/chatbots/{id}/widgetOttieni impostazioni widgetchatbots:read
PATCH/api/v1/chatbots/{id}/widgetAggiorna impostazioni widgetchatbots:write
GET/api/v1/chatbots/{id}/widget/translationsOttieni traduzioni del widgetchatbots:read
PUT/api/v1/chatbots/{id}/widget/translationsSostituisci traduzioni del widgetchatbots:write
GET/api/v1/chatbots/{id}/embedOttieni codice embedchatbots:read
POST/api/v1/chatbots/{id}/embed/confirmConferma embedchatbots:write
GET/api/v1/chatbots/{id}/learning-phaseOttieni impostazioni della learning-phasechatbots:read
PATCH/api/v1/chatbots/{id}/learning-phaseAggiorna impostazioni della learning-phasechatbots:write
POST/api/v1/chatbots/{id}/learning-phase/endTermina la learning phasechatbots:write
GET/api/v1/chatbots/{id}/instructionsElenca core instructionschatbots:read
POST/api/v1/chatbots/{id}/instructionsAggiungi core instructionchatbots:write
PUT/api/v1/chatbots/{id}/instructions/reorderRiorganizza core instructionschatbots:write
POST/api/v1/chatbots/{id}/instructions/improveMigliora istruzioni con AIchatbots:write
GET/api/v1/instructions/{id}Ottieni core instructionchatbots:read
PATCH/api/v1/instructions/{id}Aggiorna core instructionchatbots:write
DELETE/api/v1/instructions/{id}Elimina core instructionchatbots:write
GET/api/v1/chatbot-templatesElenca template chatbotchatbots:read

Knowledge base

MethodPathDescrizioneScope
GET/api/v1/chatbots/{id}/knowledgePanoramica knowledge baseknowledge:read
GET/api/v1/chatbots/{id}/documentsElenca documenti per chatbotknowledge:read
POST/api/v1/chatbots/{id}/documentsCarica documentoknowledge:write
POST/api/v1/chatbots/{id}/documents/presignPresign per upload documentoknowledge:write
GET/api/v1/documents/{id}Ottieni documentoknowledge:read
DELETE/api/v1/documents/{id}Elimina documentoknowledge:write
POST/api/v1/documents/{id}/confirmConferma upload presignedknowledge:write
GET/api/v1/chatbots/{id}/crawl/limitsLimiti di crawlknowledge:read
POST/api/v1/chatbots/{id}/crawl/previewAnteprima scan del sito webknowledge:write
GET/api/v1/chatbots/{id}/crawlElenca job di crawlknowledge:read
POST/api/v1/chatbots/{id}/crawlAvvia crawlknowledge:write
GET/api/v1/crawl-jobs/{jobId}Ottieni job di crawlknowledge:read
POST/api/v1/crawl-jobs/{jobId}/cancelAnnulla job di crawlknowledge:write
GET/api/v1/chatbots/{id}/pagesElenca pagine crawl-ateknowledge:read
POST/api/v1/chatbots/{id}/pagesAggiungi singolo URLknowledge:write
POST/api/v1/chatbots/{id}/pages/bulk-deleteEliminazione in blocco di pagine crawl-ateknowledge:write
GET/api/v1/pages/{id}Ottieni pagina crawl-ataknowledge:read
DELETE/api/v1/pages/{id}Elimina pagina crawl-ataknowledge:write
POST/api/v1/pages/{id}/recrawlRiscansiona paginaknowledge:write
GET/api/v1/chatbots/{id}/websitesElenca siti crawl-atiknowledge:read
DELETE/api/v1/chatbots/{id}/websites/{domain}Elimina sitoknowledge:write
POST/api/v1/chatbots/{id}/websites/{domain}/recrawlRiscansiona sitoknowledge:write
POST/api/v1/chatbots/{id}/websites/{domain}/recrawl/cancelAnnulla re-crawl del sitoknowledge:write

FAQs

MethodPathDescrizioneScope
GET/api/v1/chatbots/{id}/faqsElenca FAQ per chatbotfaqs:read
POST/api/v1/chatbots/{id}/faqsCrea FAQfaqs:write
POST/api/v1/chatbots/{id}/faqs/bulkImport bulk FAQfaqs:write
POST/api/v1/chatbots/{id}/faqs/reorderRiorganizza FAQfaqs:write
GET/api/v1/chatbots/{id}/faqs/embedOttieni codice embed del widget FAQchatbots:read
POST/api/v1/chatbots/{id}/faqs/purge-cacheSvuota le cache remote delle FAQfaqs:write
GET/api/v1/faqs/{id}Ottieni FAQfaqs:read
PATCH/api/v1/faqs/{id}Aggiorna FAQfaqs:write
DELETE/api/v1/faqs/{id}Elimina FAQfaqs:write
PUT/api/v1/faqs/{id}/translationsAggiorna traduzioni FAQfaqs:write
POST/api/v1/faqs/{id}/translateTraduci FAQ con AIfaqs:write
GET/api/v1/chatbots/{id}/faq-suggestionsElenca suggerimenti FAQfaqs:read
POST/api/v1/chatbots/{id}/faq-suggestions/generateGenera suggerimenti FAQ dalla knowledge basefaqs:write
GET/api/v1/faq-suggestions/{id}Ottieni suggerimento FAQfaqs:read
POST/api/v1/faq-suggestions/{id}/approveApprova suggerimento FAQfaqs:write
POST/api/v1/faq-suggestions/{id}/rejectRespinge suggerimento FAQfaqs:write
GET/api/v1/chatbots/{id}/faq-categoriesElenca categorie FAQfaqs:read
POST/api/v1/chatbots/{id}/faq-categoriesCrea categoria FAQfaqs:write
POST/api/v1/chatbots/{id}/faq-categories/reorderRiorganizza categorie FAQfaqs:write
GET/api/v1/faq-categories/{id}Ottieni categoria FAQfaqs:read
PATCH/api/v1/faq-categories/{id}Aggiorna categoria FAQfaqs:write
DELETE/api/v1/faq-categories/{id}Elimina categoria FAQfaqs:write
PUT/api/v1/faq-categories/{id}/translationsAggiorna traduzioni della categoria FAQfaqs:write
GET/api/v1/chatbots/{id}/faq-widget-settingsOttieni impostazioni widget FAQchatbots:read
PATCH/api/v1/chatbots/{id}/faq-widget-settingsAggiorna impostazioni widget FAQchatbots:write

Chats, feedback & Improvement Agent

MethodPathDescrizioneScope
GET/api/v1/chatsElenca sessioni di chatchats:read
GET/api/v1/chats/{sessionId}Ottieni sessione di chatchats:read
PATCH/api/v1/chats/{sessionId}Imposta categoria di confidenza della chatchats:write
POST/api/v1/chats/{sessionId}/feedbackValuta la chat (Good / Needs Work)chats:write
POST/api/v1/chats/{sessionId}/feedback/dismissScarta la revisione della chatchats:write
POST/api/v1/chats/{sessionId}/improveAvvia Improvement Agent per la chatchatbots:write
GET/api/v1/chatbots/{id}/feedbackElenca revisioni chat di un chatbotchats:read
GET/api/v1/chatbots/{id}/feedback/statsSchede statistiche di revisione chatchats:read
GET/api/v1/feedback/{id}Ottieni revisione chatchats:read
PATCH/api/v1/feedback/{id}Sovrascrivi gravità della revisionechats:write
POST/api/v1/feedback/{id}/improvement-sessionAvvia Improvement Agent per la revisionechatbots:write
GET/api/v1/chatbots/{id}/confidenceOttieni stato di confidenzaanalytics:read
GET/api/v1/chatbots/{id}/confidence-categoriesElenca categorie di confidenzachats:read
POST/api/v1/chatbots/{id}/confidence-categoriesCrea categoria di confidenzachatbots:write
PATCH/api/v1/confidence-categories/{id}Aggiorna categoria di confidenzachatbots:write
DELETE/api/v1/confidence-categories/{id}Elimina categoria di confidenzachatbots:write
POST/api/v1/confidence-categories/{id}/mergeUnisci categorie di confidenzachatbots:write
GET/api/v1/chatbots/{id}/improvement-sessionsElenca sessioni di miglioramentochatbots:read
GET/api/v1/improvement-sessions/{id}Ottieni sessione di miglioramentochatbots:read
POST/api/v1/improvement-sessions/{id}/messagesInvia messaggio all'Improvement Agentchatbots:write
POST/api/v1/improvement-sessions/{id}/completeCompleta sessione di miglioramentochatbots:write
POST/api/v1/improvement-sessions/{id}/resetReimposta sessione di miglioramentochatbots:write
POST/api/v1/improvement-proposals/{id}/applyApplica proposta di miglioramentochatbots:write
POST/api/v1/improvement-proposals/{id}/rejectRespinge proposta di miglioramentochatbots:write
POST/api/v1/improvement-proposals/{id}/simulationsSimula proposta di miglioramentochatbots:write
POST/api/v1/improvement-simulations/{id}/assessmentValuta risultato della simulazionechatbots:write

Leads

MethodPathDescrizioneScope
GET/api/v1/leadsElenca leadleads:read
POST/api/v1/leadsCrea leadleads:write
GET/api/v1/leads/{id}Ottieni leadleads:read
PATCH/api/v1/leads/{id}Aggiorna leadleads:write
DELETE/api/v1/leads/{id}Elimina leadleads:write
POST/api/v1/leads/{id}/assignAssegna leadleads:write
POST/api/v1/leads/bulk-statusAggiornamento in blocco dello stato dei leadleads:write
GET/api/v1/leads/statsStatistiche leadleads:read
GET/api/v1/leads/exportEsporta leadleads:read
GET/api/v1/chatbots/{id}/lead-configOttieni configurazione di acquisizione leadleads:read
PUT/api/v1/chatbots/{id}/lead-configAggiorna configurazione di acquisizione leadleads:write
GET/api/v1/chatbots/{id}/lead-categoriesElenca categorie leadleads:read
POST/api/v1/chatbots/{id}/lead-categoriesCrea categoria leadleads:write
GET/api/v1/lead-categories/{id}Ottieni categoria leadleads:read
PATCH/api/v1/lead-categories/{id}Aggiorna categoria leadleads:write
DELETE/api/v1/lead-categories/{id}Elimina categoria leadleads:write
PUT/api/v1/lead-categories/{id}/users/{userId}Assegna membro a categoria leadleads:write
DELETE/api/v1/lead-categories/{id}/users/{userId}Rimuovi membro da categoria leadleads:write

Contact forms

MethodPathDescrizioneScope
GET/api/v1/chatbots/{id}/formsElenca moduli di contattoforms:read
POST/api/v1/chatbots/{id}/formsCrea modulo di contattoforms:write
GET/api/v1/forms/{id}Ottieni modulo di contattoforms:read
PATCH/api/v1/forms/{id}Aggiorna modulo di contattoforms:write
DELETE/api/v1/forms/{id}Elimina modulo di contattoforms:write
GET/api/v1/forms/{id}/submissionsElenca invii del moduloforms:read
GET/api/v1/forms/{id}/statsStatistiche invii moduloforms:read
GET/api/v1/submissions/{id}Ottieni invio del moduloforms:read
PATCH/api/v1/submissions/{id}Revisiona invio del moduloforms:write
DELETE/api/v1/submissions/{id}Elimina invio del moduloforms:write

Live chat

MethodPathDescrizioneScope
GET/api/v1/live-chat/availabilityOttieni la propria disponibilità per la live chatchats:read
PUT/api/v1/live-chat/availabilityImposta la propria disponibilità per la live chatchats:write
POST/api/v1/live-chat/heartbeatInvia heartbeat di presenzachats:write
GET/api/v1/live-chat/agentsElenca agenti disponibili per la live chatchats:read
GET/api/v1/live-chat/sessionsElenca sessioni di live chatchats:read
GET/api/v1/live-chat/sessions/{sessionId}Ottieni sessione di live chatchats:read
POST/api/v1/live-chat/sessions/{sessionId}/assignPrendere in carico la live chat (assegna al proprietario della chiave)chats:write
POST/api/v1/live-chat/sessions/{sessionId}/messagesInvia messaggio come agentechats:write
POST/api/v1/live-chat/sessions/{sessionId}/closeTermina live chatchats:write

Analytics

MethodPathDescrizioneScope
GET/api/v1/analyticsOttieni panoramica analyticsanalytics:read
GET/api/v1/analytics/activityOttieni serie di attività chatanalytics:read
GET/api/v1/analytics/chatbotsElenca statistiche di performance per chatbotanalytics:read
GET/api/v1/analytics/chatbots/{id}Ottieni analytics del chatbotanalytics:read
GET/api/v1/analytics/leadsOttieni funnel leadanalytics:read
GET/api/v1/analytics/formsOttieni statistiche invii moduloanalytics:read
GET/api/v1/activityOttieni riepilogo attentionanalytics:read

Company & team

MethodPathDescrizioneScope
GET/api/v1/companyOttieni aziendaany key
PATCH/api/v1/companyAggiorna aziendacompany:write
GET/api/v1/company/settingsOttieni impostazioni aziendacompany:read
PATCH/api/v1/company/settingsAggiorna impostazioni aziendacompany:write
DELETE/api/v1/company/logoRimuovi logo aziendalecompany:write
GET/api/v1/company/membersElenca membri del teamcompany:read
PATCH/api/v1/company/members/{userId}Cambia ruolo del membrocompany:write
DELETE/api/v1/company/members/{userId}Rimuovi membro del teamcompany:write
GET/api/v1/company/invitesElenca inviticompany:read
POST/api/v1/company/invitesInvita membro del teamcompany:write
DELETE/api/v1/company/invites/{id}Annulla invitocompany:write
POST/api/v1/company/invites/{id}/resendReinvia invitocompany:write

Email Assistant

MethodPathDescrizioneScope
GET/api/v1/email/connectionsElenca connessioni mailboxemail:read
GET/api/v1/email/connections/{id}Ottieni connessione mailboxemail:read
PATCH/api/v1/email/connections/{id}Aggiorna connessione mailboxemail:write
DELETE/api/v1/email/connections/{id}Disconnetti mailboxemail:write
GET/api/v1/email/connections/{id}/categoriesElenca categorie emailemail:read
POST/api/v1/email/connections/{id}/categoriesCrea categoria emailemail:write
GET/api/v1/email/connections/{id}/foldersElenca cartelle mailemail:read
POST/api/v1/email/connections/{id}/foldersCrea cartella mailemail:write
GET/api/v1/email/connections/{id}/activityElenca log di attività emailemail:read
GET/api/v1/email/categories/{id}Ottieni categoria emailemail:read
PATCH/api/v1/email/categories/{id}Aggiorna categoria emailemail:write
DELETE/api/v1/email/categories/{id}Elimina categoria emailemail:write
GET/api/v1/email/contactsElenca contatti emailemail:read
GET/api/v1/email/contacts/{id}Ottieni contatto emailemail:read
PATCH/api/v1/email/contacts/{id}Aggiorna contatto emailemail:write
DELETE/api/v1/email/contacts/{id}Elimina contatto emailemail:write

Account & notifications

MethodPathDescrizioneScope
GET/api/v1/meOttieni contesto della chiave (whoami)any key
GET/api/v1/account/usageOttieni piano e utilizzoany key
GET/api/v1/notificationsElenca notificheany key
DELETE/api/v1/notificationsElimina notifiche lette vecchieany key
GET/api/v1/notifications/unread-countOttieni conteggio notifiche non letteany key
POST/api/v1/notifications/mark-all-readSegna tutte le notifiche come letteany key
GET/api/v1/notifications/{id}Ottieni notificaany key
PATCH/api/v1/notifications/{id}Segna notifica come lettaany key

Blog (platform)

MethodPathDescrizioneScope
GET/api/v1/blogElenca post del blogany key
POST/api/v1/blogCrea post del blogany key
POST/api/v1/blog/assetsCarica asset del blogany key
GET/api/v1/blog/{id}Ottieni post del blogany key
PATCH/api/v1/blog/{id}Aggiorna post del blogany key
DELETE/api/v1/blog/{id}Elimina post del blogany key
POST/api/v1/blog/{id}/translationsMetti in coda traduzioni del blogany key

Serve aiuto? Contatti il nostro team di supporto →

Precedente
Integrazione Shopify
Successivo
Integrazione Server MCP