> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vaile.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# HubSpot CRM Integration

> Automatically sync leads from your chat widget to HubSpot CRM

## Overview

The HubSpot integration automatically syncs leads captured through your chat widget directly to your HubSpot CRM as contacts. When a customer submits their information, Vaile creates or updates their contact record in HubSpot with all lead details.

## What Gets Synced

When a lead is captured via your chat widget, Vaile sends the following information to HubSpot:

* **Contact Information**: Name, email, phone number
* **Lead Details**: Status, priority, source
* **Vehicle Interest**: Make, model, and budget range
* **Conversation Notes**: Customer inquiries and preferences
* **Dealership Context**: Which dealership location the lead is for

<Tip>
  Contacts are automatically set to "Lead" lifecycle stage in HubSpot, making it easy to track and nurture new prospects.
</Tip>

## Setup

### Prerequisites

Before connecting HubSpot, ensure you have:

* **HubSpot Account** with admin access
* **CRM Permissions** to create and modify contacts
* **Custom Properties** created in HubSpot (see below)

### 1. Create Custom Properties in HubSpot

HubSpot doesn't have default fields for automotive-specific data. You'll need to create custom contact properties:

<AccordionGroup>
  <Accordion title="Vehicle of Interest" icon="car">
    **Type:** Single-line text
    **Internal name:** `vehicle_of_interest`
    **Label:** Vehicle of Interest
    **Description:** The vehicle the customer is interested in
  </Accordion>

  <Accordion title="Budget Range" icon="dollar-sign">
    **Type:** Single-line text
    **Internal name:** `budget_range`
    **Label:** Budget Range
    **Description:** Customer's budget range for vehicle purchase
  </Accordion>

  <Accordion title="Lead Priority" icon="star">
    **Type:** Dropdown
    **Internal name:** `lead_priority`
    **Label:** Lead Priority
    **Options:** `high`, `medium`, `low`
    **Description:** Priority level of this lead
  </Accordion>

  <Accordion title="Lead Origin Channel" icon="wifi">
    **Type:** Single-line text
    **Internal name:** `lead_origin_channel`
    **Label:** Lead Origin Channel
    **Description:** Channel where the lead originated (e.g., chat\_widget)
  </Accordion>

  <Accordion title="Dealership Name" icon="building">
    **Type:** Single-line text
    **Internal name:** `dealership_name`
    **Label:** Dealership Name
    **Description:** Name of the dealership this lead is for
  </Accordion>

  <Accordion title="Dealership Slug" icon="tag">
    **Type:** Single-line text
    **Internal name:** `dealership_slug`
    **Label:** Dealership Slug
    **Description:** Dealership identifier
  </Accordion>
</AccordionGroup>

<Note>
  To create custom properties in HubSpot:

  1. Go to **Settings** → **Properties**
  2. Select **Contact properties**
  3. Click **Create property**
  4. Add each property listed above
</Note>

### 2. Connect HubSpot

Navigate to **Integrations** → **Events** in your Vaile dashboard.

1. In the webhook portal, find **Connectors** section
2. Locate **HubSpot CRM** connector
3. Click **Connect to HubSpot**
4. Authorize Vaile to access your HubSpot account
5. Review and approve the requested permissions

<Warning>
  You must be a HubSpot admin to authorize the integration. The integration requires permissions to create and update contacts in your CRM.
</Warning>

### 3. Select Event Types

After connecting, select which events should sync to HubSpot:

* ✅ **Lead Captured** - Recommended (syncs all captured leads)
* 🔜 **Carousel Clicked** - Coming soon
* 🔜 **Session Initiated** - Coming soon

<Tip>
  Start with "Lead Captured" only. You can add more event types later as they become available.
</Tip>

### 4. Test the Integration

1. Open your chat widget on your website
2. Fill out the lead capture form with test data
3. Submit the form
4. Check HubSpot CRM → **Contacts** for the new contact
5. Verify all fields are populated correctly

## How It Works

### Lead Capture Flow

```
Customer submits lead form
         ↓
Vaile creates contact & lead
         ↓
Event sent to webhook system
         ↓
HubSpot connector transforms data
         ↓
Contact created/updated in HubSpot
```

### Data Mapping

Vaile automatically maps your lead data to HubSpot fields:

| Vaile Field      | HubSpot Property             |
| ---------------- | ---------------------------- |
| Contact Name     | First Name + Last Name       |
| Email            | Email                        |
| Phone            | Phone                        |
| Vehicle Interest | Vehicle of Interest (custom) |
| Budget Range     | Budget Range (custom)        |
| Lead Status      | Lead Status                  |
| Priority         | Lead Priority (custom)       |
| Notes            | Notes - Last Contacted       |
| Origin           | Lead Source                  |

### Lifecycle Stage

All synced contacts are automatically set to **"Lead"** lifecycle stage, making them easy to identify and nurture in your HubSpot workflows.

