Hotsite Form Integration (Lead API Key)

Caramelo AI offers a simple and secure way for you to send contacts (leads) captured on your Landing Pages, Hotsites, and external forms directly to your Customers dashboard and automate your customer service flows.

To do this without exposing sensitive data from your project, we use Hotsite Keys (Lead API Keys).

These keys are “public,” meaning they were specifically designed to be placed in the JavaScript code of your pages. They only have permission to create and update contacts, being incapable of reading or deleting any data from the system.

1. How to Generate Your Hotsite Key

1. Access the Caramelo AI Dashboard and enter your Project.
2. In the left sidebar menu, click on Integrations > Hotsite Keys (Leads).
3. Click the Create button.
4. Enter a Name (e.g., “Black Friday Landing Page”) and an optional brief description.
5. After creating, your key (starting with lfk_) will be displayed. Copy this key.

2. How to Integrate into Your Hotsite (JavaScript)

Data is sent via an HTTP POST request to our public API, sending the key in the X-Lead-Key header.

Add the code below to the JavaScript that processes the button click on your form:

// Replace PROJECT_ID and the KEY below with your actual data.
const PROJECT_ID = "your_project_id";
const LEAD_API_KEY = "lfk_your_key_here";

// Assemble the payload with the form data
const leadData = {
	name: "John Doe", // Optional: Lead's Name
	email: "john@example.com", // Required: E-mail (used as unique identifier)
	phone: "11999999999", // Optional: Phone
	interests: "product-x", // Optional: Product of interest

	// The 'data' field is freeform. Use for custom fields that will be permanently saved in the customer's profile
	data: {
		chosen_plan: "Pro Plan",
	},

	// Tags that will be added to the Lead
	tags: ["hotsite", "black-friday"],

	// Honeypot: Anti-bot security field (Always leave EMPTY when sending via code!)
	_hp: "",
};

// Data tied to the conversion event that will appear in the customer's "Timeline"
const eventData = {
	utm_source: "google",
	utm_campaign: "black-friday",
	page_url: window.location.href,
};

// Fire the request to Caramelo AI
fetch(`https://api.carameloai.com/api/ext/project/${PROJECT_ID}/lead`, {
	method: "POST",
	headers: {
		"Content-Type": "application/json",
		"X-Lead-Key": LEAD_API_KEY,
	},
	body: JSON.stringify({ 
		lead: leadData,
		event: eventData
	}),
})
	.then((response) => response.json())
	.then((data) => {
		if (data.success) {
			console.log("Lead successfully sent! ID:", data.customer_id);
			// Redirect user or show success message
		}
	})
	.catch((error) => {
		console.error("Error sending lead:", error);
	});

3. Anti-Bot Security (Honeypot)

The Leads endpoint features native Spam protection through the “Honeypot” technique + IP Rate Limiting.

The _hp field present in the code above must be sent empty. If any spam bot crawls your code and automatically fills this field with any text, the request will be silently invalidated. The system will pretend everything went fine for the bot, but the Lead will not be inserted into the Caramelo database.

4. Domain Protection (Origin)

To prevent unauthorized use of your key on other websites, you can restrict which domains your key accepts requests from.

When creating or editing your Hotsite Key in the Dashboard, there is an optional field for Allowed Domains (Origin).

• If left blank, the key accepts requests from anywhere (useful for testing).
• If you fill it with https://myhotsite.com, https://othersite.com, the Caramelo AI API will validate the request’s Origin header and automatically block any submission coming from an unlisted domain.

5. Triggering Flows (Automations)

Upon receiving the post, the API will search your project:

1. The API will strictly search for the contact using the provided email.
2. If the Lead does not exist in the database, they will be Created using all the data sent (Name, Phone, WhatsApp, etc.).
3. If the Lead already exists, the system will focus on Data Integrity: the main fields (name, phone, whatsapp) will not be overwritten. Only the supplementary fields (interests, observations, tags, and data) will be updated or merged with the customer’s existing data.

Activating the Flow: It is not necessary to configure any special webhook. By sending the data from the Hotsite, the API naturally triggers the internal database__record_created or database__record_updated trigger. Just create a flow in Caramelo that is “Started when creating or updating customer,” and it will be activated automatically, allowing you to send welcome emails, notify the sales team, etc.

6. Timeline of Events

Whenever a contact is created or updated via Hotsite using this API, Caramelo AI will automatically record an event on the “Timeline” tab within this customer’s profile in the Dashboard.

• Full History (Saved Payload): Regardless of whether the vital customer fields are updated or not, all data sent in the request (both from the lead and event objects) is kept in the timeline event. This ensures your team will always be able to see exactly what the Lead typed in a given form, without compromising the official contact data in the system.
• Additional Payload: The event object sent in the request (outside the lead object) is perfect for storing specific and transient information (e.g., the URL where they converted, the specific UTMs of that session, or temporary device information).

Attention (Payload Limit): To protect system integrity, the lead submission endpoint has a strict 1MB payload size limit. Avoid sending Base64 encoded files through this route.