A Velk form is any form whose submissions should land in the admin: contact, quote, job application, newsletter. You tell the AI the fields, which are required and what the visitor reads after sending. The AI declares the form in site.json, the file that holds the site's structure, and writes its HTML in the theme, in the site's style. Velk then validates, saves and e-mails each submission and keeps bots out; a lead is saved even when the e-mail fails.
Ask the AI
Add a quote form to the Contact page of the bakery site. Fields: name (required), e-mail (required), WhatsApp, event date, number of guests, type of order (wedding cake, birthday, corporate) and a message. After sending, show: Thanks! We reply within one business day. In the admin, label each lead by name, with the type of order under it. No file upload for now. Run schema:validate at the end.
Check the field names before approving: a CRM receives the fields under them, and saved leads keep the old names if you rename later.
What the AI does
- Declares the form in
site.json: an id (quote), the fields, the success message and the e-mail subject, which can include the visitor's name. Fields can be text, e-mail, phone, URL, number, long text, checkbox, a list of options, hidden or a file. - Names the field that labels each lead in the admin (
preview_field) and, since v3.8.0, the one on the card's second line (preview_subtitle_field). - Writes the form in the template, with the security token, the antispam and a sentence for each outcome: Velk returns codes, and the theme puts them in the site's words.
- Runs
schema:validateand sends a test.
In the admin
| On the form's screen | What the client does there |
|---|---|
| Recipients | Adds or removes who receives each lead by e-mail. With nobody listed, leads are still saved. |
| Submissions | One card per lead. Opened, it shows every field, the source page, the campaign, attachments and whether the e-mail went out. |
| Filters | By period; on multi-step forms, also finished or in progress. |
| Spam | What the antispam blocked, on forms that keep it. |
| Conversion tracking | The e-mail and phone fields for ad conversions (see Tracking and consent). |
| Export | Downloads the leads as a CSV file. |
Spam: the trap, Turnstile and the Spam list
Every form has a honeypot, a hidden field only bots fill in. A caught bot gets a fake “sent” and nothing is e-mailed. Since v3.7.5 a small script empties that field in real browsers, so autofill no longer gets people blocked.
Cloudflare Turnstile is the optional second layer: create a widget in the Cloudflare dashboard (no need for Cloudflare's DNS) and give the AI its two keys, which go in .env. Whoever fails it sees an honest error; if Cloudflare is down, the submission goes through.
Both checks reject a real person now and then. With keep_spam on, a form keeps what they block in a Spam list, tagged with the check that caught it, without attachments. Not spam (v3.7.3) moves a lead back, without e-mail or webhook, since it may be weeks old. Mark as spam (v3.7.6), next to Delete, moves junk there instead of destroying it, and can be undone.
Ask the AI
Protect the clinic site's contact form. I created a Turnstile widget in Cloudflare for the clinic's domain: ask me for the two keys. Keep what the antispam blocks, so we can rescue real patients, and tell me how to schedule the cleanup of spam older than 30 days on our hosting.
Neither the deploy nor a theme publish sends your local .env to the server: on a live site, the keys go in the server's .env too.
Attachments, campaign and CRM
A file field takes one file (PDF, JPG, PNG, WebP, GIF, DOCX, XLSX, PPTX or ZIP; SVG only when asked for) of up to 10 MB, unless you set another limit; the hosting's can be lower. Attachments stay private: out of the media library, downloadable only from the lead, deleted with it.
The campaign is recorded on its own: the UTM parameters and the ad click IDs of Google (gclid, gbraid, wbraid), Meta (fbclid), Microsoft, TikTok, LinkedIn and X, read from the address the visitor arrived at and kept while they browse. Nothing outside that fixed list is stored, so personal data that lands in an address by accident never is.
A webhook, a small function in the theme, passes each saved lead on to a CRM, a spreadsheet or Slack. If it fails, the lead stays saved and the error goes to the log. With the click ID, the CRM can report sales back to the ad platform; that import happens outside Velk.
Multi-step forms (since v3.7.8)
A long form can be split into steps saved as the visitor goes: the first creates the lead, the others complete it, so someone who gives up halfway still leaves a name and an e-mail.
- An unfinished lead shows “step 2 of 3” in the admin, where a filter shows finished leads (the default), those in progress, or all.
- The e-mail and the conversion happen once, on the last step, with the whole lead.
step_webhooksends each step to the CRM as it arrives, and again if the visitor goes back to fix one.- The campaign is recorded, and the antispam runs, on the first step.
- Steps need JavaScript; no other form feature does.
Ask the AI
Turn the solar panel quote form into three steps: 1) name, e-mail, phone and the consent checkbox; 2) ZIP code, city and roof type; 3) average power bill and a message. Send each step to our CRM as it arrives, so sales can call people who stop halfway. Keep the current success message.
The AI checks with schema:validate that each field sits in exactly one step, and updates the template to match.
Exporting leads (since v3.8.0)
The Export block on the form's screen downloads a CSV of approved, finished leads, with the columns (each field, plus metadata and tracking groups, off by default), period and separator you choose. It opens in Excel with accents intact, and a cell that starts like a formula is written as text, so nothing a visitor typed runs in the spreadsheet. The download address keeps your choices, as a saved export. On a live site, the AI runs form:export on the server and saves the file on your computer.