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 nameemail
- Customer's email addresssubject
- Conversation subjectmessage
- Main content of the messageslug
- Your organization identifiersuccess_url
/failure_url
- Redirect URLs (for HTML forms)
Basic HTML Example
<form method="POST" action="https://api.getfernand.com/messenger/contact">
<div>
<label for="name">Name</label>
<input type="text" id="name" name="name" required>
</div>
<div>
<label for="email">Email</label>
<input type="email" id="email" name="email" required>
</div>
<div>
<label for="subject">Subject</label>
<input type="text" id="subject" name="subject" required>
</div>
<div>
<label for="message">Message</label>
<textarea id="message" name="message" required></textarea>
</div>
<div>
<input type="hidden" name="slug" value="your-organization-slug">
<input type="hidden" name="redirect_url" value="https://your.website/thank-you">
</div>
<div>
<button type="submit">Send</button>
</div>
</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 astate
parameter ("success" or "error")Error responses include
error
(message) andcode
(HTTP status code) parametersWithout
redirect_url
: The server returns appropriate status codes:204
- Successful submission400
- Field validation errors (JSON response with details)428
- No default channel configured429
- 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.