Casi d'uso

Questi scenari illustrano come i partner collegano Userbot a CRM, portali clienti e sistemi interni nella pratica. Ogni caso descrive il problema di business, il flusso consigliato e le API coinvolte — così puoi identificare rapidamente il pattern più vicino al tuo progetto e partire da lì.

Non sono mutuamente esclusivi: molte integrazioni reali combinano più pattern (es. assistente embedded + notifiche CRM + handoff operatore).

1. Assistente embedded in portale cliente

Problema: il partner vuole offrire assistenza AI direttamente nel portale web o nell’app del cliente, con un’interfaccia chat completamente custom — senza usare il widget Userbot predefinito.

Approccio: la UI del portale invia i messaggi dell’utente al backend partner, che chiama la REST API con webhookOnly: true. Le risposte dell’agente arrivano via message.added sul webhook in dashboard e la UI si aggiorna di conseguenza.

Flusso:

Quando sceglierlo: hai già un portale o un’app con autenticazione utente e vuoi integrare la chat come componente nativo, mantenendo pieno controllo su UX e branding.

Guide: Quickstart · REST API

2. Notifiche CRM su nuova conversazione

Problema: ogni volta che un utente avvia una conversazione con l’agente, il team commerciale o l’assistenza deve sapere subito — e il CRM deve avere un record aggiornato con i dati raccolti durante la chat.

Approccio: configura un webhook in ingresso sul backend partner. Userbot invia eventi push quando accadono cose rilevanti; il tuo codice crea o aggiorna i record CRM di conseguenza.

Flusso:

1. L’utente invia il primo messaggio via API o canale Userbot (web chat, WhatsApp, ecc.)
2. Userbot emette conversation.created sul webhook del partner
3. Il backend partner crea il record CRM e salva il sessionId
4. Eventuali variabili utente (email, nome, piano) arrivano con user.variables.created / user.variables.updated

Quando sceglierlo: la conversazione AI è un touchpoint commerciale o di supporto e vuoi che CRM e team interni restino allineati senza intervento manuale.

Guide: Ricevere eventi webhook · Verifica firma HMAC

3. Handoff a operatore umano

Problema: l’AI risolve la maggior parte dei casi, ma quando serve un intervento umano la transizione deve essere fluida — senza perdere il contesto e senza che l’utente debba ripetere tutto.

Approccio: la logica partner (o l’agente stesso) rileva la necessità di escalation e chiama l’endpoint REST per cambiare stato. Da quel momento i messaggi dell’operatore arrivano via webhook e la tua UI li mostra come messaggi umani.

Flusso:

1. L’agente o la logica partner rileva la necessità di escalation
2. Il backend chiama PATCH /v1/conversations/{session_id} con state: "escalated" e operatorEmail
3. Userbot notifica conversation.state_changed con il nuovo stato
4. L’operatore risponde dalla dashboard Userbot; i messaggi arrivano via message.added

Quando sceglierlo: hai un team di operatori che gestisce casi complessi e vuoi un handoff trasparente tra AI e umano.

Guide: Concetti chiave · REST API

4. Automazione back-office con pipeline

Problema: un evento nel sistema partner — nuovo ordine, ticket IT, richiesta di preventivo — deve innescare automaticamente un flusso Userbot (notifica, aggiornamento record, workflow multi-step).

Approccio: il sistema partner chiama l’endpoint webhook trigger con i dati dell’evento. Userbot esegue la pipeline configurata in piattaforma e restituisce un jobId per tracciare l’esecuzione.

Flusso:

1. Il sistema partner (ERP, ticketing) rileva l’evento
2. Chiama POST /webhook/{webhookToken} con variables e opzionalmente file allegati
3. Userbot esegue la pipeline e restituisce jobId
4. Il risultato è visibile nella dashboard Userbot

$
curl -X POST https://api.userbot.ai/webhook/TOKEN \
>
  -F 'variables={"orderId":"ORD-2025-001"}' \
>
  -F 'files=@documento.pdf'

Quando sceglierlo: vuoi automatizzare processi che non passano necessariamente da una chat utente — ad esempio elaborare un ordine, generare un documento o inviare una sequenza di notifiche.

Guide: REST API — Flussi

5. Archivio e analytics esterni

Problema: le conversazioni concluse devono finire in un data warehouse, in un sistema di reporting o in un archivio a norma — con tutto lo storico messaggi e i metadati associati.

Approccio: usa l’evento conversation.archived come trigger per l’export, poi recupera lo storico completo via REST API con paginazione.

Flusso:

1. Alla chiusura, Userbot emette conversation.archived
2. Il partner recupera lo storico con GET /v1/conversations/{session_id}/messages (paginazione con limit / offset)
3. I dati vengono normalizzati e caricati nel sistema analytics

Quando sceglierlo: hai requisiti di compliance, audit o business intelligence che richiedono l’export sistematico delle conversazioni.

Guide: REST API · Tutorial

Scegli il punto di partenza