Ticket intake

The ticket intake accepts reports from outside — from the contact form of a customer’s site, from an app or from a server. All three ways create a ticket in the corresponding project, with the response deadline from the customer’s contract.

There are also email and monitors — further down.

Everything is set up in one place: Settings › Ticket intake (owner only). There every project is listed with the measured state of its intake; a click expands it and shows the three cards “Server and app” (intake keys), “Public ticket intake” (form and browser) and “Email intake” (mailboxes). From the project page, “Set up” in the “Ticket intake” row of the overview leads straight to the expanded project. VentionDesk recognises which way a ticket came by the URL it was delivered to — not by anything the sender states.

Before setting up: Whoever writes via the form or the app gives personal data to you and therefore to VentionDesk as a service provider. Only set up the intake for a customer’s site once the data processing agreement with your customer is in place, and point this out on the site — the form code below contains a sentence with a link to your customer’s privacy policy for that.

Setting up the public key and origins

Under Settings › Ticket intake, expand the project, card “Public ticket intake”:

1. “Set up intake” creates the public key vd_pub_…. “Copy” puts it on the clipboard.
2. Under “Allowed origins” you enter every address from which browser reports may come — only scheme, host and port, so https://kunde.de, without a path and without a trailing slash. VentionDesk compares literally.
3. Without an origin entered, the browser way accepts nothing. The HTML form and the server way are not affected.
4. “Turn off intake” removes the key again.

The public key is not secret — it is in the source code of the customer’s site. It can only create tickets in exactly this project.

Way 1: HTML form

An ordinary form that posts to https://in.ventiondesk.com/f/<public key>. You copy the ready-made code in VentionDesk under Tickets › “?” › “Copy form code”:

<form method="post" action="https://in.ventiondesk.com/f/DEIN_PUBLIC_KEY">
  <input name="name" placeholder="Ihr Name" required />
  <input name="email" type="email" placeholder="Ihre E-Mail" required />
  <input name="subject" placeholder="Betreff" required />
  <textarea name="message" placeholder="Ihre Nachricht" required></textarea>
  <p>Mit dem Absenden werden Ihre Angaben zur Bearbeitung an unseren Dienstleister
    übermittelt. Mehr dazu in unserer <a href="DEINE_DATENSCHUTZERKLAERUNG">Datenschutzerklärung</a>.</p>
  <button type="submit">Absenden</button>
</form>

Replace DEIN_PUBLIC_KEY with the public key and DEINE_DATENSCHUTZERKLAERUNG with the privacy policy of the customer’s site.

Optional:

• _redirect — an absolute URL the browser is redirected to after submitting (303). Its origin must be listed under “Allowed origins”, otherwise VentionDesk answers with JSON.
• _hp — a honeypot against bots: a hidden, empty field. If it is filled in, VentionDesk answers politely and creates nothing.
• cf-turnstile-response — the Cloudflare Turnstile token, see below.

Without _redirect, VentionDesk answers with 201 and { "ok": true, "ticket": { "id": "…", "key": "TK-1044" } }.

Way 2: report from the browser

POST https://api.ventiondesk.com/v1/intake/reports with the public key in the x-ventiondesk-key header — from a web app whose origin is listed under “Allowed origins”:

await fetch('https://api.ventiondesk.com/v1/intake/reports', {
  method: 'POST',
  headers: { 'content-type': 'application/json', 'x-ventiondesk-key': 'vd_pub_…' },
  body: JSON.stringify({
    text: 'Saving does nothing',
    email: 'user@customer.com',
    screenshot: 'data:image/png;base64,…',
    meta: { url: location.origin + location.pathname, severity: 'high' },
  }),
});

• text (required): 5 to 5,000 characters. email: optional.
• screenshot: optional, as a data URL (data:image/png, image/jpeg or image/webp in Base64), under 500 kB. The image is attached to the ticket.
• meta: optional — device, version, user, url and severity (low, normal, high, critical). critical sets the ticket’s priority to “Critical”.
• turnstileToken: optional, see below.

The package @ventiondesk/sdk wraps exactly this call (ventiondesk.init({ publicKey }), then ventiondesk.report({ text, screenshot })); it is currently not published on npm. The fetch above does the same.

Way 3: server to server

If the customer’s site has its own backend, it submits with an intake key. You create it under Settings › Ticket intake: the “+” at the top right of the section, then choose the project — an intake key applies to exactly one project and is then listed with that project under “Server and app”. The key is secret and belongs on the server only, never in the browser.

curl -X POST https://api.ventiondesk.com/v1/intake/tickets \
  -H "Authorization: Bearer vd_intake_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane Miller","email":"j.miller@customer.com","subject":"Login does not work","message":"Since this morning I can no longer get into my account."}'

The fields are the same as for the form, plus optionally screenshot (as above) and meta (up to 20 simple values). An intake key can do nothing but submit — it cannot read tasks or see tickets.

Turnstile against bots

If Cloudflare Turnstile is switched on on VentionDesk’s side, the form and the browser way require a Turnstile token (cf-turnstile-response or turnstileToken). If it is missing, VentionDesk answers with 403. By default this check is off for the intake: the form and the browser way sit on your pages, and a Turnstile widget only works on the domains of its site key. It is only switched on by arrangement — your page then needs its own widget with a site key that is valid for its domain. If Cloudflare itself does not answer, VentionDesk lets the report through and marks it as unverified — an outage at Cloudflare should not cost a customer request. The server-to-server way needs no Turnstile.

Checking: does anything arrive?

The public key and every intake key under “Settings › Ticket intake” show “last report … ago” or “no report yet” — measured on real attempts. If the last attempt was rejected, the reason is shown:

Limits

Every intake way accepts up to 10 reports per minute per IP address; a request may be at most 1 MB.

Email

Emails to your workspace’s mailbox become tickets; you set the mailbox name under Settings › Email sender. If a customer replies to an email from VentionDesk, the reply lands in the same ticket — recognised by the email headers, by the ticket number in the address (mailbox+TK-1044@…) or by [TK-1044] in the subject. In a project’s “Email intake” card under Settings › Ticket intake you assign addresses to this project; addresses on another domain need a forward there.

Which addresses create a new ticket: only registered ones. These are your workspace’s mailbox (also an earlier mailbox name and every plus address of it), the addresses from the “Email intake” card of your projects and the sign-in addresses of your workspace’s members. An email to any other address does not become a ticket and appears nowhere — so emails that spam bots send to made-up addresses do not land in your intake. Replies to an existing ticket always arrive, no matter which address they go to. If an email is missing, enter its address in the “Email intake” card of the matching project.

Confirmation of receipt by email: it only goes to senders you know — the ticket is assigned to a customer, or the address belongs to a customer or a portal account of your workspace. For an unknown sender no automatic email goes out; instead an internal note appears in the history, and you reply by hand if the request is genuine. Via form, app widget and server way, new prospects also get their confirmation.

Monitors

In a project’s Analytics tab you create monitors (URL, type “Availability” or “Certificate”, interval). If a monitor fails twice in a row, VentionDesk opens a ticket; once it is reachable again, the ticket is resolved.