DeskcommCRM: Come Distribuire un CRM Open-Source con Agenti AI per WhatsApp sul Tuo Server

Le vendite su WhatsApp richiedono un coinvolgimento costante del responsabile oppure la connessione di servizi di terze parti come Kommo o Intercom. Man mano che il database clienti cresce, le tariffe di abbonamento e gli addebiti per postazione diventano una spesa significativa. Lo sviluppatore Rafael Melgara dal Brasile ha rilasciato DeskcommCRM su GitHub. È un sistema di gestione delle vendite self-hosted progettato per agenti AI e integrazione con messenger.

Il progetto si posiziona come un sistema di gestione delle vendite per piccole e medie imprese. Inizialmente è stato creato per un negozio online con integrazione Nuvemshop, ma successivamente l'architettura è stata rielaborata. Il risultato è una soluzione flessibile per cliniche, agenzie immobiliari, attività informative e qualsiasi servizio che riceva richieste dalle chat.

Stack Tecnologico e Architettura

Da un punto di vista architetturale, DeskcommCRM è costruito su uno stack familiare per le applicazioni web moderne:

• Frontend e backend: Next.js 16 (App Router) con React 19 e TypeScript in strict mode.
• Database e autenticazione: Supabase (PostgreSQL), che utilizza attivamente il meccanismo Row Level Security (RLS) e l'estensione pgvector per la ricerca vettoriale.
• Integrazione WhatsApp: WAHA (WhatsApp HTTP API) con il motore NOWEB, eseguito in un container Docker.
• Livello AI: Vercel AI SDK v7 con integrazione dei modelli Anthropic Claude, OpenAI e Google Gemini.

Il sistema contiene un server MCP (Model Context Protocol) integrato. Questo significa che agenti AI esterni possono connettersi al CRM tramite un protocollo comune ed eseguire operazioni con l'entonno delle vendite.

Agenti Intelligenti al Posto dei Normal Autoresponder

In DeskcommCRM, gli agenti AI funzionano in modo diverso dai tradizionali chatbot con alberi di scenario rigidi. Il bot assume il ruolo di responsabile affidabile: conduce il dialogo, qualifica i lead, li sposta attraverso le card dell'entonno e trasferisce la conversazione a un essere umano quando non riesce a rispondere autonomamente.

Per ogni cliente viene creato un knowledge base isolato. I dialoghi completati con successo vengono reimmessi nell'archiviazione vettoriale. In questo modo, l'agente accumula gradualmente contesto e diventa più preciso nel rispondere alle domande tipiche. Allo stesso tempo, il trasferimento del controllo agli esseri umani è regolato da regole per impedire al bot di inviare messaggi non necessari.

Webhook e Code di Elaborazione

Per la ricezione di richieste da landing page e moduli esterni, il sistema fornisce punti di ingresso webhook. Qualsiasi richiesta POST con parametri in formato JSON o urlencoded crea immediatamente un lead nella fase richiesta dell'entonno.

L'elaborazione interna degli eventi è configurata in modo interessante. Per evitare il sovraccarico dei trigger PostgreSQL con richieste HTTP, lo sviluppatore ha applicato un pattern di tabella eventi. Tutte le azioni (cambio di stato del lead, comparsa di tag, messaggio in entrata) vengono registrate nella tabella. Un processo in background recupera gli eventi dalla coda una volta al minuto ed esegue automazioni di tipo "quando/se/allora".

In pratica, lo schema si presenta così:

Nel cloud Vercel, questo route attiva un normale Cron Job, e quando si effettua il deployment sul proprio server, l'avvio viene rilevato dal sistema.

Sicurezza e Verifica dell'Isolamento dei Dati

Poiché il CRM supporta il multi-tenancy, è fondamentale garantire che una azienda non veda i contatti o le conversazioni di altre aziende. In DeskcommCRM, l'isolamento è basato sulle policy RLS in PostgreSQL.

Il repository ha una pipeline CI configurata che esegue 364 test invarianti su un'istanza database pulita con ogni pull. Uno dei test chiave genera due organizzazioni diverse, simula token JWT degli utenti e verifica se il database restituisce almeno una riga di un'altra azienda. Se la policy di sicurezza perde dati esterni, il build fallisce.

Avvio Rapido in Ambiente Locale

Per esplorare il codice, il progetto può essere avviato localmente in un paio di minuti. Sono necessari Node.js versione 22, pnpm e Docker in esecuzione.

Per un deployment completo su VPS, l'autore ha preparato un set di script. Lo script stesso richiede il dominio, le chiavi Supabase, le chiavi API delle reti neurali, genera i token e fa partire uno stack pronto con certificati HTTPS.

Limitazioni e Specifiche del Progetto

Quando si esplora il repository, tenere a mente diverse sfumature:

• Una parte dei commenti del codice e della documentazione è scritta in portoghese, poiché il progetto è stato inizialmente creato per il mercato brasiliano.
• Il repository è ancora relativamente giovane, con poco più di 300 stelle su GitHub.
• L'integrazione WhatsApp si basa su WAHA, quindi con un'elevata attività di messaggi è importante configurare ritardi e intervalli di invio per proteggersi dal blocco del numero.

A Chi Sarà Utile DeskcommCRM

Il progetto sarà utile per web studio e freelancer che costruiscono sistemi CRM chiavi in mano per piccole imprese e non vogliono pagare abbonamenti mensili a servizi di terze parti. Il codice sarà anche prezioso per gli sviluppatori come riferimento di qualità: potete trovare esempi di utilizzo pulito di Next.js 16, configurazione RAG con pgvector, implementazione di server MCP e test delle policy RLS in PostgreSQL.