Il modulo del tuo sito: i contatti dal sito nel kanban

Anche chi ti scrive dal sito può finire nel kanban, con il messaggio già nelle note. Il modulo del sito c'è nei piani Pro e Agency e lo crea un admin del team.

1. Apri Connettori → Il modulo del tuo sito e scegli da dove arrivano i lead: Sul tuo sito se vuoi un modulo pronto da incollare, Con il tuo assistente AI se il sito ha già un modulo e un assistente che ci lavora, Zapier se i contatti passano da uno Zap, Da un programma se i dati li manda Make o un sito fatto su misura.
2. Dagli un nome per riconoscerlo (per esempio "Sito web") e premi Crea il modulo o Crea la chiave.
3. Premi Scarica le istruzioni per chi fa il sito: è un file con dentro tutto (codice, chiave, esempi). Giralo a chi ti gestisce il sito. Fallo subito: per sicurezza la chiave non la mostriamo più.
4. Compila il modulo dal sito per provarlo: il lead compare nella prima colonna.

Il modulo pronto chiede nome e cognome, email, telefono e messaggio, e ha una protezione invisibile contro i bot. I lead arrivano con fonte "Sito web".

Il modulo l'hai già fatto con Elementor su WordPress? Non rifarlo: segui la guida per Elementor. Usi Zapier? C'è la guida passo passo per Zapier.

La chiave si vede nel codice: è un problema?

No, per il modulo Sul tuo sito è normale: tutto quello che sta in una pagina web lo può leggere chiunque, e succede con ogni servizio di moduli. Quella chiave però può solo aggiungere lead: non legge niente e non cambia niente. Contro chi la usa per mandare spam ci sono la trappola per i bot e dei limiti di invio.

Per Zapier, Make o un server usa invece Da un programma: la chiave è segreta e Skeo la accetta solo se arriva da un server, nel posto giusto. Se qualcuno la mette in una pagina web o nell'indirizzo, viene rifiutata.

Hai perso il codice, o arriva spam?

Premi Revoca sul modulo vecchio e creane uno nuovo, poi sostituisci il codice nel sito. Il modulo revocato smette subito di funzionare.

Con il tuo assistente AI (Claude Code, Cursor, Lovable…)

Il sito ha già il suo modulo e lo segui con un assistente AI che lavora sul codice? Non serve rifare niente: in Skeo scegli Con il tuo assistente AI, salvi la chiave tra i segreti del tuo hosting con il nome SKEO_API_KEY e dai all'assistente il prompt qui sotto. La chiave nel prompt non c'è, apposta: in una chat resterebbe per sempre.

Collega il modulo di contatto di questo sito a Skeo, il CRM dove finiscono i nostri
lead: ogni volta che qualcuno invia il modulo, manda i suoi dati anche a Skeo.

DOVE
- La chiamata parte solo dal server: una API route, una funzione serverless, l'azione del
  modulo. Mai dal browser: la chiave è segreta e Skeo rifiuta le richieste fatte da una
  pagina web.
- Se il sito non ha nessuna parte server (solo pagine statiche), fermati e dimmelo: in
  Skeo uso l'opzione «Sul tuo sito», che è fatta per quello.

LA CHIAMATA
POST https://skeo.it/api/public/leads/inbound
Authorization: Bearer <valore della variabile d'ambiente SKEO_API_KEY>
Content-Type: application/json
Corpo: un oggetto JSON con i campi del lead (va bene anche application/x-www-form-urlencoded).
Costruisci una richiesta nuova: non inoltrare le intestazioni del browser (in particolare
Origin), altrimenti Skeo la scambia per una pagina web e risponde 401.

LA CHIAVE
- Leggila dalla variabile d'ambiente SKEO_API_KEY, che ho salvato tra i segreti
  dell'hosting. Se non la trovi, dimmelo e la aggiungo io: non chiedermela e non farmi
  mai incollare la chiave nella chat. Per provare in locale usa un file .env escluso dal
  repository, che compilo io, o prova sul sito pubblicato.
- Non scrivere mai la chiave nel codice, nel repository, nel JavaScript della pagina o
  nei log, e mai nell'indirizzo (?key=): Skeo la rifiuta.

