Documentazione Tecnica

SideMindBot v1.8.0

Reference tecnico completo per sviluppatori e system integrator. API, webhook, architettura e best practice.

Architettura Multi-Agent

SideMindBot utilizza un'architettura multi-agent con orchestratore centrale. Ogni messaggio viene analizzato e instradato all'agente specializzato più appropriato.

Messaggio

WhatsApp/Email/Social

→
Orchestratore

Intent detection

→
Agente Specializzato

Sales/Support/Booking

→
Risposta

+ Context memory

Componenti Principali

Componente Funzione Tecnologia
Orchestrator Analizza intent, routing agli agenti, gestione fallback Claude/GPT-4 con function calling
Agent Pool Agenti specializzati per dominio (sales, support, booking) LLM + Knowledge Base specifica
Memory Manager Gestione contesto conversazione, TTL 24h, max 30 msg Redis + PostgreSQL
GDPR Filter Pseudonimizzazione pre-AI, de-anonimizzazione post-AI Regex + tokenizer custom
Channel Adapter Normalizzazione input/output per ogni canale WhatsApp Web.js, IMAP, Graph API

Fallback Strategy

Il sistema implementa fallback automatico su provider AI alternativi per garantire continuità di servizio:

// Configurazione fallback (ordine di priorità)
{
  "primary": "claude-3-opus",
  "fallback": [
    "claude-3-sonnet",
    "gpt-4-turbo",
    "gpt-3.5-turbo"
  ],
  "timeout_ms": 5000,
  "retry_count": 2
}

Webhook API

SideMindBot può inviare notifiche webhook per eventi specifici e ricevere comandi esterni.

Outbound Webhook (SideMindBot → Your Server)

POST https://your-server.com/webhook/sidemind
Content-Type: application/json
X-SideMind-Signature: sha256=...

{
  "event": "message.received",
  "timestamp": "2026-01-25T10:30:00Z",
  "data": {
    "conversation_id": "conv_abc123",
    "channel": "whatsapp",
    "sender": {
      "id": "393331234567",
      "name": "Mario Rossi"
    },
    "message": {
      "type": "text",
      "content": "Vorrei prenotare un appuntamento"
    },
    "context": {
      "referral_type": "ADS",
      "campaign_id": "fb_camp_123"
    }
  }
}

Eventi Disponibili

Evento Descrizione Trigger
message.received Nuovo messaggio in arrivo Ogni messaggio utente
message.sent Risposta inviata (bot o operatore) Ogni risposta
conversation.escalated Conversazione passata a operatore Human takeover
conversation.closed Conversazione conclusa Timeout o chiusura manuale
lead.captured Nuovo lead identificato Estrazione dati contatto
spam.detected Messaggio spam bloccato Anti-spam trigger

Inbound Webhook (Your Server → SideMindBot)

POST https://api.sidemindbot.com/v1/messages/send
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "channel": "whatsapp",
  "recipient": "393331234567",
  "message": {
    "type": "text",
    "content": "Il tuo appuntamento è confermato per domani alle 15:00"
  },
  "bypass_ai": true
}

Autenticazione Webhook

Tutti i webhook in uscita includono header X-SideMind-Signature con HMAC-SHA256 del payload. Verifica sempre la signature prima di processare.

Configurazione Canali

WhatsApp

SideMindBot si connette al tuo numero WhatsApp personale/business tramite WhatsApp Web (QR code). Non richiede WhatsApp Business API.

// Configurazione WhatsApp
{
  "channel": "whatsapp",
  "config": {
    "session_name": "main_business",
    "qr_timeout_ms": 60000,
    "auto_reconnect": true,
    "voice_transcription": true,
    "media_download": true
  }
}

Email (Gmail + IMAP)

// Configurazione Email multi-account
{
  "channel": "email",
  "accounts": [
    {
      "type": "gmail",
      "email": "support@tuaazienda.it",
      "oauth2": {
        "client_id": "...",
        "refresh_token": "..."
      }
    },
    {
      "type": "imap",
      "email": "info@tuaazienda.it",
      "imap_host": "imap.tuodominio.it",
      "smtp_host": "smtp.tuodominio.it"
    }
  ]
}

Social Media (Facebook, LinkedIn, TikTok)

// Configurazione Facebook con context tracking
{
  "channel": "facebook",
  "page_id": "123456789",
  "features": {
    "messenger_dm": true,
    "post_comments": true,
    "ad_comments": true,
    "story_replies": true
  },
  "context_tracking": {
    "referral_types": ["ADS", "ORGANIC", "DIRECT", "STORY"],
    "include_post_content": true,
    "include_ad_content": true
  }
}

