Headless contact form

Create custom forms on your website that connect directly to Fernand conversations. This integration allows you to place headless contact forms anywhere without requiring our JavaScript widget.

Basic implementation

To create conversations from a static form, send a POST request to https://api.getfernand.com/messenger/contact with these required fields:

• name - Customer's name

• email - Customer's email address

• subject - Conversation subject

• message - Main content of the message

• slug - Your organization identifier

• success_url/failure_url - Redirect URLs (for HTML forms)

Basic HTML Example

<form method="POST" action="https://api.getfernand.com/messenger/contact">
    <label for="name">Name</label>
    <input type="text" id="name" name="name" required>

    <label for="email">Email</label>
    <input type="email" id="email" name="email" required>

    <label for="subject">Subject</label>
    <input type="text" id="subject" name="subject" required>

    <label for="message">Message</label>
    <textarea id="message" name="message" required></textarea>

    <input type="hidden" name="slug" value="your-organization-slug">
    <input type="hidden" name="redirect_url" value="https://your.website/thank-you">

    <button type="submit">Send</button>
</form>

Response handling

We recommend using JavaScript XHR/fetch to handle responses directly on your site, but you can also use redirect URLs:

• With redirect_url: Users are redirected with a state parameter ("success" or "error")

• Error responses include error (message) and code (HTTP status code) parameters

• Without redirect_url: The server returns appropriate status codes:

  • 204 - Successful submission

  • 400 - Field validation errors (JSON response with details)

  • 428 - No default channel configured

  • 429 - Rate limited (too many requests)

Advanced Features

These advanced features require JSON submissions rather than basic HTML forms.

Custom fields

Add additional data using the extra parameter:

{
    "extra": [
        {
            "label": "Company Role",
            "value": "CEO"
        },
        {
            "label": "Company Size",
            "value": "1-10"
        },
        {
            "label": "Company Name",
            "value": "Acme Corp"
        }
    ]
}

File attachments

Include files using the attachments parameter:

{
    "attachments": [
        {
            "name": "screenshot.png",
            "type": "image/png",
            "size": 15631,
            "content": "iVBORw0KGgoAAAANSUhEUgAAAB..."
        }
    ]
}

Conversation tags

Automatically apply tags to new conversations:

{
    "tags": ["website-inquiry", "support", "new-customer"]
}

Channel routing

Override the default channel with the channel parameter:

<input type="hidden" name="channel" value="support@example.com">

You can also provide a SHA256 hash of the email to keep it hidden:

<input type="hidden" name="channel" value="e133c661d9106a35fb30c8ee2d0d5a5a279505e573d9f4f4d24d5aed1e9f59e4">

User authentication

Authenticate users by providing a hash parameter created by signing the user's email with your secret key:

<input type="hidden" name="hash" value="fc3cf30c76a8b5c1c875b79c53a36bd8e2d653a1ec00c11fff538583ef759244">

For detailed instructions on generating this hash, see Authenticating Users.

Security measures

We implement several protections against abuse:

• Rate limiting: 5 submissions per minute per IP address

• Daily submission limits to prevent excessive use

• User-agent filtering to block submissions from bots and automated systems

These measures ensure your headless contact forms remain secure while providing a smooth experience for legitimate users.