> ## Documentation Index
> Fetch the complete documentation index at: https://microstrate-1133-notifications-prefs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Embed Triggers
> Add interactive buttons, forms, and chat to your website with simple copy-paste embed code
# Embed Triggers
Embed triggers allow you to add interactive elements to your website or web application that trigger QuivaWorks flows. With simple copy-paste embed code, you can add buttons, forms, or chat interfaces that connect directly to your intelligent agents.
## Overview
Embed triggers come in three types:
Click to trigger an action or open chat
Collect data from users and submit
Interactive conversation interface
**Key Benefits:**
* ✅ No backend required - just copy and paste HTML
* ✅ Works on any website (HTML, WordPress, Squarespace, etc.)
* ✅ Customizable styling and behavior
* ✅ Secure with optional API keys
* ✅ Mobile-responsive out of the box
***
## Button Embed
The button embed renders a clickable button on your website. When clicked, it can either trigger a flow immediately or open a chat window.
### What is Button Embed?
A button embed creates an interactive button that:
* Triggers your flow when clicked
* Can make an HTTP request (for actions)
* Can open a chat window (for conversations)
* Passes data to your flow
* Shows loading states
* Displays success/error messages
### Use Cases
**Examples:**
* "Get a Quote" - Calculate and return pricing
* "Check Availability" - Query inventory
* "Generate Report" - Create document on-demand
* "Subscribe to Newsletter" - Add to mailing list
**Flow pattern:**
```
Button Click
↓
Agent processes request
↓
Return result to user
```
**Examples:**
* "Chat with Support" - Open support chat
* "Talk to Sales" - Start sales conversation
* "Get Help" - Launch help chat
* "Ask a Question" - Begin Q\&A
**Flow pattern:**
```
Button Click
↓
Open chat window
↓
User converses with agent
```
**Examples:**
* "Start Free Trial" - Collect info and provision
* "Book a Demo" - Capture details and schedule
* "Request Information" - Gather requirements
**Flow pattern:**
```
Button Click
↓
Agent collects information via chat or form
↓
Process and respond
```
### Configuration
1. Open your flow in the Hub
2. Click **Add Trigger**
3. Select **Embed Trigger**
4. Choose **Button** as the embed type
5. The trigger is added to your flow
Click on the button trigger to open settings:
**Basic Settings:**
* **Trigger Name**: Descriptive name (e.g., "Homepage Chat Button")
* **Button Text**: What displays on the button (e.g., "Get Started", "Chat Now")
* **Button Color**: Primary color (hex code or color picker)
* **Button Style**: Choose from preset styles or customize
**Action Settings:**
* **Action Type**: Choose what happens on click
* **Make HTTP Request**: Trigger flow and get response
* **Open Chat**: Launch chat interface
* **Response Mode**: Wait for completion or run in background
**Action Type determines behavior:**
* HTTP Request: For actions that return data (quotes, lookups, submissions)
* Open Chat: For conversations with agents
**Public (No Security):**
* Anyone can click the button
* Good for public websites
**API Key Protected:**
1. Toggle **Require API Key** to ON
2. Click **Generate API Key**
3. Copy and save the key
4. The key is automatically embedded in the code
API keys are for server-side use or when you want to limit access. For public buttons, leave security off.
1. Click **Get Embed Code** button
2. Copy the HTML snippet provided
3. The code includes:
* Button HTML
* JavaScript to handle clicks
* Styling (optional)
* API key (if enabled)
**Example embed code:**
```html theme={null}
```
1. Open your website's HTML
2. Paste the embed code where you want the button
3. Save and publish
4. Test the button to ensure it works
**Where to place:**
* Header/navigation
* Hero section
* Sidebar
* Footer
* Product pages
* Anywhere in your content
### Customization Options
Customize button appearance:
**Via Configuration:**
* Button text
* Primary color
* Size (small, medium, large)
* Border radius
* Icon (optional)
**Via CSS:**
```css theme={null}
#quiva-button {
background-color: #4641F2;
color: white;
padding: 12px 24px;
border-radius: 8px;
font-size: 16px;
font-weight: 600;
border: none;
cursor: pointer;
transition: all 0.2s;
}
#quiva-button:hover {
background-color: #3730d8;
transform: translateY(-2px);
box-shadow: 0 4px 12px rgba(70, 65, 242, 0.3);
}
```
Configure button behavior:
**Loading State:**
```javascript theme={null}
quiva.aiEmbed.init({
flowId: 'abc123',
onLoading: () => {
// Show spinner
button.innerHTML = ' Processing...';
button.disabled = true;
}
});
```
**Success/Error:**
```javascript theme={null}
quiva.aiEmbed.init({
flowId: 'abc123',
onSuccess: (response) => {
// Show success message
alert('Success! ' + response.message);
},
onError: (error) => {
// Show error message
alert('Error: ' + error.message);
}
});
```
Pass data with button click:
```html theme={null}
```
**Access in flow:**
```
Product ID: ${trigger.data.productId}
User Email: ${trigger.data.userEmail}
```
***
## Form Embed
The form embed creates customizable web forms that collect user input and submit it to your flow.
### What is Form Embed?
A form embed creates a data collection interface that:
* Displays form fields you configure
* Collects user input
* Validates data client-side
* Submits to your flow on submit
* Shows confirmation or error messages
* Supports various field types
### Use Cases
**Collect:**
* Name
* Email
* Phone
* Company
* Message
**Flow processes:**
* Qualify lead
* Enrich data
* Add to CRM
* Send notification
* Auto-respond
**Example:**
```
Form Submit (Name, Email, Company, Message)
↓
Lead Qualification Agent
- Company lookup
- Lead scoring
↓
Condition: Qualified?
- Yes → Add to CRM + Book meeting
- No → Add to nurture campaign
↓
Send confirmation email
```
**Collect:**
* Name
* Email
* Company
* Company size
* Use case
* Timeline
**Flow processes:**
* Automatically qualify
* Enrich with company data
* Score against ICP
* Book demo if qualified
* Notify sales team
**Collect:**
* Name
* Email
* Issue type
* Priority
* Description
* Attachments (if enabled)
**Flow processes:**
* Create support ticket
* Assign to team
* Auto-respond with ticket number
* Alert team if urgent
**Collect:**
* Satisfaction rating
* Multiple choice answers
* Open text feedback
* Contact info (optional)
**Flow processes:**
* Store responses
* Analyze sentiment
* Flag negative feedback
* Send thank you
**Collect:**
* Personal information
* Qualifications
* Documents
* References
**Flow processes:**
* Validate completeness
* Screen applicants
* Send to review queue
* Auto-respond
### Configuration
1. Open your flow in the Hub
2. Click **Add Trigger**
3. Select **Embed Trigger**
4. Choose **Form** as the embed type
5. The trigger is added to your flow
Click on the form trigger to open the form builder:
**Add Fields:**
1. Click **Add Field**
2. Choose field type:
* Text Input (single line)
* Text Area (multiple lines)
* Email
* Phone
* Number
* Dropdown/Select
* Radio Buttons
* Checkboxes
* Date
* File Upload (if enabled)
3. Configure field settings:
* **Label**: What displays above the field
* **Placeholder**: Hint text inside field
* **Required**: Toggle on/off
* **Validation**: Email format, phone format, min/max length
* **Default Value**: Pre-fill if needed
**Field naming:** Use clear, consistent field names (e.g., "email", "company\_name"). These become the variable names you'll use in your flow: `${trigger.form.email}`
**Layout Options:**
* **Single Column**: All fields stack vertically (default)
* **Two Columns**: Fields side-by-side
* **Three Columns**: Compact layout for many short fields
* **Custom Layout**: Drag and drop to arrange
**Form Settings:**
* **Form Title**: Headline above form (optional)
* **Form Description**: Subtext explaining purpose
* **Submit Button Text**: "Submit", "Send", "Get Started", etc.
* **Success Message**: Shown after submission
* **Error Message**: Shown if submission fails
**Column layouts** are responsive - they automatically stack on mobile devices.
**Response Mode:**
* **Wait for Completion**: Form shows result after flow completes
* **Run in Background**: Form shows success immediately, flow runs async
**After Submission:**
* **Show Message**: Display success message on same page
* **Redirect**: Send user to a different URL (e.g., thank you page)
* **Reset Form**: Clear fields and allow another submission
* **Keep Values**: Keep filled values (for editing)
**Example configurations:**
*Contact Form (Show Message):*
```
Success Message: "Thanks for reaching out! We'll contact you within 24 hours."
Keep Form Visible: No
```
*Demo Request (Redirect):*
```
Redirect URL: https://yoursite.com/thank-you-demo
Pass Data: Yes (include form data in URL params)
```
**Styling Options:**
**Via Configuration:**
* Primary color (buttons, focus states)
* Background color
* Border radius
* Font family
* Spacing
**Via Custom CSS:**
```css theme={null}
.quiva-form {
max-width: 600px;
margin: 0 auto;
padding: 32px;
background: white;
border-radius: 12px;
box-shadow: 0 4px 20px rgba(0,0,0,0.1);
}
.quiva-form input,
.quiva-form textarea {
width: 100%;
padding: 12px;
border: 1px solid #ddd;
border-radius: 6px;
font-size: 16px;
}
.quiva-form button[type="submit"] {
background: #4641F2;
color: white;
padding: 14px 32px;
border-radius: 8px;
font-weight: 600;
border: none;
cursor: pointer;
}
```
**Public Form (Recommended for most cases):**
* Anyone can submit
* Use CAPTCHA to prevent spam (coming soon)
* Rate limiting to prevent abuse
**API Key Protected:**
* Requires API key in request
* Good for internal forms or server-side submissions
* Not typical for public website forms
To enable API key:
1. Toggle **Require API Key** to ON
2. Generate and copy the API key
3. Key is embedded in the form code
1. Click **Get Embed Code**
2. Copy the HTML snippet
3. The code includes:
* Form HTML structure
* JavaScript for handling submission
* Validation logic
* Styling (optional)
**Example embed code:**
```html theme={null}
```
1. Paste the embed code where you want the form
2. Common placements:
* Dedicated contact page
* Homepage section
* Sidebar widget
* Modal/popup
* Footer
3. Save and publish
4. Test form submission
### Form Field Types
Single-line text field.
**Settings:**
* Label: "Full Name"
* Placeholder: "John Smith"
* Required: Yes/No
* Min/Max Length
* Pattern validation (regex)
**Use for:** Names, titles, short answers
Multi-line text field.
**Settings:**
* Label: "Message"
* Placeholder: "Tell us about your needs..."
* Rows: 4-10
* Required: Yes/No
* Max length
**Use for:** Messages, descriptions, comments
Email address with validation.
**Settings:**
* Label: "Email Address"
* Placeholder: "[you@example.com](mailto:you@example.com)"
* Required: Yes (typically)
* Auto-validates email format
**Use for:** Email collection
Phone number with formatting.
**Settings:**
* Label: "Phone Number"
* Placeholder: "(555) 123-4567"
* Format: US, International, etc.
* Required: Yes/No
**Use for:** Contact numbers
Numeric input.
**Settings:**
* Label: "Number of Employees"
* Min/Max values
* Step (1, 0.1, etc.)
* Required: Yes/No
**Use for:** Quantities, counts, measurements
Single selection from list.
**Settings:**
* Label: "Company Size"
* Options:
* "1-10 employees"
* "11-50 employees"
* "51-200 employees"
* "201-1000 employees"
* "1000+ employees"
* Required: Yes/No
* Default selection
**Use for:** Categories, options, selections
Single selection, all visible.
**Settings:**
* Label: "Preferred Contact Method"
* Options:
* Email
* Phone
* Text
* Required: Yes/No
* Default selection
**Use for:** Few options (2-5), always visible
Multiple selections.
**Settings:**
* Label: "Interested In:"
* Options:
* Product Demo
* Pricing Info
* Technical Documentation
* Free Trial
* Required: At least one/specific ones
**Use for:** Multiple selections, preferences
Date picker.
**Settings:**
* Label: "Preferred Date"
* Min/Max dates
* Default: Today/None
* Required: Yes/No
* Format: MM/DD/YYYY, DD/MM/YYYY, etc.
**Use for:** Appointments, deadlines, dates of birth
Allow file attachments.
**Settings:**
* Label: "Upload Resume"
* Allowed types: PDF, DOC, images, etc.
* Max size: 5MB, 10MB, etc.
* Multiple files: Yes/No
* Required: Yes/No
**Use for:** Documents, images, attachments
File uploads may have additional costs. Files are processed by the Upload trigger handling.
### Validation
Client-side validation happens automatically:
**Built-in Validation:**
* Required fields must be filled
* Email format checking
* Phone format checking
* Min/max length enforcement
* Number range validation
* File type and size checking
**Custom Validation:**
```javascript theme={null}
quiva.aiEmbed.renderForm({
containerId: 'form-container',
flowId: 'abc123',
onValidate: (formData) => {
// Custom validation logic
if (formData.company_size === '1-10' && formData.budget < 1000) {
return {
valid: false,
message: 'Budget must be at least $1,000 for companies under 10 employees'
};
}
return { valid: true };
}
});
```
***
## Chat Embed
The chat embed creates an interactive chat interface on your website where users can have conversations with your AI agents.
### What is Chat Embed?
A chat embed creates a messaging interface that:
* Opens as a widget or full-screen chat
* Allows back-and-forth conversation
* Shows typing indicators
* Supports rich messages
* Remembers conversation history
* Can be triggered by button or auto-open
### Use Cases
**24/7 support chat:**
* Answer product questions
* Troubleshoot issues
* Look up orders
* Process returns
* Escalate to humans when needed
**Example flow:**
```
User: "Where is my order?"
↓
Agent: "I can help! What's your order number?"
↓
User: "#12345"
↓
Agent uses Order Lookup tool
↓
Agent: "Your order shipped yesterday! Tracking: TRK123..."
```
**Lead qualification chat:**
* Ask discovery questions
* Understand needs
* Qualify leads
* Book meetings
* Answer pricing questions
**Example flow:**
```
User: "I'm interested in your Enterprise plan"
↓
Agent: "Great! Can you tell me about your company?"
↓
User: "We're a 200-person SaaS company"
↓
Agent enriches company data, qualifies
↓
Agent: "Perfect fit! Would you like to schedule a demo?"
```
**Help users navigate:**
* Product recommendations
* Feature explanations
* Configuration help
* Use case guidance
* Setup assistance
**Guide new users:**
* Welcome and introduce features
* Help with setup
* Answer questions
* Provide tutorials
* Collect feedback
### Configuration
1. Open your flow in the Hub
2. Click **Add Trigger**
3. Select **Embed Trigger**
4. Choose **Chat** as the embed type
5. The trigger is added to your flow
Click on the chat trigger to configure:
**Display Settings:**
* **Chat Widget Style**: Bubble, sidebar, full-screen
* **Position**: Bottom right, bottom left, center
* **Widget Color**: Primary brand color
* **Agent Name**: Display name (e.g., "Support Assistant")
* **Agent Avatar**: Optional image URL
* **Welcome Message**: First message shown (e.g., "Hi! How can I help?")
**Behavior Settings:**
* **Auto-open**: Open chat automatically on page load
* **Auto-open Delay**: Wait X seconds before opening
* **Minimize on Close**: Keep widget visible when closed
* **Sound Notifications**: Play sound on new messages
* **Desktop Notifications**: Browser notifications when tab inactive
**Welcome message best practices:**
* Keep it friendly and concise
* Set expectations ("I'm here to help with orders and returns")
* Prompt action ("What can I help you with today?")
**Agent Connection:**
* Select which agent handles conversations
* Agent must be in the same flow
* Agent receives chat messages as prompts
**Conversation Memory:**
* **Context Window**: How much history to maintain
* **Session Duration**: How long conversations persist
* **Clear on Close**: Reset conversation when chat closed
**Example configuration:**
```
Chat Trigger
↓
Customer Service Agent (with Smart Context enabled)
- Tools: Knowledge Base, Order Lookup, Refund Tool
- Response Mode: Wait for Completion
↓
Agent response shown in chat
```
**Via Configuration:**
* Primary color
* Secondary color
* Text color
* Background color
* Border radius
* Font family
**Via Custom CSS:**
```css theme={null}
.quiva-chat-widget {
--primary-color: #4641F2;
--text-color: #1a1a1a;
--bg-color: #ffffff;
--border-radius: 12px;
--font-family: 'Inter', sans-serif;
}
.quiva-chat-bubble {
background: var(--primary-color);
width: 60px;
height: 60px;
border-radius: 30px;
box-shadow: 0 4px 20px rgba(70, 65, 242, 0.3);
}
.quiva-chat-window {
width: 400px;
height: 600px;
border-radius: var(--border-radius);
box-shadow: 0 8px 40px rgba(0, 0, 0, 0.15);
}
```
**Public Chat (Typical):**
* Anyone can use the chat
* No authentication required
* Rate limit to prevent abuse
**Authenticated Chat:**
* Require user login
* Pass user data to agent
* Personalized experience
* Access to account information
**To pass user data:**
```javascript theme={null}
quiva.aiEmbed.renderChat({
containerId: 'chat-container',
flowId: 'abc123',
userData: {
userId: 'user_123',
email: 'user@example.com',
name: 'John Smith',
accountType: 'premium'
}
});
```
Agent can access: `${trigger.userData.email}`
Choose your embed method:
**Option 1: Chat Bubble (Recommended)**
* Floating button in corner
* Clicking opens chat window
* Unobtrusive, always available
```html theme={null}
```
**Option 2: Embedded Chat Window**
* Chat window always visible
* Part of your page layout
* Good for dedicated support pages
```html theme={null}
```
**Option 3: Button-Triggered Modal**
* Custom button on your page
* Clicking opens chat as modal overlay
* Full control over button placement and styling
```html theme={null}
```
1. Copy the embed code
2. Paste before closing `
` tag (for bubble)
3. Or paste in specific container (for inline)
4. Save and publish
5. Test the chat on your site
**Pro tip:** Add to all pages for consistent support access, or only on specific pages (product pages, checkout, support center).
### Advanced Features
### Use Cases
### Use Cases
### Use Cases