CAMPI ACCETTATI
- Nome e cognome: nome_e_cognome, oppure nome + cognome (anche name, first_name, last_name)
- Email: email
- Telefono: telefono (anche phone, cellulare)
- Azienda: azienda (anche company)
- Messaggio: messaggio (anche message), finisce nelle note del lead
- Campagna: campagna, utm_source, utm_medium, utm_campaign, utm_term, utm_content
Serve almeno un nome, un'email o un telefono.
Ogni altro campo (es. settore_attivita, budget) arriva nella scheda del lead come campo
personalizzato, con il suo nome. I campi che iniziano con _ restano fuori. Massimo 20.
Manda anche utm_source, utm_medium, utm_campaign, utm_term e utm_content se la pagina li ha
(dall'indirizzo o da un cookie), e l'indirizzo della pagina del modulo in un campo così:
pagina: <indirizzo della pagina>

COME DEVE COMPORTARSI
- Lascia tutto quello che il modulo fa già (email, altri strumenti, pagina di
  ringraziamento) e aggiungi Skeo accanto.
- Aspetta la risposta di Skeo prima di rispondere al browser, con un limite di qualche
  secondo: su un hosting serverless una richiesta non attesa viene interrotta e il lead si
  perde. Se il framework lo prevede, va bene anche waitUntil o after().
- Un errore di Skeo non deve mai bloccare l'invio di chi compila il modulo: intercettalo e
  la persona vede la conferma come prima.
- Su 5xx o errore di rete riprova una volta dopo un paio di secondi. Su 429 non ritentare
  subito: scrivilo nei log.
- Nei log scrivi solo il codice di risposta: mai la chiave e mai i dati della persona.

RISPOSTE
- 200 {"ok":true}: lead arrivato nel kanban, nella prima colonna.
- 400: mancano nome, email e telefono, o il formato non è JSON né un modulo.
- 401: chiave sbagliata, revocata o mandata nel modo sbagliato (vedi sopra).
- 429: troppi invii in poco tempo. Riprova dopo un minuto.
- 500: problema nostro. Riprova tra poco.

PROVA E RESOCONTO
1. Invia una prova con nome «Prova Skeo» (dal modulo o con una richiesta di test dal
   server) e controlla che la risposta sia 200 {"ok":true}: il lead compare in Skeo, nella
   prima colonna. Ricordami di cancellarlo: conta come un lead vero.
2. Poi dimmi: quale modulo hai collegato, come hai abbinato i campi, dove leggi la chiave
   e com'è andata la prova.

Il prompt chiede all'assistente di aggiungere l'invio a Skeo dal server, lasciare com'è tutto il resto e mandare un lead di prova, da cancellare dopo. Se il sito è fatto solo di pagine statiche, deve fermarsi: lì serve il modulo pronto di Sul tuo sito. Funziona con Claude Code, Cursor, Codex, Lovable, Copilot o ChatGPT, se lavorano sul codice del sito. Il collegamento si crea da Connettori.

Per chi sviluppa il sito

Qui la parte tecnica, da girare a chi fa l'integrazione. La chiave è nel file di istruzioni scaricato da Skeo, non qui.

Modulo HTML (chiave pubblica)

<form action="https://skeo.it/api/public/leads/inbound?key=LA_TUA_CHIAVE" method="POST">
  <input name="nome_e_cognome" required>
  <input name="email" type="email">
  <input name="telefono" type="tel">
  <textarea name="messaggio"></textarea>
  <input name="_gotcha" style="display:none" tabindex="-1" autocomplete="off">
  <button type="submit">Invia</button>
</form>

Stile e testi sono liberi. Lascia l'indirizzo in action, i nomi dei campi e il campo _gotcha vuoto e nascosto. Dopo l'invio compare una pagina di ringraziamento; per restare sulla pagina, invia con fetch e leggi la risposta JSON.

Da un server, Zapier o Make (chiave segreta)

curl -X POST "https://skeo.it/api/public/leads/inbound" \
  -H "Authorization: Bearer LA_TUA_CHIAVE_SEGRETA" \
  -H "Content-Type: application/json" \
  -d '{"nome":"Mario","cognome":"Rossi","email":"mario@esempio.it","messaggio":"Vorrei un preventivo"}'

• La chiave va solo in Authorization: Bearer (o X-Skeo-Key): nell'indirizzo viene rifiutata.
• Solo da un server: una richiesta da un browser (con intestazione Origin) viene rifiutata. Tienila tra le variabili segrete.
• Corpo JSON o application/x-www-form-urlencoded, con gli stessi campi.

Campi e risposte

• Nome: nome_e_cognome, oppure nome + cognome. Poi email, telefono, azienda, messaggio (finisce nelle note), campagna e i parametri utm_*. Vanno bene anche i nomi inglesi (name, phone, company, message).
• Serve almeno un nome, un'email o un telefono.
• Ogni altro campo (per esempio settore_attivita) arriva da solo nella scheda del lead come campo personalizzato, con il suo nome: "Settore attivita". I campi che iniziano con _ restano fuori. Massimo 20.
• 200 lead arrivato · 400 dati mancanti · 401 chiave sbagliata, revocata o mandata nel modo sbagliato · 429 troppi invii, riprova dopo un minuto · 500 problema nostro, riprova.

In quale kanban arrivano

Con più di un kanban, sotto ogni collegamento attivo c'è Arrivano in: scegli dove finiscono i lead di quel modulo. Due siti, due prodotti? Un collegamento per sito, ognuno col suo kanban. Senza scelta, nel kanban principale.