HubSpot Integration

The AssistLoop HubSpot integration automatically syncs leads from your chat conversations directly to your HubSpot CRM. When customers submit lead forms through your AssistLoop chat interface, their information is instantly created or updated as contacts in HubSpot, eliminating manual data entry and ensuring your CRM stays up-to-date.

Overview

With the AssistLoop HubSpot integration, you can:

• Automatically create contacts in HubSpot when leads submit forms through your chat
• Update existing contacts if a lead with the same email already exists
• Map form fields to HubSpot contact properties automatically
• Sync lead data in real-time via asynchronous background processing
• Handle OAuth authentication securely with automatic token refresh

This integration uses HubSpot's OAuth 2.0 API and follows HubSpot's best practices for secure, reliable data synchronization.

How It Works

Integration Flow

1. Customer submits a lead form through your AssistLoop chat interface
2. AssistLoop processes the form and stores the lead data
3. HubSpot sync job is triggered automatically in the background
4. Contact is created or updated in HubSpot based on email address
5. Integration status is tracked for monitoring and troubleshooting

Key Features

• Automatic Sync: No manual intervention required - leads sync automatically
• Duplicate Handling: Checks for existing contacts by email before creating new ones
• Field Mapping: Intelligently maps common form fields to HubSpot properties
• Error Handling: Robust error handling with retry logic for transient failures
• Token Management: Automatic OAuth token refresh ensures continuous operation

Installation & Setup

Prerequisites

• An active AssistLoop account
• A HubSpot account (Free, Starter, Professional, or Enterprise)
• Admin access to your HubSpot account to install the integration

Step 1: Install the Integration in HubSpot

1. Navigate to the HubSpot App Marketplace
2. Search for "AssistLoop" or navigate to the AssistLoop app listing
3. Click "Install app" or "Get app"
4. Review the required permissions and click "Install"
5. You'll be redirected to authorize the connection

Step 2: Authorize the Connection

1. You'll be redirected to AssistLoop's integrations page
2. Find HubSpot in the list of available integrations
3. Click "Connect" next to HubSpot
4. You'll be redirected to HubSpot's authorization page
5. Review the requested permissions:
   • Read contacts: View existing contacts in HubSpot
   • Write contacts: Create and update contacts in HubSpot
6. Click "Authorize" or "Allow" in HubSpot to approve the connection
7. You'll be redirected back to AssistLoop's integrations page
8. HubSpot will now show as "Connected" with a green status indicator

Step 3: Enable Lead Collection

1. Ensure the "Collect Lead" action is enabled for your agent
2. Configure when the action should be triggered by defining the tool's description or conditions
   • For example: "Use this tool when the customer tries to reach out to the sales team"
   • The action will be triggered based on customer intent matching your configuration
3. When triggered, the lead form will be shown to the customer during the conversation
4. Any leads collected through the form will automatically sync to HubSpot
5. The integration is now fully configured and ready to sync leads

Field Mapping

The integration automatically maps form fields to HubSpot contact properties. Currently, the following fields are supported:

Supported Field Mappings

Name Field Handling

If your form uses a single name field instead of separate first_name and last_name fields, the integration will automatically split it:

• Single word (e.g., "John"): Mapped to firstname only
• Multiple words (e.g., "John Doe"): First word becomes firstname, remaining words become lastname

Example:

• Form field name = "John Doe" → HubSpot: firstname = "John", lastname = "Doe"
• Form field name = "John" → HubSpot: firstname = "John", lastname = (empty)

OAuth Authentication

The integration uses OAuth 2.0 for secure authentication with HubSpot. This ensures your HubSpot credentials are never exposed or stored in plain text.

Authentication Flow

1. Authorization Request: When you install the app, AssistLoop requests authorization from HubSpot
2. User Approval: You approve the requested permissions in HubSpot
3. Token Exchange: AssistLoop exchanges the authorization code for access and refresh tokens
4. Token Storage: Tokens are encrypted and stored securely
5. Automatic Refresh: Access tokens expire after 30 minutes; refresh tokens are used automatically to obtain new access tokens

Required Scopes

The integration requires the following HubSpot OAuth scopes:

• crm.objects.contacts.read - Read existing contacts to check for duplicates
• crm.objects.contacts.write - Create and update contacts

These scopes are automatically requested during installation and cannot be modified.

Token Management

• Access Tokens: Valid for 30 minutes (1,800 seconds)
• Refresh Tokens: Long-lived tokens used to obtain new access tokens
• Automatic Refresh: Tokens are automatically refreshed when they expire
• Security: All tokens are encrypted at rest and transmitted over HTTPS only

Technical Details

API Endpoints

The integration uses the following HubSpot API endpoints:

Rate Limits

HubSpot enforces rate limits on API requests:

• 100 requests per 10 seconds per HubSpot account
• The integration includes automatic rate limit handling and retry logic
• Requests are queued and processed asynchronously to prevent blocking

Data Processing

• Asynchronous Processing: Lead sync happens in the background via queue jobs
• Retry Logic: Failed syncs are automatically retried up to 3 times with exponential backoff
• Error Handling: Validation errors (e.g., invalid properties) are handled gracefully and don't trigger retries

Troubleshooting

Integration Not Syncing Leads

Check Connection Status

1. Go to your AssistLoop dashboard
2. Navigate to your agent's integrations settings
3. Verify HubSpot shows as "Connected"

Check Lead Form Submission

1. Ensure the "Collect Lead" action is enabled for your agent
2. Verify that the action's tool description or trigger conditions are properly configured
3. The lead form will be shown when the AI determines customer intent matches your configured conditions
4. Test the lead collection flow by triggering the action through customer conversation

Contacts Not Appearing in HubSpot

Check HubSpot Property Permissions

• Verify that your HubSpot account has permission to create contacts
• Ensure required properties (like email) are not restricted

OAuth Token Errors

Token Expired

• The integration automatically refreshes tokens when they expire
• If you see token expiration errors, the integration will retry with a refreshed token

Re-authorization Required

• If tokens cannot be refreshed, you may need to reconnect the integration
• Disconnect and reconnect the integration in your AssistLoop dashboard

API Reference

OAuth Endpoints

The integration uses standard OAuth 2.0 endpoints for authentication:

Authorization URL

https://app.hubspot.com/oauth/authorize

Token URL

https://api.hubapi.com/oauth/v1/token

Required Parameters

• client_id: Your HubSpot app's client ID
• client_secret: Your HubSpot app's client secret
• redirect_uri: The callback URL registered in HubSpot
• grant_type: authorization_code (for initial auth) or refresh_token (for token refresh)

Contact Creation

Endpoint: POST /crm/v3/objects/contacts

Request Body:

{
  "properties": {
    "email": "[email protected]",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+1234567890",
    "company": "Example Corp"
  }
}

Response:

{
  "id": "12345678",
  "properties": {
    "email": "[email protected]",
    "firstname": "John",
    "lastname": "Doe",
    "phone": "+1234567890",
    "company": "Example Corp"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Contact Search

Endpoint: POST /crm/v3/objects/contacts/search

Request Body:

{
  "filterGroups": [
    {
      "filters": [
        {
          "propertyName": "email",
          "operator": "EQ",
          "value": "[email protected]"
        }
      ]
    }
  ],
  "properties": ["email", "firstname", "lastname", "phone"]
}

Changelog

Version 1.0.0 (Current)

• Initial release
• Automatic lead sync to HubSpot
• OAuth 2.0 authentication
• Automatic field mapping
• Duplicate contact handling
• Error handling and retry logic
• Custom property support

Last Updated: October 2025