Skip to content

BRD-008 UTM HubSpot Integration

BRD – Pass URL & UTM Journey Data to HubSpot

Product: MachineAvatars
Feature: HubSpot Integration for Session URL Journey Tracking

1. Background & Problem Statement

  • MachineAvatars captures a user’s complete URL journey (including UTMs) during a chatbot session (as defined in Topic-2).
  • Currently, this journey data remains internal to MachineAvatars.
  • Customers using HubSpot need this data synced to their CRM for lead attribution, context, and analytics.

2. Objective

Automatically pass the complete URL + UTM journey captured during a chatbot session to HubSpot, mapped to the corresponding lead or contact.

3. Scope

In-Scope

  • Capture URL and UTM parameters via the MachineAvatars SDK deployed on customer websites.
  • Map the URL journey to a unique chatbot Session ID.
  • Send the journey payload to HubSpot when a lead is created or updated.
  • Support standard UTM parameters (source, medium, campaign, term, content).

Out-of-Scope

  • Bi-directional sync with HubSpot.
  • Custom CRM field creation beyond required mappings.
  • Advanced attribution modeling inside HubSpot.

4. User Personas

  • End User: Browses the website and interacts with the chatbot.
  • Customer Admin: Connects HubSpot and expects accurate lead data.
  • Sales / Marketing Teams: Consume journey data inside HubSpot.

5. High-Level User Flow

  1. Customer embeds the MachineAvatars SDK on their website.
  2. User lands on the website with UTMs (if any).
  3. SDK captures entry URL and UTMs.
  4. User navigates across pages during chatbot session.
  5. URL journey is stored and mapped to Session ID.
  6. User submits a lead form via chatbot.
  7. System sends URL + UTM journey payload to HubSpot.
  8. Journey data is associated with the lead/contact.

6. Functional Requirements

  • FR-1: SDK shall capture entry URL and all UTM parameters at session start.
  • FR-2: SDK shall capture all internal URL changes during the chatbot session.
  • FR-3: System shall store the ordered URL journey mapped to a Session ID.
  • FR-4: On lead creation or update, system shall push the journey payload to HubSpot.
  • FR-5: URL journey data shall be associated with the correct HubSpot lead/contact.

7. Constraints & Non-Functional Requirements

  • Integration must comply with HubSpot API limits and authentication.
  • Payload size must be optimized to avoid API failures.
  • SDK must not impact website performance.

8. Acceptance Criteria

  • Given the SDK is installed, when a user starts a chatbot session, then URL and UTMs are captured.
  • Given a user navigates across pages, when the session is active, then the full journey is recorded.
  • Given a lead is submitted, when integration is enabled, then journey data is sent to HubSpot.
  • Given a HubSpot contact exists, when viewed, then URL + UTM journey data is accessible.