GDPR Pseudonimizzazione

SideMindBot implementa pseudonimizzazione reversibile come requisito architetturale. I dati personali vengono tokenizzati prima dell'invio all'AI e de-anonimizzati nella risposta.

Tipi PII Supportati (12)

Tipo PII Pattern Token
Email mario.rossi@email.com [EMAIL_1]
Telefono +39 333 1234567 [PHONE_1]
Codice Fiscale RSSMRA80A01H501Z [CF_1]
IBAN IT60X0542811101000000123456 [IBAN_1]
Nome Completo Mario Rossi [NAME_1]
Indirizzo IP 192.168.1.100 [IP_1]
Data di Nascita 01/01/1980 [DOB_1]
Carta di Credito 4111 1111 1111 1111 [CC_1]
CAP 20100 [ZIP_1]
Indirizzo Via Roma 1, Milano [ADDRESS_1]
Partita IVA IT12345678901 [VAT_1]
Dati Sanitari allergia a penicillina [HEALTH_1]

Flusso Pseudonimizzazione

// Input utente
"Ciao, sono Mario Rossi, email mario.rossi@email.com, vorrei prenotare"

// Dopo pseudonimizzazione (inviato all'AI)
"Ciao, sono [NAME_1], email [EMAIL_1], vorrei prenotare"

// Risposta AI
"Ciao [NAME_1], ho inviato la conferma a [EMAIL_1]"

// Dopo de-anonimizzazione (inviato all'utente)
"Ciao Mario Rossi, ho inviato la conferma a mario.rossi@email.com"

Importante

I mapping PII→Token sono memorizzati localmente su server EU e mai inviati a provider AI esterni. Il TTL di default è 24 ore, configurabile per compliance specifica.

Human-in-the-Loop

Il sistema Human-in-the-Loop garantisce che l'operatore umano abbia sempre priorità sulla risposta AI.

Flusso di Funzionamento

// Configurazione HITL
{
  "hitl": {
    "enabled": true,
    "timeout_seconds": 300, // 5 minuti default
    "operator_priority": true,
    "context_preservation": true
  }
}

// Stati conversazione
enum ConversationState {
  QUEUED,      // In attesa, timer attivo
  OPERATOR,    // Operatore ha risposto
  BOT,         // Bot ha risposto (timeout scaduto)
  MIXED        // Interventi misti operatore+bot
}

Logica Decisionale

Scenario Azione Risultato
Messaggio arriva, operatore disponibile Entra in coda con timer Attende risposta operatore
Operatore risponde entro timeout Bot NON interviene Risposta operatore inviata
Timeout scade senza risposta Bot genera risposta Risposta AI inviata
Bot ha risposto, operatore interviene dopo Operatore prende controllo Conversazione passa a MIXED

Operator Context

Quando il bot risponde dopo un intervento operatore, ha piena consapevolezza del contesto:

// Cronologia conversazione inviata all'AI
[
  { "role": "user", "content": "Quanto costa il servizio?" },
  { "role": "operator", "content": "Dipende dal piano, quale ti interessa?" },
  { "role": "user", "content": "Quello base" },
  // Bot risponde con contesto completo
]

Eventi e Analytics

Metriche Tracciate

Metrica Descrizione Aggregazione
messages_received Messaggi in arrivo per canale Count / ora, giorno
messages_sent Risposte inviate (bot vs operatore) Count / ora, giorno
response_time_avg Tempo medio risposta Media mobile 7 giorni
bot_deflection_rate % conversazioni gestite solo da bot Percentuale giornaliera
escalation_rate % conversazioni passate a operatore Percentuale giornaliera
referral_breakdown Distribuzione ADS/ORGANIC/DIRECT Percentuali per canale

Export Dati

GET /api/v1/analytics/export
Authorization: Bearer YOUR_API_KEY

// Query params
?start_date=2026-01-01
&end_date=2026-01-31
&format=csv
&metrics=messages_received,response_time_avg

Supporto Tecnico

Per assistenza tecnica su integrazione e configurazione:

  • Email: tech@synaptica-solution.com
  • Documentazione: Questa pagina viene aggiornata regolarmente
  • Richieste feature: Contatta il tuo account manager
Torna a SideMindBot Contatta Supporto
Parliamone
Scrivici su WhatsApp