MindFire Docs

Appearance

Conversational AI: Voice Chat Component ​

Voice AI Agents are conversational assistants embedded in MindFire’s Personalized Landing Pages using a “voice chat component”. These landing pages are used in marketing campaigns, so the agent becomes an always-on guide that can answer questions, handle objections, and help visitors take the next step—all without leaving the page.

Agents work by combining two key inputs: your business Knowledge Base (FAQs, SOPs, product docs, policies, etc.) and the visitor’s personal/contextual information passed into the component (for example: name, email, company, or campaign data). The result is a voice experience that can speak naturally while also tailoring its guidance to the individual visitor.

This creates value on both sides: visitors get faster, more relevant answers and a more human-feeling experience, while marketers get higher-quality engagement that can boost conversion rates, reduce drop-off, and capture intent signals in real time.

Common use cases:

  • Campaign concierge: Explain the offer, answer objections, and guide visitors to the right CTA (book a call, request a demo, download, etc.).
  • Product fit + qualification: Ask a few questions, recommend the best plan/package, and route qualified visitors to sales.
  • Support-to-conversion: Provide instant help (shipping, returns, pricing, setup), then smoothly transition to purchase or scheduling.

This guide explains how to create, edit, and configure Voice AI Agents in MindFire.

Manage Voice AI Agents ​

Log in to your MindFire account at https://mindfire.app and navigate to AI Agents → Voice Agents.

  • The Voice Agents page lists all agents in your account.
  • Click Edit to open the agent configuration screen.
  • Click New Agent to create a new agent.

Create a New Agent ​

  1. Go to AI Agents → Voice Agents.
  2. Click New Agent.
  3. Enter an Agent Name.
  4. Click Create Agent.

After creation, you’ll be taken to the Edit Agent page to configure the agent.

Configure an Agent ​

1) Change the agent’s name ​

  • On the Edit Agent page, click the agent name at the top and type the new name.
  • Click the Save button at the top (or Save Changes at the bottom) of the page.

2) Test and change the agent’s voice ​

  • In the Voice card, click the play button to preview the current voice.
  • Click Change Voice to open the voice picker.
    • You can preview multiple voices before selecting one.
    • Click Select Voice on the voice you want.
  • Click Save.

3) Enter the agent’s “system prompt” (Instructions) ​

  • In Instructions, enter the guidance that defines how the agent should behave.
  • The instructions field supports up to 64,000 characters.
  • Click Save.

Recommended content for strong instructions:

  • Role/persona (who the agent is and how it should speak)
  • Primary goals (what success looks like)
  • Guardrails (what the agent should not do)
  • Escalation paths (when to hand off to a human or direct to support)
  • If using a Knowledge Base: how to reference it and when to answer from it
  • If using tools (Zapier MCP): when to use tools and what to confirm before taking actions

TIP

For more information and best practices, see OpenAI's Realtime Prompting Guide.

WARNING

While you can enter up to 64,000 characters, we recommend keeping it concise (lower than 10,000 characters) to improve performance.

4) Add authorized domain(s) (Allowed Domains) ​

Allowed domains determine where the agent widget is allowed to load.

  1. In Allowed Domains, click Add Domain.
  2. Enter the domain host and click Add Domain (or press Enter).
  3. Repeat for additional domains.

WARNING

Important rules:

  • Enter only the host, not a full URL.
    • ✅ example.com, www.example.com, *.example.com
    • ✅ localhost (for local development)
    • ❌ https://example.com (protocol not allowed)
    • ❌ example.com/path (paths not allowed)
    • ❌ example.com:3000 (ports not allowed)
  • If the agent is active, you cannot remove the last allowed domain—deactivate first.

5) Activate the agent ​

  • Use the Active / Inactive toggle (top right of the settings card).
  • The agent can only be activated when:
    • At least one allowed domain is configured, and
    • Any enabled tools configuration is valid (e.g., Zapier MCP required fields are filled).
  • The active toggle saves automatically; click Save if you changed other fields.

6) Add files (Knowledge Base) ​

The Knowledge Base lets the agent answer using your uploaded documents (FAQs, SOPs, policies, etc.).

  1. Toggle Knowledge Base on.
  2. Click Setup Knowledge Base.
  3. Choose one:
    • Create a new knowledge base, or
    • Select an existing one.
  4. Click Add File and upload documents.
  5. Click Save if you changed other fields.

INFO

Supported file types include: .pdf, .docx, .doc, .txt, .md, .rtf, .pptx, .ppt, .html, .xlsx, .xls, .csv
Maximum file size: 32 MB

Managing Knowledge Base files:

  • Click the knowledge base row to view the file list.
  • Remove a file to stop using it in that knowledge base.
  • Detach removes the knowledge base from this agent.
  • Delete Knowledge Base permanently deletes the knowledge base container

INFO

  • If a knowledge base is attached to multiple agents, you must detach it from each agent before deleting.
  • When deleting a knowledge base, files remain available for other knowledge bases.

7) Connect the agent with apps (Tools / Zapier MCP) ​

