Collegare il modulo del sito con il tuo assistente AI

Il sito ha già il suo modulo di contatto, magari fatto su misura, e ci lavori con un assistente AI che vede il codice: Claude Code, Cursor, Codex, Lovable, Copilot, o ChatGPT collegato al repository. Invece di rifare il modulo, gli fai collegare quello che c'è: ogni persona che lo compila arriva anche nel kanban di Skeo. Tu incolli un prompt, lui scrive il codice.

In Skeo: crea la chiave

1. Apri Connettori, riquadro Il modulo del tuo sito, e scegli Con il tuo assistente AI.
2. Lascia il nome proposto ("Assistente AI") o cambialo, e premi Crea la chiave.
3. Tieni aperto il riquadro: la chiave si vede una volta sola. Se devi chiuderlo prima di aver finito, premi Scarica le istruzioni.

Salva la chiave nei segreti dell'hosting

La chiave è segreta: va dove il sito tiene le password, non nel codice. Crea una variabile con nome SKEO_API_KEY e come valore la chiave (in Skeo c'è un pulsante per copiare l'uno e l'altro).

• Vercel: il progetto, Settings, Environment Variables.
• Netlify: le Environment variables del progetto.
• Cloudflare: il progetto, Settings, Variables and Secrets.
• Lovable: i Secrets del progetto.
• Un tuo server: il file .env, che non va mai nel repository.

Dopo aver aggiunto la variabile, di solito il sito va ripubblicato perché la legga.

Perché la chiave non è nel prompt

Quello che scrivi in una chat con un'AI resta nella cronologia, e a volte nei registri di chi la fornisce: da lì non lo cancelli più. Per questo il prompt dice all'assistente di leggere la chiave da SKEO_API_KEY e di non chiedertela mai. Se te la chiede lo stesso, non dargliela: aggiungi la variabile e diglielo.

Il prompt da dare all'assistente

È lo stesso che trovi in Skeo, con il pulsante Copia il prompt. Incollalo nella chat dell'assistente che lavora sul sito.

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 dal kanban.
2. Poi dimmi: quale modulo hai collegato, come hai abbinato i campi, dove leggi la chiave
   e com'è andata la prova.

Cosa fa l'assistente, e come sai che ha funzionato

1. Trova il modulo e il punto del server dove arriva l'invio.
2. Aggiunge la chiamata a Skeo accanto a quello che c'è già: le email e la pagina di ringraziamento restano.
3. Manda un lead di prova chiamato «Prova Skeo»: deve comparire nella prima colonna del kanban. Poi cancellalo: nel conteggio dei lead del mese resta, come ogni lead arrivato.
4. Ti scrive cosa ha collegato, come ha abbinato i campi e com'è andata la prova.

Se qualcosa non va

• Ti chiede la chiave: non incollarla. Controlla che la variabile SKEO_API_KEY ci sia e che il sito sia stato ripubblicato.
• Dice che il sito è statico: senza una parte server la chiave segreta non si può usare. Crea invece il modulo pronto di Sul tuo sito, come spiega la guida del modulo del sito.
• La prova risponde 401: chiave sbagliata o revocata, oppure la richiesta parte dal browser o si porta dietro le sue intestazioni. Deve partire dal server, con la chiave solo in Authorization: Bearer.
• Risponde 429: troppe prove di fila. Aspetta un minuto.

Chiave finita nella chat?

In Skeo premi Revoca su quel collegamento, creane uno nuovo e sostituisci il valore di SKEO_API_KEY. Quella vecchia smette subito di funzionare. Usi Make o hai uno sviluppatore invece di un assistente? C'è la guida per Make o un server.