Integrazioni e canali (riferimento tecnico)

I canali portano i messaggi di altri servizi nello stesso pannello operatori della chat del sito web; le integrazioni inviano eventi ad altri servizi o ne consultano le conoscenze. Questa pagina descrive la tecnologia. La gestione nell’account è descritta nel Manuale.

Stato: i canali e la maggior parte delle integrazioni sono stati testati con risposte simulate dei provider, ma non ancora con tutti gli account reali. Il webhook firmato è completo (con la limitazione indicata nella relativa pagina); per tutti gli altri provider, controlli il registro dell’integrazione dopo l’attivazione. Li consideri in beta.

Regole comuni

• Indirizzi di callback nel formato https://reactive.chat/kanal/<kanal>/<SITE_KEY>. La chiave del sito si trova nell’account in Progetto → Installazione.
• Ogni percorso in ingresso verifica la firma del provider. Senza il segreto del provider non viene accettato nulla.
• Le credenziali vengono memorizzate in forma cifrata e separatamente dal resto della configurazione.
• Le risposte del Suo team arrivano al provider tramite una coda in uscita; una piattaforma bloccata non rallenta alcuna chat.
• Lunghezza dei messaggi: i messaggi in ingresso che superano il limite del piano vengono accorciati e contrassegnati con [...] (Limiti).
• Gli allegati dei canali (e-mail, foto Telegram) passano gli stessi controlli del widget (tipo, dimensione, quota). I file rifiutati appaiono nel testo come «[Allegato non accettato: …]», nella lingua predefinita del progetto (de, en, pl, altrimenti inglese).

WhatsApp, Messenger, Instagram

Si configurano nell’account in Integrazioni. Serve una Sua app nella Meta Developer Dashboard; i Suoi messaggi non passano attraverso un nostro account.

• Callback URL: https://reactive.chat/kanal/whatsapp/SITE_KEY, …/kanal/messenger/SITE_KEY o …/kanal/instagram/SITE_KEY
• Verify Token: una lunga stringa casuale da inserire identica presso Meta e presso di noi (confronto a tempo costante).
• App Secret: lo usiamo per verificare la firma di ogni callback. Senza App Secret il percorso in ingresso non accetta nulla.
• Access Token: lo usiamo per inviare a Suo nome.

Regole delle piattaforme che possono far fallire le consegne senza avviso:

• WhatsApp: per 24 ore dopo l’ultimo messaggio del cliente può rispondere liberamente; in seguito solo con un modello approvato (tipo UTILITY, esattamente un segnaposto {{1}}). Ne inserisca il nome nella configurazione; fuori da questa finestra non inviamo liberamente.
• Instagram: il cliente deve scrivere per primo.
• Messenger: tra le etichette dei messaggi rimane solo HUMAN_AGENT; rifiutiamo le altre.

Meta si aspetta la risposta a un callback entro cinque secondi; il nostro percorso in ingresso si limita ad accettarlo e metterlo in coda.

Telegram, SMS, e-mail

Questi canali appartengono al progetto e si configurano in Progetto → Canali.

• Telegram: un Suo bot. Quando salva il token del bot, registriamo noi l’indirizzo di callback https://reactive.chat/kanal/telegram/SITE_KEY tramite setWebhook, con un secret_token casuale che ogni callback deve contenere. Per impostazione predefinita risponde anche l’assistente.
• SMS: tramite il Suo account Twilio (integrazione Twilio). Per il numero, inserisca https://reactive.chat/kanal/sms/SITE_KEY in «A message comes in»; viene verificato X-Twilio-Signature. Per impostazione predefinita risponde anche l’assistente.
• E-mail: la Sua casella di posta viene consultata tramite IMAP ogni minuto; le risposte passano dal Suo SMTP (altrimenti dal nostro servizio di invio con Reply-To). All’attivazione non vengono recuperate vecchie e-mail. L’assegnazione alla conversazione avviene tramite In-Reply-To/References, altrimenti tramite mittente e oggetto degli ultimi 30 giorni. Non vengono importati: risposte di assenza, notifiche di consegna, mailing list, e-mail contrassegnate come spam, oltre 20 e-mail per mittente e ora (300 per progetto). Per impostazione predefinita l’assistente non risponde alle e-mail; se attivato, le sue risposte contengono Auto-Submitted: auto-replied.

Lacuna nota: se una consegna al provider fallisce definitivamente (numero bloccato, finestra chiusa), il motivo compare nel registro dell’integrazione, ma non ancora nella conversazione.

Integrazioni

Attivi le integrazioni nell’account in Integrazioni. Ciascuna ha credenziali proprie (chiave, token, indirizzo o accesso presso il provider). Gli eventi (conversation.created, message.created, handoff.requested, csat.submitted, fehlerfall.erstellt) passano da una coda con nuovi tentativi:

• fino a cinque nuovi tentativi con intervalli crescenti (da 1 s a poco più di 10 minuti),
• un interruttore di protezione per provider e spazio di lavoro: dopo 5 errori in 60 secondi, una pausa di 30 secondi,
• gli eventi più vecchi di un’ora non vengono più consegnati,
• una chat non attende mai un’integrazione.

Provider presenti nel codice:

• Eventi verso i Suoi sistemi: webhook (firmati, veda Webhook), Zapier, Make, n8n (tramite hook REST)
• Chat del team: Slack, Microsoft Teams, Discord
• Ticket e CRM: Zendesk, Freshdesk, HubSpot, Pipedrive, Jira, Linear, GitHub
• Negozi: Shopify, WooCommerce, Shopware, Stripe
• Conoscenze: crawler del sito web, WordPress, Notion, Confluence, Google Drive
• Analisi ed errori: Google Analytics 4, Matomo, Plausible, Sentry
• Appuntamenti: Cal.com
• Canali: WhatsApp, Messenger, Instagram, Telegram, Twilio, e-mail

Non può registrare provider propri. Per i Suoi collegamenti usi i webhook, l’API server o MCP.

Le funzioni del negozio nella chat (ad esempio «Aggiungi al carrello» per WooCommerce, Shopify e Shopware) vengono abilitate da reactive.chat per ciascun progetto; funzionano solo sull’host del negozio registrato e non dispongono di un’API JavaScript propria.

App mobili

Per le app non esiste un SDK nativo, ma una pagina di incorporamento per WebView: App mobili.

Prosegua: App mobili