## Managing the Integration

### Viewing Sync Status

Check webhook delivery status in the Events dashboard:

1. Go to **Integrations** → **Events**
2. Click **Logs** tab
3. Filter by event type: `lead.captured.v1`
4. View delivery status for each lead

<Info>
  Successful deliveries show a **200 OK** status. Failed deliveries will show error details and retry attempts.
</Info>

### Automatic Retries

If HubSpot is temporarily unavailable or returns an error, the webhook system automatically retries delivery:

* **1st retry:** Immediately
* **2nd retry:** 5 seconds
* **3rd retry:** 5 minutes
* **4th retry:** 30 minutes
* **5th retry:** 2 hours
* **Continues for:** Up to 3 days

### Disconnecting HubSpot

To disconnect the integration:

1. Go to **Integrations** → **Events**
2. Click **Connectors**
3. Find **HubSpot CRM**
4. Click **Disconnect**
5. Confirm disconnection

<Warning>
  After disconnecting, new leads will no longer sync to HubSpot. Existing contacts in HubSpot remain unchanged.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Contact not appearing in HubSpot" icon="circle-xmark">
    **Check:**

    * HubSpot connection is active (green status in Events dashboard)
    * Required permissions are granted (check OAuth settings)
    * Custom properties are created in HubSpot
    * No duplicate email exists (HubSpot may update instead of create)

    **Solution:**

    * Review webhook logs for error messages
    * Re-authorize HubSpot connection
    * Verify custom properties exist
  </Accordion>

  <Accordion title="Missing fields in HubSpot contact" icon="database">
    **Cause:** Custom properties not created in HubSpot

    **Solution:**

    * Create the missing custom properties (see Setup step 1)
    * New leads will include all fields
    * Existing contacts won't be updated automatically
  </Accordion>

  <Accordion title="Duplicate contacts being created" icon="copy">
    **Cause:** HubSpot uses email as unique identifier

    **Behavior:**

    * If email exists: HubSpot updates the existing contact
    * If email is new: HubSpot creates a new contact
    * If email is blank: May create duplicate contacts

    **Best Practice:**

    * Always capture email addresses in lead forms
    * Use HubSpot's duplicate management tools
  </Accordion>

  <Accordion title="Integration disconnected unexpectedly" icon="plug">
    **Possible causes:**

    * OAuth token expired
    * HubSpot account permissions changed
    * Admin revoked access

    **Solution:**

    * Re-connect HubSpot via Events dashboard
    * Verify you have admin permissions
    * Check HubSpot connected apps settings
  </Accordion>
</AccordionGroup>

## Security & Privacy

### Data Transmission

* All data is transmitted securely via HTTPS
* Webhooks are signed with HMAC signatures
* HubSpot connection uses OAuth 2.0 authentication

### Permissions Required

The integration requests these HubSpot permissions:

* **Create/Update Contacts** - To sync lead information
* **Read Contacts** - To check for duplicates
* **Read Contact Properties** - To validate custom fields

<Note>
  Vaile never stores your HubSpot credentials. Authentication is handled securely via OAuth, and tokens are encrypted at rest.
</Note>

### Compliance

* **GDPR**: Customers can request data deletion via your HubSpot account
* **Data Retention**: Follow your HubSpot data retention policies
* **Consent**: Ensure lead capture forms include appropriate consent language

## Advanced: Creating Deals

By default, the integration creates contacts only. If you want to also create deals in HubSpot:

<Steps>
  <Step title="Contact Vaile Support">
    Reach out to [support@vaile.ai](mailto:support@vaile.ai) to request the deal creation feature
  </Step>

  <Step title="Provide Deal Settings">
    Specify your deal pipeline, stage, and default values
  </Step>

  <Step title="Custom Transformation">
    Vaile will configure a custom transformation for your account
  </Step>

  <Step title="Test & Deploy">
    Test with sample leads before enabling for production
  </Step>
</Steps>

<Tip>
  Most dealerships start with contacts only and use HubSpot workflows to create deals automatically based on their sales process.
</Tip>

## Best Practices

1. **Set Up Workflows** - Create HubSpot workflows to automatically assign leads to sales reps
2. **Enable Notifications** - Configure HubSpot to notify your team of new leads
3. **Monitor Sync Status** - Check webhook logs weekly to ensure consistent delivery
4. **Use Lead Scoring** - Leverage HubSpot's lead scoring with the priority field
5. **Create Follow-up Tasks** - Use HubSpot automation to schedule follow-ups

## Need Help?

If you encounter issues or need assistance:

* **Email**: [support@vaile.ai](mailto:support@vaile.ai)
* **Dashboard**: Use the chat widget in your Vaile dashboard
* **Documentation**: Check webhook logs for detailed error messages

Our support team typically responds within 24 hours on business days.