HTML Submissions

ALTCHA Forms allows you to submit your custom web forms without server-side integration, simply by configuring the form’s action URL.

Features

• Field validation
• Built-in Captcha protection
• Supports submission processors
• Custom redirect URL after submission

Easy Setup

To get started with custom HTML forms, configure the action attribute of the form to point to the ALTCHA Forms URL.

Step 1: Create an HTML Form

Create a new HTML form on your website. Here’s an example:

<form
  action=""
  method="post"
>
  <input type="email" name="email" required />
  <input type="text" name="name" required />
  <textarea name="message" required></textarea>
  <button type="submit">Submit</button>
</form>

• action: This will be updated later to point to the ALTCHA Forms URL.
• method="post": Ensures that the form data is submitted using the POST method.
• required: Ensures that the fields are filled out before submission.

Step 2: Create a New Form in ALTCHA Forms

1. Open the ALTCHA Forms application.
2. Create a new form with fields matching those in your HTML form. Ensure each field’s name attribute in ALTCHA Forms matches the corresponding field in your HTML form.
3. Optional: If you want to allow the submission of arbitrary data without validation, you can leave the form empty without any fields or steps. This will disable field validation and allow submissions of any data.

Step 3: Update the HTML Code

1. Copy the URL of the form from the ALTCHA Forms application.
2. Update the action attribute of your HTML form to include the copied URL:

<form
  action="https://eu.altcha.org/form/1j9nksueu6wpBNKjrCTMP"
  method="post"
>
  <input type="email" name="email" required />
  <input type="text" name="name" required />
  <textarea name="message" required></textarea>
  <button type="submit">Submit</button>
</form>

Step 4: Configure Custom Success Page

To redirect users to a custom page after form submission:

1. Go to the form’s Settings in the ALTCHA Forms application.
2. Set the Success Redirect URL to the desired URL on your website.

Submitting with XHR/Fetch

You can also submit your form using XHR (Ajax) or Fetch with FormData or a JSON-encoded payload. The API always returns a JSON object with success: bool and error: string? if an error occurs.

{
  "error": "<error message>",
  "success": false
}

Caution

When submitting via XHR or Fetch, the form must include the ALTCHA widget, and the altcha payload must be submitted as part of the form data.

Field Validation

The Forms application validates the submitted data based on the configured fields, so ensure that all fields are properly added to the form’s configuration under the Design tab.

To disable validation and allow submissions of any arbitrary data, simply remove all fields and steps from the form’s configuration.

Adding ALTCHA Widget

You can also add the ALTCHA widget to your form to skip the manual security check on the submission page. Follow the integration steps and configure the challengeurl as follows:

<altcha-widget
  challengeurl="https://eu.altcha.org/form/1j9nksueu6wpBNKjrCTMP/altcha"
></altcha-widget>

Append /altcha to the form’s URL. The name of the field must be altcha (do not change the name attribute of the widget).

Analytics

The ALTCHA widget supports integration with analytics for your HTML forms.

To enable analytics, add the analytics attribute to the widget:

<altcha-widget
  analytics
></altcha-widget>

This configuration will:

• Submit recorded session data upon form submission.
• Enable beacon reporting for abandoned (unsubmitted) forms.

Caution

Ensure that the <altcha-widget> is placed inside the <form> element. Analytics will not function correctly without the wrapping <form> element.

Redirects

To enhance the user experience, provide a custom ?ref= parameter in the submission URL to indicate the URL of your website where the form is located. This allows “go back” actions in the Forms UI to navigate back to your website seamlessly after a submission. Custom “success redirects” configured in the application are also supported.

<form
  action="https://eu.altcha.org/form/1j9nksueu6wpBNKjrCTMP?ref=https://example.com/contact"
  method="post"
>

File Upload

File uploads are not currently supported. This is a planned feature for future releases.

Supported Encodings

Currently supported body encodings:

• application/x-www-form-urlencoded
• multipart/form-data
• application/json

Troubleshooting

In case of errors or unsuccessful submissions:

• Ensure all form fields are correctly named and match those in ALTCHA Forms.
• Verify that the action URL is correctly set.
• Check for any required fields that might be missing.