Salesforce Integration Guide

Architecture Overview

HoverBot conversation
  → lead.qualified event fires
  → webhook POST to your middleware or Salesforce directly
  → Lead/Contact upsert via Salesforce REST API
  → Optional: Opportunity creation on high-score leads

Authentication: OAuth 2.0 client credentials flow
Retry: Exponential backoff with 3 retries on transient failures
Deduplication: Email-based upsert key prevents duplicate records

Implementation Steps

1. Create a Salesforce Connected App

   Navigate to Setup → App Manager → New Connected App. Enable OAuth with the api scope. Copy the consumer key and secret.

2. Configure webhook endpoint in HoverBot

   In your HoverBot workspace, go to Integrations → Add Webhook. Set the trigger to lead.qualified and point the URL to your middleware or a Salesforce-compatible endpoint.

3. Map HoverBot fields to Salesforce objects

   Map conversation data to Salesforce fields: email → Email, phone → Phone, qualificationScore → custom Lead_Score__c field, intent → Lead Source or custom field, conversation URL → Description.

4. Configure upsert logic

   Use email as the external ID for upsert operations. This ensures returning visitors update existing records rather than creating duplicates.

5. Set up Opportunity creation rules

   For leads above your score threshold, create an Opportunity with stage "Qualification" and associate it with the Contact record. Include conversation context in the Opportunity description.

6. Enable retry and error handling

   Configure exponential backoff for Salesforce API rate limits and transient errors. Log failed deliveries for manual review.

Example Payload

{
  "event": "lead.qualified",
  "timestamp": "2026-04-05T14:30:00Z",
  "lead": {
    "email": "prospect@company.com",
    "phone": "+1-555-0142",
    "firstName": "Alex",
    "lastName": "Chen",
    "qualificationScore": 87,
    "intent": "enterprise_demo",
    "source": "website_widget",
    "conversationUrl": "https://app.hoverbot.ai/conversations/sf-abc123",
    "metadata": {
      "companySize": "200-500",
      "industry": "Technology",
      "budget": "50k-100k"
    }
  }
}

Field Mapping Reference

Validation Checklist

• Lead is created or updated (upsert on email works correctly)
• Qualification score and intent map to the expected Salesforce fields
• Conversation URL is accessible and provides handoff context for sales reps
• High-score leads trigger Opportunity creation with correct stage
• Failed webhook deliveries are logged and retried with backoff
• Duplicate handling works for returning visitors across multiple conversations