# Forms

> Building a public intake form, sharing its link, and how a submission becomes a ticket with a customer email thread attached.

Source: https://triagic.com/docs/admin/forms

> **Note**
>
> This is an add-on. Members without a Forms + email seat see a short description and a link to add it; hosted forms keep accepting submissions as long as at least one member holds the seat.

A **form** is a public page your organization builds and shares. Someone fills it in,
and the submission arrives in the Triagic desktop app as a ticket with the customer's
email address on it. Every email after that (the acknowledgement, your team's replies,
the customer's replies) stays on that one ticket, in one mail thread.

Forms are built and managed in the portal under **Forms**, and it is an org-admin page.
Nothing is configured on the desktop side: the app is already signed in to your
organization, so it starts pulling submissions on its own.

> **Note:** If Forms is not in your portal nav
>
> Forms are enabled per deployment. When the feature is off for yours, the nav entry is
> hidden and the public pages return 404. Ask whoever runs your Triagic deployment.

## Building a form [#building-a-form]

### Create it [#create-it]

**New form** asks for one thing, a name. The name becomes part of the public link, and
the link keeps its original wording after a rename, so pick something you would show a
customer. You land in the builder.

### Add fields [#add-fields]

Drag field types from the palette onto the canvas, reorder them, and group them into
sections. Each field has a label, a required switch, optional placeholder and help
text, and an optional show/hide condition. Dropdowns and multi-selects take a list of
options, each with a stored value and the label the customer reads.

### Publish [#publish]

**Publish** validates the form and puts it live. It refuses until the form has at least
one field, has an **Email** field, and that email field is **required**: every
submission becomes a mail thread, so one without an address is a ticket nobody can
answer. It also picks the ticket subject, either the field you marked as the subject or
the first short or long answer field.

### Share the link [#share-the-link]

A live form is at `triagic.com/f/<your-org>/<form-name>`. The link is on the form's page
and in the forms list, with a copy button. Paste it into a help centre, an email
signature, or a support page.

### Embed it in your own site or app [#embed-it-in-your-own-site-or-app]

A live form can also sit inside your own website, help centre or product. Turn on
**Allow this form to be embedded** under **Settings → Embedding**, save, and the tab
shows an embed designer: pick how the form should look on your page, watch it in a live
preview, then copy the **embed link** or the **embed code**. The embed link is the hosted
link with `?embed=1` on it, and the same copy button is on the form's page next to the
hosted link.

The embed code is an `<iframe>` plus a few lines of script that size the frame to the
form, so a long form never scrolls inside its frame and the thank-you page does not
leave a gap under it. After a submission the frame scrolls itself into view. On a page
whose security policy blocks inline scripts, the frame stays 720px tall.

Embedding is off by default, per form, and a form with it off refuses to load inside a
frame. Turning it off again closes every existing embed; the hosted link is unaffected.

#### Make it match your site [#make-it-match-your-site]

Everything the designer offers is an option on the embed link, so you can also write
them by hand, and two pages can embed the same form two different ways. The form's own
theme (Settings → How the form looks) is the default; an option on the link wins over it.

| Option | Values | What it does |
| --- | --- | --- |
| `theme` | `light`, `dark`, `auto` | The colour scheme. Without it an embedded form is light, or uses the form's own background colour. `auto` follows the visitor's device setting |
| `bg` | `transparent`, or a hex colour like `0f172a` | Page background. `transparent` lets your page show through |
| `accent` | Hex colour like `6366f1` | Submit button, required marks |
| `font` | `system`, `serif`, `mono` | Font, from the visitor's device |
| `radius` | `0` to `24` | Corner radius of fields and the button, in px (default 8) |
| `width` | `320` to `1200` | Widest the form column grows, in px (default 608) |
| `padding` | `0` to `64` | Space between the frame's edge and the form, in px (default 20) |
| `align` | `center`, `left` | Where the column sits in a wide frame (default centred) |
| `button` | `auto`, `full` | `full` makes the submit button span the column |
| `title` | `1` | Shows the form's name as a heading. Hidden by default, since your page has its own |
| `logo` | `0` | Hides the logo |
| `intro` | `0` | Hides the text above the form |

Write hex colours **without** the `#`; in a link it starts a fragment. A value that is not
on the list is ignored, never an error. For example:

```
https://triagic.com/f/acme/bug-report?embed=1&theme=dark&bg=0f172a&accent=6366f1&radius=12&button=full
```

These names are reserved, so a field cannot use one as its pre-fill parameter.

`bg=transparent` blends into your page as long as your page does not declare a dark
`color-scheme`; on such a page pass your background colour as `bg` instead.

#### Listen for events [#listen-for-events]

The embedded page posts two messages to the page around it, which the embed code
already uses. Your own script can listen for them too, for example to close a modal
or count conversions. Check `event.origin` before trusting one.

| `event.data.type` | When | Extra |
| --- | --- | --- |
| `triagic:form:height` | The form's height changed | `height`, in px |
| `triagic:form:submitted` | The thank-you page loaded | |

Publishing again after an edit creates a new version. Submissions record the version
they were filled in against, so an old submission still reads with the labels and
dropdown options that were on screen at the time.

**Archive** closes the public link. Submissions already received stay where they are.

### Field types [#field-types]

| Type | What the customer sees |
| --- | --- |
| **Short answer** | One-line text box, up to 500 characters |
| **Long answer** | Multi-line text box, up to 20,000 characters |
| **Email** | Email box. Every form needs one and it has to be required |
| **Dropdown** | Pick one option |
| **Multi-select** | Pick any number of options |
| **Checkbox** | One tick box |
| **Date** | Date picker |
| **Number** | Number box |
| **File upload** | Up to 5 files per submission |

A form holds up to 20 sections of up to 60 fields each.

### Show and hide conditions [#show-and-hide-conditions]

A field can be shown only when another field has a given value: show **Steps to
reproduce** when **Type of problem** is `Bug`. Conditions read dropdowns, tick boxes and
short answers, since those are the values an admin can predict typing into the box.

The condition graph is checked at publish time, not at draft time, so you can leave a
half-built condition while you work. Publish refuses a condition that points at a
missing field, at itself, at a file upload, or around a loop, and says which one.

### Pre-fill from the link [#pre-fill-from-the-link]

Give a field a URL parameter under **Pre-fill from link** and the form opens with that
field filled in from the link: with `plan` on a field,
`triagic.com/f/<your-org>/<form-name>?plan=pro` opens with `pro` in it. Your product
can build the link with what it already knows, such as the signed-in user's email or
account ID. Repeat a parameter to pick several options in a multi-select
(`?area=api&area=billing`); a tick box takes `true`. A value the field would refuse,
like a dropdown option that does not exist, is ignored rather than filled in.

Tick **Hide on the form** to keep the field off the page. Its value still goes into the
ticket, so the agent and your team see it. A hidden field the link leaves out is left
off too, unless it is required, in which case it shows so the submitter can fill it in.
Pre-fill works on the embed link as well. File uploads cannot be pre-filled.

### Preview [#preview]

The **Build** tab's preview is the same renderer as the public page, with the theme and
settings you are editing applied. What you see there is what a customer gets.

## Settings [#settings]

The **Settings** tab, per form:

| Group | What it controls |
| --- | --- |
| **Acknowledgment email** | Whether the person who filled in the form gets an immediate email, and its subject and body. `{{name}}`, `{{ticket_id}}` and `{{form_name}}` are filled in when it goes out. |
| **Triage** | Whether new submissions are investigated automatically, plus tags, a priority and a default assignee recorded on every submission. |
| **Team notifications** | Email addresses to ping per submission, a Slack channel, and a Slack webhook URL. |
| **Attachments** | Whether files can be attached, and the largest file, between 1 and 10 MB. |
| **Spam** | A Cloudflare Turnstile bot check on the public form. Off by default. |
| **Email thread** | Whether a customer reply reopens a resolved ticket, and whether the customer is emailed when their request is resolved. |
| **How the form looks** | Logo address, accent colour, background colour, font (system, serif or monospace), text above the form, text on the thank-you page. |

Four of these are worth reading twice:

**Team notifications are sent by the desktop app**, not by the portal, once it picks the
submission up. The Slack message goes through the Slack connection set up on the
desktop, and the emails through the Resend connection on its **Ticket sources** panel.
Saving either here does not send anything on its own, and a channel or address with no
matching connection behind it is skipped with a log line rather than queued.

The **Slack webhook URL** is the exception: Triagic cloud posts each submission to it the
moment the submission is stored, with no desktop app running. Create an incoming webhook
in Slack (Apps, then Incoming Webhooks), paste its `https://hooks.slack.com/services/…`
address, and save. The address is stored encrypted and shows as `•••` afterwards; use
**Remove** to clear it or replace it.

**Tags, priority and the default assignee are recorded and sent to the desktop**, and
that is all they do today. Nothing in the desktop app tags, prioritizes or assigns a
ticket from them yet, so treat them as a note on the submission rather than as routing.

**The bot check needs Turnstile keys on the deployment.** With none configured, the
switch renders nothing on the form and submissions are accepted as if it were off.

**The acknowledgement is the only email the customer gets automatically.** A resolve
notice needs its own switch under **Email thread**, and it is off by default.

## Working the ticket [#working-the-ticket]

The desktop app polls for new submissions every two minutes. A submission becomes an
ordinary ticket with the source **Form**: the field answers are written into the ticket
body with their labels, attachments are linked, and the customer's email address is on
it.

> **Note:** Auto-triage is on by default for forms
>
> This is the opposite of a connected source such as HubSpot or Zendesk, where triage is
> off until an admin turns it on. A form's triage setting is **per form**, in the portal,
> and starts **on**, so a submission is investigated as it arrives. There is no triage
> switch on the desktop's Forms card, because a per-form setting cannot be expressed by a
> per-source toggle. See [Working tickets](/docs/desktop/tickets).

The ticket has a **Customer email** section holding the whole conversation, oldest
first: the acknowledgement, every reply from your team, every reply from the customer,
and any status notice. Attachments on each message link out. Below it is a reply box,
prefilled from the investigation's suggested reply when there is one, that sends on the
existing mail thread.

**Resolve** on a form ticket pushes the status back up, and mails the customer that
their request is resolved when the form has status emails on. The desktop asks you to
confirm before it does, because that is the one status change that reaches outside the
app.

The portal's **Submissions** tab is read-only: it shows what arrived, per submission,
with the field answers and files. Replies and status changes happen on the ticket.

## Email threading [#email-threading]

Outbound mail is from `"<Your org> Support" <t+<token>@mail.triagic.com>` by default, or
from your own address if your organization has connected its own provider (see
[Email](/docs/admin/email)). The Reply-To is always the Triagic `t+<token>` address, so
whatever the customer's mail client does, a reply to any Triagic email on that request
lands back on the ticket, in order.

- Quoted trails are trimmed, so a reply reads as the new text rather than the whole
  history again.
- A reply on a resolved request reopens it, when **Reopen a resolved ticket when the
  customer replies** is on. With it off the reply is still recorded, and the ticket
  stays closed.
- Replies appear on the ticket within about three minutes of arriving.
- Files the customer attaches to a reply are stored and linked on the message, and count
  towards your storage allowance.

> **Warning:** Triagic's shared sending domain
>
> Unless you connect your own provider, form email goes out through `mail.triagic.com`, so
> Triagic sends at most **100 emails a day per organization** across acknowledgements,
> replies and status notices, inside a monthly cap (see [Limits](#limits)). Past either one
> a reply is refused, and the desktop tells the agent to wait or to use their own mail
> client. To send from your own domain with no cap, connect your own provider under
> [Email](/docs/admin/email).

## Limits [#limits]

| | Trial and free | Paid plan |
| --- | --- | --- |
| **Live forms** | 1 | 10 |
| **Submissions per month** | 50 | 1,000 |
| **Attachment storage per month** | 100 MB | 5 GB |
| **Outgoing emails per month** | 100 | 500 |
| **"Powered by Triagic" on the form** | Yes | No |

The email limits apply only while you use Triagic's sending domain. See [Email](/docs/admin/email).

The paid column applies while the subscription is active. An expired or canceled one
falls back to the free limits, which can put an organization over its cap without
anything else changing.

Also fixed, on every plan:

- **5 files per submission**, each up to the size the form sets (1 to 10 MB).
- **Images, PDF, plain text, JSON and ZIP** are accepted. SVG is refused, because an SVG
  is a script document.
- **10 submissions per 10 minutes** from one network address to one form.
- Archived forms do not count against the live-forms limit. Publishing when you are
  already at the limit is refused.

Both counters are monthly and reset on the first of the month, UTC. The storage figure
counts what was uploaded during that month, including files attached to customer
replies; files stored in an earlier month do not count again. The portal's **Usage**
page shows both running totals, as **Submissions** and **Attachment storage**, with the
date they reset.

### At the cap [#at-the-cap]

The account owner gets one email when the organization passes **80%** of either monthly
cap, and one when it reaches **100%**. Each is sent at most once per month, and usage
that jumps straight past the cap gets only the second one. It goes to the owner rather
than to every admin because changing the plan is an owner action. Admins see the same
figures on the **Usage** page.

At 100% the forms stop accepting submissions. Anyone who opens one reads *"This form is
temporarily unavailable. Please try again later or contact the team directly."* instead
of the fields, and nothing they write is recorded. Every submission already received is
untouched. The allowance resets on the first of the next month and the forms reopen on
their own; moving to a plan with a higher allowance reopens them the same day.

## Forms API [#forms-api]

Your own systems can file submissions and read them back with an **API token**. A
submission filed through the API is the same as one typed into the hosted form: it is
checked against the same fields, counts toward the same monthly allowance, becomes a
ticket, and gets the same acknowledgement email and Slack message. The API skips only
the bot checks (captcha and the per-visitor limits), because the token proves who is
calling.

### Tokens [#tokens]

**API tokens** in the portal sidebar is for org admins only. Create a token, name it
after the system that will use it, and copy it straight away: it is shown once and
cannot be read again. Each token acts for the whole organization, not for the admin who
made it, so it keeps working if that admin leaves.

- **Rotate** gives the token a new secret under the same name and stops the old secret
  at once. To swap with no gap, create a second token, deploy it, then revoke the first.
- **Revoke** stops a token at once. Revoked tokens stay listed so the audit log still
  names them.
- Every create, rotate and revoke is in the audit log. The list shows when each token
  was last used.

An organization can hold 20 active tokens. Tokens need the Forms add-on, and stop
working while the organization has no Forms seat.

### Calls [#calls]

Send the token as a bearer token. Every call is scoped to the token's organization; a
form from another organization answers 404, the same as one that does not exist.

```bash
curl https://triagic.com/api/v1/forms \
  -H "Authorization: Bearer $TRIAGIC_TOKEN"
```

| Call | What it does |
| --- | --- |
| `GET /api/v1/forms` | Every form with its status, link and the fields of its published version (`id`, `label`, `type`, `required`, `options`) |
| `POST /api/v1/forms/{formId}/submissions` | Files a submission to a live form. Answers `201 {"id"}` |
| `GET /api/v1/forms/{formId}/submissions` | Submissions, newest first, 50 a page. Pass the returned `nextBefore` as `?before=` for the next page |

A submission is JSON with the answers keyed by **field id**, which `GET /api/v1/forms`
lists for each form:

```bash
curl https://triagic.com/api/v1/forms/$FORM_ID/submissions \
  -H "Authorization: Bearer $TRIAGIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"3f9c2a1e": "ada@example.com", "b07d4e55": "Export is broken", "c1a8e9f0": ["api", "ui"]}}'
```

Text, email, date and dropdown answers are strings, numbers are numbers, a multi-select
is a list of option values and a tick box is `true` or `false`. Field ids not on the form
are ignored. To attach files, send `multipart/form-data` instead, with one part per field
id and the files under the file field's id.

| Status | Meaning |
| --- | --- |
| `401` | Missing, malformed, unknown or revoked token |
| `404` | No such form in your organization, or (for a submission) the form is not live |
| `400` | The body is not `{"fields": {…}}` JSON or form data |
| `422` | Answers failed the form's checks. `errors` maps field id to the reason |
| `429` | Too many calls (120 a minute per token), or the monthly submission allowance is spent |

## How submission data is handled [#how-submission-data-is-handled]

**Answers and email.** A submission's field answers, the submitter's email address and
name, and every message in the email conversation are stored in Triagic's cloud so the
thread can be continued and so the desktop app can pull the ticket down. The desktop
app keeps its own copy of the ticket on each member's machine.

**Uploaded files are stored privately.** Every attachment is authorized per request:
opening one checks that you are signed in and that the file belongs to your organization,
and there is no link that works without that. An attachment link copied out of the portal
or out of a ticket is useless to anyone else. Uploads are always served as a download
rather than displayed in the browser.

**Retention.** **Organization → Form data retention**, an admin card, sets how long
submissions are kept: forever, or 90, 180 or 365 days. It is one setting for the whole
organization, and the default is keep forever. The age is measured from when the submission
**arrived**, not from the last message on it. A daily job permanently deletes everything
past that age: the answers, the uploaded files, and every email in the conversation with
the person who sent it. It cannot be undone and Triagic keeps no copy.

Changing the setting applies to submissions you already have, not only to new ones, so
shortening the window deletes older submissions on the next daily run. A large backlog
clears over several days rather than in one run. Tickets your team has already pulled
into the desktop app stay on their machines; this setting controls what the cloud keeps.

Retention deliberately leaves three things alone: your form definitions, which are your
own configuration; the monthly usage counters, which are billing history rather than
customer content; and the audit trail, including the record of who changed this setting.

**Deleting on request.** The retention setting is the deletion path. There is no
per-submission delete button today, and archiving a form does not delete what it already
collected. To honour a deletion request for a whole organization, set retention to 90
days, or to the shortest window that suits you, and the next daily run removes
everything past it.

## Not available yet [#not-available-yet]

Named here so nobody plans around them: multi-step forms, a rule engine for routing, virus scanning of uploads, a status page for the submitter, and SLA
timers.
