Contact Form
Octocom makes it easy to collect customer inquiries through contact forms that connect directly to your AI-powered inbox. You can launch a form with zero code, keep the form you already have if it sends submissions by email, or integrate one directly in your site using our API.
Prerequisites
Before you add a contact form, make sure you have:
- ✅ An email integration connected and configured with Octocom
- ✅ The AI replies to new emails toggle turned on (if you want Octocom to automatically respond to inquiries)
- ✅ For the API options, your Octocom business slug that you can find in the contact form settings in the dashboard
Options for launching a contact form
You can set up a contact form in four ways:
- Hosted form (no coding required)
- JSON API call (client-side integration)
- Multipart form (with file upload support)
- Your existing form, by email (no website changes)
1. Hosted form on your customer portal
The easiest way to get started is a contact form hosted on your customer portal.
- Publish the form as a custom page, for example at
https://your-business.octocom.page/contact. Ask Copilot to build and publish it for you. - The page submits to the JSON or multipart endpoint described below.
- Link your site’s “Contact Us” button to the page.
- Optionally serve the portal from your own hostname, such as
help.example.com, with a custom domain.
2. Submitting inquiries via JSON API
If you prefer embedding your own form, you can send inquiries directly to Octocom with a JSON POST request.
Endpoint
POST https://api.octocom.ai/contact-forms/submit-inquiryExample
fetch("https://api.octocom.ai/contact-forms/submit-inquiry", {
method: "POST",
body: JSON.stringify({
businessSlug: "your-business-slug",
customerEmail: values.email,
customerName: values.fullName,
inquiryText: values.message,
tags: ["contact-page"],
}),
headers: {
"Content-Type": "application/json",
},
});Request schema
Octocom validates incoming JSON payloads using this schema:
body: {
businessSlug: string, // Required. Found in Contact Form settings.
customerEmail: string, // Required. Must be a valid email.
emailConfigId?: string, // Optional inbox UUID. Defaults to the business's primary inbox.
customerName?: string,
subject?: string,
inquiryText: string, // Required. Min 1 character.
orderId?: string,
additionalFields?: Record<string, string>,
tags?: string[], // Up to 10 tags, max 50 characters each. See "Tagging submissions".
handedOff?: boolean, // If true, skips AI auto-response and routes directly to a human agent.
files?: Array<{
name?: string,
url: string, // Must be a valid URL
contentType: string,
}>
}orderId is stored as the octocom:orderId conversation metadata key (up to 255 characters). Each additionalFields entry is stored as conversation metadata under a contactForm: prefix, so {"product": "Kettle"} becomes contactForm:product. Python actions and workflows can read them from context["conversation"]["metadata"]. Treat these values as unverified customer input. Up to 50 fields are kept; keys can be up to 188 characters and values up to 50,000 characters. When a submission continues an existing conversation, only keys that conversation does not already have are written.
⚠️ Note: For JSON API submissions, any files must already be uploaded to your own hosting system. You’ll pass file URLs to Octocom.
3. Multipart form (with file upload support)
If you want Octocom to handle file uploads directly, use the multipart form endpoint.
Endpoint
POST https://api.octocom.ai/contact-forms/submit-inquiry-multipart- Files are included as standard multipart attachments.
- The business slug is passed via the
x-octocom-business-slugheader.
Schema (form fields)
{
customerEmail: string, // Required
emailConfigId?: string, // Optional inbox UUID. Defaults to the business's primary inbox.
customerName?: string,
subject?: string,
inquiryText: string, // Required
orderId?: string,
reason?: string,
handedOff?: "true" | "false", // Multipart fields are strings. "true" routes to a human.
tags?: string // See "Tagging submissions"
}Example HTML form
Here’s a ready-to-use form that submits directly to Octocom with file upload support:
<form id="contact-form" enctype="multipart/form-data" method="POST">
<label>Email*</label>
<input type="email" name="customerEmail" required />
<label>Name</label>
<input type="text" name="customerName" />
<label>Subject*</label>
<input type="text" name="subject" required />
<label>Inquiry*</label>
<textarea name="inquiryText" required></textarea>
<label>Order ID</label>
<input type="text" name="orderId" />
<label>Attachments</label>
<input type="file" name="attachments[]" multiple />
<input type="hidden" name="tags" value="warranty-form" />
<button type="submit">Submit Inquiry</button>
</form>
<script>
document
.getElementById("contact-form")
.addEventListener("submit", async (e) => {
e.preventDefault();
const formData = new FormData(e.target);
const res = await fetch(
"https://api.octocom.ai/contact-forms/submit-inquiry-multipart",
{
method: "POST",
body: formData,
headers: { "x-octocom-business-slug": "your-business-slug" },
},
);
if (res.ok) alert("Your inquiry was submitted successfully.");
else alert("Something went wrong.");
});
</script>4. Keep your existing form, by email
If your website form already sends each submission by email, you can keep it as it is. Point it at an inbox connected to Octocom and add one email rule. Your website doesn't change.
The rule is needed because most forms send every submission from one fixed address, with the customer only in the Reply-To header. Without it, Octocom treats that fixed address as the customer: different customers' submissions merge into one conversation, replies go to the form's address instead of the customer, and the per-sender limits can stop new conversations being created. The Use Reply-To as the customer action makes the customer in Reply-To the sender of the conversation.
Set it up
The quickest way is to ask Copilot, for example: "Our website contact form emails us from shop@example.com, so all submissions end up in one conversation. Make each customer get their own conversation." Your Octocom account manager can also set it up for you. To do it yourself:
- Make sure form submissions reach an inbox connected to Octocom.
- Submit your form once and open the email. Note the From address and the subject, and check that Reply-To shows the address you entered in the form.
- Open Settings -> Help Desk -> Email Rules and create a rule:
- Use the Email condition with the From address if that address only sends form submissions.
- Use the Subject condition with the form's subject if the same address also sends other mail, such as order notifications. Otherwise that mail would also be treated as coming from its
Reply-To. - Set the action to Use Reply-To as the customer.
- Optionally choose an inbox under Only on inbox.
- Choose Test email on the same page, enter the From, Reply-To and subject from step 2, and check that the rule matches.
- Submit the form again and confirm that a conversation appears under the customer's address.
What to expect
- The form must set
Reply-Toto the customer. If it is missing, or on the same domain as the From address, the email keeps its original sender. A form that only writes the customer's address in the email body can't use this method: change the form to setReply-To, or use the API. - Submissions are handled as normal email. Auto-merging, spam detection and your AI reply settings all apply, and attachments come through with the email.
- The
contact-formtag is not added automatically. To tag these conversations, add a Subject rule with the Add tag action. - Match other rules on the subject. Hand off and tag rules that match on the sender see the customer's address, not the form's. Sender-based Ignore and Forward rules run first, so they see the form's address and stop the email before this rule applies.
PrestaShop
PrestaShop's standard contact form works with this method. It sends from your store's email address to the address of the contact the customer selects, and sets Reply-To to the customer. Its subject is Message from contact form [no_sync], translated into your store's language, so copy the exact text from a real submission.
Keep the module's notification email turned on, and set the contact's address to your Octocom inbox or forward it there. Custom themes and third-party form modules can behave differently, so always check a real submission as in step 2.
Choosing an email inbox
By default, both API endpoints use your business's primary email inbox. Pass
emailConfigId to route a particular form to a different connected inbox within
that same business. Use the inbox's email configuration UUID, supplied by your
integration administrator, rather than its email address or an inbox view ID.
For JSON submissions, add it to the request body:
{
businessSlug: "your-business-slug",
emailConfigId: "11111111-1111-4111-8111-111111111111",
customerEmail: "customer@example.com",
inquiryText: "Please help with my order",
}For multipart submissions, add a field:
<input
type="hidden"
name="emailConfigId"
value="11111111-1111-4111-8111-111111111111"
/>The selected inbox determines the conversation's email integration, reply address
and AI response settings. A submission can merge into an existing conversation
only within that inbox. handedOff: true still creates a fresh conversation for a
human agent without an automatic AI reply.
An invalid UUID returns HTTP 400. A missing, archived, or other-business inbox returns HTTP 404 without falling back to the primary inbox. If you omit the field, the existing primary-inbox behavior is preserved. Inbox IDs are public routing configuration, not API keys, so keep your existing anti-spam protections in place.
Tagging submissions
Both API endpoints accept custom tags, which are applied to the conversation the submission creates. Tags are useful when you run several forms — a warranty claim form, a wholesale enquiry form, a dispute form — and want to tell them apart in the inbox, filter views by them, or drive routing and automation.
Every contact form conversation is automatically tagged contact-form, whether or not you pass tags of your own.
JSON API
Pass an array of strings:
fetch("https://api.octocom.ai/contact-forms/submit-inquiry", {
method: "POST",
body: JSON.stringify({
businessSlug: "your-business-slug",
customerEmail: values.email,
inquiryText: values.message,
tags: ["warranty-form", "priority"],
}),
headers: { "Content-Type": "application/json" },
});Multipart form
Multipart fields are plain text, so tags accepts either a comma-separated value or repeated fields. Both of these send the same two tags:
<input type="hidden" name="tags" value="warranty-form,priority" /><input type="hidden" name="tags" value="warranty-form" />
<input type="hidden" name="tags" value="priority" />Rules and limits
- Up to 10 tags per submission, each up to 50 characters.
- Tags you haven't used before are created automatically in your organization's tag list. Watch your spelling — a typo creates a new tag rather than matching the intended one, so it's best to hardcode tag values in your form rather than build them from user input.
- Tag values are trimmed, and duplicates within one submission are ignored.
- On the multipart endpoint, tags that are empty or over 50 characters are skipped and the submission still goes through. On the JSON endpoint they're rejected with a validation error, so the whole request fails.
- If a submission is merged into the customer's existing email conversation, the tags are applied to that conversation.
The multipart endpoint also accepts a single tag field. This is a legacy
field kept for backwards compatibility — use tags for new integrations.
Choosing the right option
| Option | Use case |
|---|---|
| Hosted form | Fastest setup, no coding required |
| JSON API | You already manage file uploads and want full UI control |
| Multipart form | You want Octocom to handle file uploads for you |
| Existing form, email | Your form already emails submissions; no website changes |
Security considerations
Rate limits
Octocom applies aggressive rate limits to protect against abuse. This ensures that spam operations attempting to use another business’s slug cannot scale.
If spam is happening at a low volume (under rate limit thresholds), it will usually be detected by human agents quickly. In such cases, report it to Octocom — we’ll propose solutions and remove the spam conversations so the victim doesn’t incur additional charges.
No API keys
Since contact form integrations are publicly visible in a site’s source code, API keys would provide no protection. Instead, Octocom recommends adding captchas and leveraging firewall providers (such as Cloudflare) to block automated spam.
Handling frequent spam
- Preferred option: Expose a public-facing email address instead of a form. Email providers like Gmail and Outlook have strong, battle-tested spam filters.
- If forms must be used: Contact your Octocom account manager. We can coordinate more advanced anti-spam measures such as one-time tokens and other custom solutions.