Web Forms

Web forms let your customers submit structured requests directly from your website. Each submission automatically creates a ticket in RapiDesq, matches or creates a contact record, maps form data to ticket fields, and routes the ticket to the right team or conversation flow — all without any manual intervention.

Overview

A web form is a configurable, embeddable HTML form that acts as an intake channel for your contact center. When a customer fills out and submits a form, RapiDesq executes the following flow automatically:

  1. Customer submits the form on your website (embedded via iframe) or on the standalone form page.
  2. A ticket is created with the channel set to WEB_FORM. Form field values are mapped to the ticket's standard and custom fields.
  3. Contact lookup or creation — RapiDesq matches the submitted email address against existing contacts. If a match is found, the ticket is linked to that contact. If no match exists, a new contact record is created with the source set to WEB_FORM.
  4. Field mapping — Each form field value is stored in the ticket. Standard fields like subject and description map directly; all other field values are stored in the ticket's custom fields (JSONB).
  5. Routing — The ticket is routed based on your form configuration: either to a specific team queue or into a conversation flow for automated triage.
  6. Agent visibility — The ticket, including all form field data, appears in the agent's ticket detail view alongside tickets from chat and email channels.
Note — Web form submissions appear in your unified inbox alongside conversations from chat and email channels. Your agents handle them using the same ticket workflow regardless of source channel.

Creating a Form

To create a new web form, navigate to Admin > Channels > Web Forms and click Create Form. The form builder walks you through the following configuration:

Basic Settings

Setting Description Default
headerText The title displayed at the top of the form. Customers see this as the form heading. "Contact Us"
submitButtonText The label on the form's submit button. "Submit"
successMessage The confirmation message shown to the customer after a successful submission. Use this to set expectations about response time. —
isActive Controls whether the form accepts submissions. Deactivated forms display a message indicating the form is unavailable. Active

Routing Configuration

Every form must be configured with a routing target so that submissions reach the right team or automation:

You must choose one routing method. See the Routing section below for detailed guidance on when to use each approach.

Step-by-Step

  1. Go to Admin > Channels > Web Forms and click Create Form.
  2. Enter the headerText (e.g., "Contact Us", "Request a Demo", "Report an Issue").
  3. Set the submitButtonText to a clear call to action (e.g., "Submit Request", "Send Message").
  4. Write a successMessage that confirms receipt and sets response time expectations (e.g., "Thank you! We've received your request and will respond within 2 business hours.").
  5. Choose a routing target: select a team from the team dropdown, or select a conversation flow from the flow dropdown.
  6. Add and configure your form fields (see Configuring Fields below).
  7. Configure appearance, embedding, and business hours as needed.
  8. Click Save to create the form.
Tip — Create separate forms for different purposes. A "Contact Sales" form can route to your sales team with fields for company size and budget, while a "Technical Support" form routes to engineering with fields for product version and error details.

Configuring Fields

Form fields define what information you collect from customers. Each field has a type that determines its input behavior and validation, along with properties that control its appearance and requirements.

Field Types

RapiDesq supports six field types. Choose the type that best matches the data you need to collect:

Type Input Behavior When to Use
TEXT Single-line text input Short values: names, subjects, account numbers, order IDs. Use for any concise, single-line data.
EMAIL Text input with built-in email format validation Customer email address. Always include at least one EMAIL field — it drives contact matching and is required for follow-up communication.
PHONE Phone number input Customer phone number. Useful when your team needs to call back or when phone is a preferred contact method.
TEXTAREA Multi-line text area Longer descriptions, issue details, reproduction steps. Use when customers need space to explain their request fully.
SELECT Dropdown with predefined options Controlled choice lists: issue category, department, priority level, product name. Standardizes input and enables routing rules. Requires an options array.
NUMBER Numeric-only input Quantities, amounts, reference numbers, or any field where only numeric values are valid.

Field Properties

Every field, regardless of type, supports the following properties:

Property Required Description
name Yes A unique identifier for the field. This is the key used when mapping field values to ticket custom fields. Use descriptive, camelCase names like issueCategory or orderNumber.
label Yes The display label shown above the input. This is what the customer sees (e.g., "Your Email Address", "Describe Your Issue").
required No When set to true, the field must be completed before the form can be submitted. Required fields display a visual indicator to the customer.
placeholder No Hint text displayed inside the empty input. Disappears when the customer begins typing. Use to show expected format or an example value (e.g., "you@company.com").
helpText No Descriptive text displayed below the input field. Use to provide instructions, clarify what information is needed, or explain why the field is being asked (e.g., "We'll use this to look up your account").
validationPattern No A regular expression (regex) pattern for custom input validation. The form will not submit if a field's value does not match its pattern. See examples below.
options SELECT only An array of string values that populate the dropdown choices. Each string becomes a selectable option (e.g., ["Billing", "Technical", "Sales", "Other"]).
displayOrder No An integer that controls the position of the field on the form. Fields are rendered in ascending order. Use increments of 10 (10, 20, 30) to leave room for inserting fields later without renumbering.
category No Organizes the field into a logical group. See Field Categories below.

Validation Pattern Examples

The validationPattern property accepts standard regex syntax. Here are common patterns:

Use Case Pattern Matches
US phone number ^\(\d{3}\)\s?\d{3}-\d{4}$ (555) 123-4567 or (555)123-4567
5-digit ZIP code ^\d{5}$ 90210
Order ID format ^ORD-\d{6,}$ ORD-123456
No special characters ^[a-zA-Z0-9\s]+$ Alphanumeric and spaces only
Note — The EMAIL field type has built-in email format validation, so you do not need to set a validationPattern for email fields. Custom patterns are most useful for TEXT, PHONE, and NUMBER fields where you need to enforce a specific format.

Field Categories