Tools allow the agent to trigger actions in connected systems via Zapier MCP.

  1. In Tools, toggle Zapier MCP on.
  2. Fill in all required fields:
    • Name (a descriptive tool name)
    • Description (what it does and when the agent should use it)
    • Zapier API Key (obtained from your Zapier account)
    • Allowed Tools (comma-separated tool identifiers)
  3. Click Save.

INFO

To learn how to set up a Zapier MCP and get a Zapier API Key, see Zapier's documentation.

WARNING

If Zapier MCP is enabled but required fields are missing, the agent cannot be saved/activated until the configuration is complete.

8) Change the agent widget look and feel (Theme) ​

In Theme, customize how the widget appears on your site:

  • Primary Color and Text Color
  • Button Text (supports {agentName} placeholder)
  • Avatar URL (optional; leave blank to use the selected voice image)
  • Show/Hide avatar toggle
  • Button Size — controls the padding, font size, and height of the start button (small, medium, large; default: medium)
  • Button Style — controls the background treatment (filled, outline, soft; default: filled)
  • Show Button Shadow — toggle the drop shadow on the filled-style button (default: on)

Use the preview button to confirm styling, then click Save.

TIP

To use the default image of the voice, leave the Avatar URL field blank and save.

9) Enable closed captions (CC) ​

When enabled, a [CC] toggle button appears in the modal controls. Visitors can click it to show a caption bar at the bottom of the screen that displays real-time transcriptions of the conversation.

  • In Theme, enable Show CC Button.
  • Click Save.

Here's how the Closed Caption button and transcript will appear on the landing page:

How captions work:

  • The caption bar appears at the bottom of the browser viewport (not inside the modal).
  • Your visitor’s speech appears immediately after they finish speaking.
  • The agent’s captions appear in real time as the agent speaks.
  • The caption bar is automatically removed when the conversation ends.

INFO

The CC button is hidden by default. Enable it only if accessibility or transcript visibility is important for your use case.

10) Configure voice activity detection (VAD) ​

Voice Activity Detection (VAD) controls how the agent detects when your visitor starts and stops speaking. Two modes are available:

ModeBest For
server_vadStandard voice detection based on audio signal levels
semantic_vadAI-powered turn detection based on the meaning of speech — better for natural, conversational exchanges

server_vad parameters:

ParameterDescription
ThresholdSensitivity to audio — higher values require louder speech to trigger
Silence DurationHow long (ms) the user must be silent before the turn ends
Prefix PaddingAudio (ms) captured before voice activity is detected
Idle TimeoutSession ends after this many milliseconds of inactivity (5,000–30,000 ms)

semantic_vad parameters:

ParameterDescription
EagernessHow quickly the agent jumps in: low, medium, high, or auto

INFO

If no VAD configuration is set, the component falls back to server_vad with a 15-second idle timeout.

WARNING

Idle Timeout is only supported in server_vad mode. Semantic VAD uses eagerness-based timing.

11) Configure noise reduction ​

Optional noise reduction filters the visitor’s microphone audio before voice activity detection runs, reducing false triggers from background noise.

In Noise Reduction, choose a mode:

ModeUse When
near_fieldVisitor is using headphones or a close microphone
far_fieldVisitor is using laptop speakers or a speakerphone

Leave this off (default) if your visitors are typically in quiet environments.

Embed the Agent Widget on Your Website ​

From the Edit Agent page:

  1. Click Embed Code.
  2. Follow the modal’s steps to:
    • Add the <voice-chat-component ...> element where you want the widget to appear
    • Add the <script ...> tag before </body>
    • Optionally set data for contextual personalization
    • Optionally set history to pass in prior conversation transcripts

WARNING

  • The widget only loads on secure sites using https://.
  • The page’s domain must be included in the agent’s Allowed Domains.

Passing contextual data ​

Use the data property to give the agent information about the current context — visitor details, product specs, listing info, account data, or anything else relevant to the conversation:

html
<script>
  const voiceComponent = document.querySelector('voice-chat-component');
  voiceComponent.data = {
    name: "Jane Smith",
    email: "jane@example.com",
    propertyAddress: "123 Main St"
  };
</script>

Passing conversation history ​

Use the history property to give the agent memory of prior sessions. Pass a JSON object or array containing previous conversation summaries or transcripts:

html
<script>
  voiceComponent.history = [
    {
      date: "2025-01-15",
      summary: "User asked about 3-bedroom listings in Austin. Was interested in properties under $500k."
    }
  ];
</script>

When present, the agent uses this history to personalize its responses and avoid repeating itself across sessions.

INFO

To track agent interactions with visitors and record the voice conversation, add the following script to the bottom of your landing page:

html
<script src="https://mfdavinci.s3.us-west-1.amazonaws.com/js/event-persistent-script.js"></script>

Troubleshooting ​

  • Widget doesn’t show up on my site
    • Confirm your page is https:// (not http://).
    • Confirm the domain host is in Allowed Domains.
    • Confirm the agent is Active.
  • Can’t activate the agent
    • Add at least one allowed domain.
    • If Zapier MCP is enabled, fill all required tool fields.
  • Can’t delete an agent
    • Agents must be Inactive before they can be deleted.