The Contact Form is a lightweight, embeddable form designed for public websites where visitors are not logged in. Visitors provide their name, email, and message. Submissions appear in your Helpdesky dashboard under Messages.
Contact Form vs Ticket Center: The Contact Form is for anonymous visitors on public pages. No authentication is required. The Ticket Center is for authenticated users inside your application who need to view and manage their support conversations.
The form is a single JavaScript file (contact-form.js) that renders itself into a container element on your page. It handles its own styling, validation, submission, and success state. No framework dependencies are required.
Quick Start
Get the contact form on your website in two minutes.
Enable messaging. In your Helpdesky dashboard, go to Messages and make sure messaging is turned on. The toggle is at the top of the Messages page.
Add the embed code. Go to Contact Form in the dashboard sidebar. Copy the embed code and paste it into your website's HTML where you want the form to appear:
<div id="hdh-contact-form"></div>
<script src="https://helpdesky.io/contact-form.js"
data-helpdesk-id="YOUR_HELPDESK_ID"></script>
Tip: The embed code in your dashboard already has your helpdesk ID filled in. Just copy and paste it directly.
Done. The form will automatically render in the container div. When a visitor submits, it creates a new conversation in your Messages inbox. You can reply from the dashboard, and your response will be emailed to the visitor.
Data Attributes
Configuration options are passed via the script tag.
| Attribute | Required | Description |
|---|---|---|
data-helpdesk-id |
Yes | Your helpdesk's unique identifier. Found in the embed code on the Contact Form dashboard page. |
data-container |
No | The ID of the container element. Defaults to hdh-contact-form. Use this if you need a different container ID. |
data-align |
No | Form alignment: left, center (default), or right. Can also be set from the dashboard. |
data-max-width |
No | Maximum width of the form. Defaults to 560px. Accepts any valid CSS value. |
Example with all attributes:
<div id="my-support-form"></div>
<script src="https://helpdesky.io/contact-form.js"
data-helpdesk-id="YOUR_HELPDESK_ID"
data-container="my-support-form"
data-align="left"
data-max-width="480px"></script>
Customization
All appearance settings are configured in the Contact Form page of your dashboard under the Appearance section. Changes are saved to your helpdesk and automatically applied whenever the form loads.
| Setting | Default | Description |
|---|---|---|
| Button Text | Send message | The text displayed on the submit button. |
| Button Color | #222222 | The background color of the submit button. Use the color picker or enter a hex value. |
| Success Heading | Message sent successfully | The heading shown after a successful submission. |
| Success Message | Thank you for reaching out... | The body text shown after a successful submission. |
| Alignment | Center | How the form is positioned within its container: left, center, or right. |
The preview panel on the right side of the dashboard shows your changes in real time before you save.
Email Notifications
When you reply to a contact form conversation, the visitor receives an email notification at the address they submitted. Notifications are delayed by 60 seconds and can be skipped if the visitor reads the reply before the email is sent. You can also send emails immediately using the Send Instantly toggle. See Email Notification Timing for full details.
Cloudflare Turnstile
Turnstile adds bot protection to your contact form. Without it, your form has no spam prevention and you may receive large volumes of unwanted submissions. Turnstile is free for unlimited use and we strongly recommend setting it up.
Create a Turnstile widget. Go to the Cloudflare Turnstile dashboard and create a new widget. You do not need to use Cloudflare as your DNS provider. Turnstile works with any domain.
Add your domain. In the widget settings, add the domain(s) where the contact form will be embedded to the Allowed Hostnames list. For example, yoursite.com and www.yoursite.com.
Enter the keys in your dashboard. Copy the Site Key and Secret Key from Cloudflare and paste them into the Turnstile section on the Contact Form dashboard page. The Site Key is embedded in the form (public). The Secret Key is used to verify submissions on the server (private, never shared).
Save. Click Save Settings. The Turnstile challenge will automatically appear on your contact form. Submissions that fail verification will be rejected.
For a step by step walkthrough with screenshots, see Setting Up Cloudflare Turnstile.
Custom CSS
Add custom CSS in the Custom CSS section of the Contact Form dashboard page. Your CSS is injected into the form's container, so it takes precedence over the default styles.
Available class names: .hdh-cf-form, .hdh-cf-submit, .hdh-cf-success, .hdh-cf-error
Example: change border radius and add a brand color:
.hdh-cf-form {
border-radius: 8px;
border-color: #6366f1;
}
.hdh-cf-submit {
background: #6366f1;
border-radius: 8px;
}
.hdh-cf-submit:hover {
background: #4f46e5;
}
Example: make the form full width with squared corners:
.hdh-cf-form {
max-width: 100%;
border-radius: 0;
border: none;
box-shadow: none;
padding: 0;
}
.hdh-cf-form input,
.hdh-cf-form textarea {
border-radius: 4px;
}
.hdh-cf-submit {
border-radius: 4px;
}
Troubleshooting
Form not appearing. Check that the container element (<div id="hdh-contact-form">) exists in the DOM before the script loads. The script must be placed after the container div, not in the <head>. Also verify that your data-helpdesk-id is correct.
"Contact form not available" error. This means either messaging is disabled for your helpdesk, or the messaging feature has not been enabled for your account. Two conditions must both be true: messaging must be enabled in your dashboard (Messages page toggle), and the messaging feature must be activated for your account.
Turnstile showing "Unable to connect to website". This happens when the domain the form is running on is not in your Turnstile widget's allowed hostnames list. Go to your Cloudflare Turnstile dashboard, edit your widget, and add the domain where the form is embedded. If you are testing locally (e.g. localhost:3000), you can temporarily remove the Turnstile keys from your Contact Form settings to disable the challenge during development.
Form values cleared on error. This was a known issue that has been fixed. The form now preserves entered values when an error occurs. If you are seeing this behavior, make sure you are loading the latest version of the script by adding a cache busting query parameter: contact-form.js?v=2.
Form looks different from the preview. Your website's global CSS may be affecting the form's appearance. The form renders directly in the page (not in an iframe), so your site's styles can cascade into the form elements. Use the Custom CSS feature to override any conflicts, or wrap the container div in a CSS reset.