Field categories help organize fields in the form builder and make it easier to find the right field type when adding fields to a form. Categories do not affect how the form is rendered to customers — they are an administrative convenience.

Tip — When building a form, use the category filter in the field picker to quickly locate pre-built field templates. For example, filtering by SUPPORT shows issue type, priority, and other support-related fields ready to add to your form.

Form Appearance

Customize the visual appearance of your form to match your brand. These settings are found in the Appearance tab of the form builder.

Branding

Dark Mode

Enable darkModeEnabled to provide a dark color scheme for the form. When dark mode is enabled, the form automatically uses separate dark color properties for backgrounds, text, and accent elements. This is useful when embedding the form on a website that uses a dark theme, ensuring visual consistency.

Tip — Preview your form in both light and dark mode before publishing. If your website supports both themes, enabling dark mode ensures the embedded form looks correct regardless of which theme the visitor is using.

Embedding Forms

Once your form is saved and active, you can embed it on your website using an iframe or share it as a standalone page via its direct URL.

Iframe Embedding

Copy the embed snippet from the form's Settings tab and paste it into your website's HTML where you want the form to appear:

<!-- RapiDesq Web Form Embed -->
<iframe
  src="https://your-tenant.rapidesq.com/forms/FORM_ID"
  width="100%"
  height="600"
  frameborder="0"
  title="Contact Form"
  allow="clipboard-write"
  style="border: none; max-width: 640px;">
</iframe>

Replace your-tenant with your RapiDesq tenant subdomain and FORM_ID with the form ID shown on the form settings page.

Direct Link

Every form also has a standalone URL that you can share directly. This is useful when you cannot embed an iframe — for example, in emails, social media posts, or QR codes. The standalone form page is fully responsive and uses the same branding configuration as the embedded version.

Domain Whitelist (allowedDomains)

The allowedDomains setting restricts which websites can embed your form. This is a security measure that prevents unauthorized sites from embedding your form and potentially collecting submissions under your tenant.

Important — Always configure allowedDomains for production forms. Without a domain whitelist, anyone can embed your form on their website, which could lead to spam submissions or phishing attempts that appear to come from your organization.
Tip — For a seamless visual experience, set the iframe height to match your form length. A form with 5–6 fields typically fits well in a 600px iframe. Longer forms may need 800px or more. Adjust to prevent scrollbars inside the iframe.

Form-to-Ticket Mapping

When a customer submits a form, RapiDesq creates a ticket and maps the form field values to corresponding ticket fields. Understanding this mapping helps you design forms that produce clean, actionable tickets.

Standard Field Mapping

Form Field Maps To Details
EMAIL field Contact record The email is used to look up an existing contact. If no contact is found, a new contact is created with the source set to WEB_FORM. The ticket is linked to this contact, giving agents access to the customer's full interaction history.
Subject-like TEXT field (e.g., "Subject", "Title") Ticket subject Becomes the ticket's subject line, visible in queue views and search results.
Description TEXTAREA field Ticket description Becomes the ticket's main description, providing the detailed context agents need to resolve the request.
All other fields Ticket custom fields (JSONB) Stored as key-value pairs in the ticket's custom fields. The field name property is used as the key. Values are accessible in the ticket detail view and can be used in routing rules and reporting.

Ticket Metadata

In addition to the field-mapped data, each web form ticket includes:

Note — If a submission's email matches an existing contact, the new ticket is added to that contact's history. This gives agents full context of all previous interactions when handling the request, regardless of which channel those previous interactions occurred on.

Routing

Every web form routes submissions to either a team or a conversation flow. The routing method determines how tickets are queued and processed after submission.

Team Routing (teamId)

When you assign a form to a team, every submission goes directly into that team's ticket queue. This is the simplest routing method.

Flow Routing (flowId)

When you assign a form to a conversation flow, each submission enters the flow before being assigned. The flow can inspect the form data and take automated actions.

See Conversation Flows for details on building flows.

When to Use Each

Scenario Recommended Routing Reason
Single-purpose form (e.g., "Contact Support") Team All submissions are the same type and go to the same team. No conditional logic needed.
Multi-category form with a category dropdown Flow The flow can read the category value and route to different teams based on the selection.
VIP customer detection Flow The flow can look up the submitter's email against your customer database and assign higher priority or a dedicated team for VIP accounts.
Simple feedback or survey form Team Low urgency, no conditional routing needed. A single team reviews all submissions.
Submissions that need auto-reply before assignment Flow The flow can send an immediate acknowledgment email with relevant details before routing to a team.
Tip — Start with team routing and move to flow routing as your needs grow. You can change a form's routing method at any time without affecting previously submitted tickets.

Business Hours & Offline Behavior

Configure business hours on a form to control behavior outside your operating schedule. This sets expectations with customers and prevents submissions from piling up when no agents are available.

Configuring Business Hours

The businessHours setting lets you define the days and times when the form is active. Configure this in the form's Schedule tab:

Offline Message

When a customer visits the form outside of the configured business hours, the offlineMessage is displayed instead of (or alongside) the form. Use this message to:

Example: "Our support team is available Monday through Friday, 9 AM to 6 PM ET. If you submit a request outside these hours, we will respond on the next business day."

Schedule Exceptions

For holidays or special closures, add schedule exceptions to override the standard business hours for specific dates. Exceptions take precedence over the regular weekly schedule, so a form configured as open on Wednesdays will correctly show the offline message on a Wednesday holiday.

Note — If no business hours are configured, the form is available 24/7. Business hours are optional and should only be configured when you need to manage availability or set response time expectations.

Tips & Best Practices

Form Design

Data Quality

Security

Testing

Operations

Note — You can monitor form submission metrics in the Admin panel to track submission volume, completion rates, and routing outcomes. Use this data to optimize your forms over time.