HubSpot CRM

The HubSpot CRM Integration establishes a bidirectional, secure, and real-time data bridge between Supsis—where omnichannel customer communication and live support are managed—and HubSpot CRM, where corporate marketing, sales pipeline, and customer success operations take place. Thanks to this integration, new customers arriving via WhatsApp, Instagram, Live Chat (WebChat), or other communication channels can be automatically created as contacts and deals in HubSpot according to configured business rules and transfer modes.

The integration connects directly using an Access Token without requiring complex OAuth authorization popups. Depending on your business needs, you can choose between a rapid setup via Service Key or a full-featured Private App method supporting real-time automation events (webhooks). Live support agents can inspect the customer's HubSpot contacts, open deals, associated companies, and activity history directly within the chat interface without switching tabs, as well as append new notes and tasks. In addition, real-time events in HubSpot (such as deal stage changes or contact updates) can instantly trigger Supsis automations.

1- HubSpot CRM Integration Overview

1.a – What is HubSpot CRM and the Purpose of the Integration

HubSpot is a cloud-based CRM platform that enables sales, marketing, customer support, and operations teams to manage contacts, deals, companies, tickets, and engagement activities within a unified database.

Organizations typically run their multi-channel customer conversations through Supsis while tracking their sales pipeline and customer lifecycle inside HubSpot. Without integration, agents are forced to constantly switch back and forth between messaging windows and CRM tabs, manually copy-pasting customer details and logging every new conversation. This leads to operational friction, data discrepancies, and lost sales opportunities.

The Supsis HubSpot CRM Integration eliminates this disconnect through a bidirectional automated flow:

1. Supsis → HubSpot (Data Forwarding): When a new customer reaches out via WhatsApp, Instagram, or WebChat, phone and email deduplication checks are executed. If no matching record exists, Supsis automatically creates a Contact (and optionally an associated Deal) in HubSpot.
2. HubSpot → Supsis (In-Chat CRM Widget): In the live support interface, the right-hand customer profile panel displays a dedicated HubSpot tab. Contact details, open/closed deals, associated companies, and tasks are displayed in real time. Agents can review the HubSpot profile and add notes to deals without leaving the conversation.
3. HubSpot Events → Supsis Automations (Webhooks): Powered by Private App webhooks, when a deal stage changes in HubSpot (e.g., to "Closed Won"), a contact is deleted, or a company is updated, Supsis automations are triggered immediately to send notifications via WhatsApp, SMS, or email.

1.b – Two-Tier Configuration Architecture

The HubSpot CRM integration operates on a two-tier structural model:

1.c – Glossary of Terms

The key concepts utilized throughout the HubSpot integration interface and documentation are detailed below:

2- Connection Methods: Service Key vs. Private App

The Supsis HubSpot CRM integration does not use a third-party OAuth popup. Users simply copy their Access Token from HubSpot and paste it into Supsis. You can choose between two methods based on your functional requirements:

3- Required Scopes

Regardless of which connection method you use, the Access Token must include all the following scopes. If any scope is missing, Supsis will reject the connection and display the name of the missing scope in the error message:

• crm.objects.contacts.read – Permission to read contacts
• crm.objects.contacts.write – Permission to create and update contacts
• crm.objects.deals.read – Permission to read deals
• crm.objects.deals.write – Permission to create and update deals
• crm.objects.owners.read – Permission to read HubSpot owners/users
• crm.objects.companies.read – Permission to read associated company data
• crm.schemas.contacts.read – Permission to inspect contact property schemas
• crm.schemas.deals.read – Permission to inspect deal property schemas
• crm.schemas.companies.read – Permission to inspect company property schemas

4- Setup Steps

4.a – Accessing the Integration Card

1. Log in to the Supsis administration panel and navigate to Integrations in the left navigation menu.
2. Under the CRM section, locate the HubSpot CRM card featuring the green ● FREE badge.
3. Click the card to open the HubSpot CRM Channels list.

4.b – Method 1: Full Setup via Private App (Recommended)

Follow these steps to enable full CRM management along with automation triggers and webhook notifications:

1. Navigate to Private Apps in HubSpot: In your HubSpot account, click the gear icon (Settings) in the top right. In the left-hand sidebar, go to Integrations → Private Apps.

2. Initialize App Creation: Click Create legacy app (or Create a private app) and select Private in the modal.

3. Define Basic Info: Set the application name to Supsis AI Integration. Optionally, add a brief description and upload the Supsis logo.

4. Add Scopes: Switch to the Scopes tab. Search for and check all Contact, Deal, Owner, Company, and Schema scopes listed in Section 3. Confirm all selections in the Summary sidebar.

5. Generate the App and Retrieve Credentials: Click Create app in the top right and confirm with Continue creating.

6. Copy the generated Access Token (pat-na1-...).

7. Switch to the Auth tab and copy the Client Secret for webhook signature verification.

8. Connect in Supsis: Return to the Add Channel modal in Supsis. Enter a channel name, paste the Access Token and Client Secret, and click Connect.

4.c – Method 2: Quick Setup via Service Key

If you only need in-chat contact inspection and automatic contact forwarding without webhooks, you can connect in seconds using a Service Key:

1. Navigate to Service Keys: In HubSpot, go to Settings → Integrations → Service Keys (or Development → Keys → Service Keys in some accounts) (See: Integrations Settings Screen above).
2. Create a Key: Click Create Service Key and provide a descriptive name.
3. Select Scopes: Select the required read/write scopes listed in Section 3 and verify the summary.
4. Copy the Token: Copy the generated Access Token.
5. Add Channel in Supsis: In Supsis, open the Add Channel modal, paste the token, and click Connect.

5- Forwarding Data from Channels (CRM Forward)

5.a – Enabling Forwarding

Once the HubSpot channel is established, contact forwarding must be enabled on your source messaging channels (e.g., WhatsApp or WebChat):

1. In Supsis, go to Settings > Channels or open the channel details from the left menu (e.g., WhatsApp Channels → Channel Details).
2. Open the CRM / HubSpot tab.
3. Toggle on Forward new contacts to HubSpot.

5.b – Forwarding Modes and Parameters

Configure the following parameters in the forwarding tab:

1. Forward Mode:
2. Contact (Contact Only): Creates only a contact record in HubSpot for each new customer.
3. Contact + Deal: Creates both a contact and a new sales deal, automatically linking them together (Association). In this mode, selecting a Pipeline and Deal Stage is mandatory.
4. Lifecycle Stage: HubSpot CRM does not have a separate "Lead" object in standard configurations. In Supsis, the lead state is managed through the contact's Lifecycle Stage. Available values:
5. lead (Default)
6. subscriber
7. marketingqualifiedlead (MQL)
8. salesqualifiedlead (SQL)
9. opportunity
10. customer
11. evangelist
12. other
13. Phone Format:
14. E.164 (with +): +905xxxxxxxxx
15. Without +: 905xxxxxxxxx (HubSpot searches phone, mobilephone, and computed normalized phone fields simultaneously).
16. Default Owner: Specifies the default HubSpot user assigned to newly created records. If left blank, HubSpot's portal default applies.
17. Field Mapping: Map Supsis contact and session variables to HubSpot custom properties using templates (e.g., {{contact.phone}}, {{contact.name}}).

5.c – Deduplication Logic (Dedup)

To prevent duplicate contact records from polluting your CRM database:

6- HubSpot Widget in Live Chat

When the HubSpot integration is active, agents gain access to a dedicated CRM panel directly inside the live chat interface:

1. Access: In the chat view, click the HubSpot tab in the right-side customer profile pane.
2. Contacts Tab: Shows customer name, title, email, phone, lifecycle stage, and assigned owner. The "View in HubSpot" button opens the record directly in HubSpot with a single click.
3. Deals Tab: Lists all active and closed deals associated with the contact, showing stage, amount, and close date. Agents can append notes directly to deals from this panel.
4. Companies Tab: Displays associated organization details in read-only mode.
5. Activities Tab: Displays tasks and past communication touchpoints tied to the contact.

7- User Mapping and Visibility

7.a – User Mapping

Under the User mapping tab of your HubSpot channel, match Supsis support agents with HubSpot Owners via their email addresses:

• When an agent reassigns record ownership in the chat widget, this mapping table is referenced.
• When records are assigned in HubSpot, notifications can be routed to the corresponding Supsis agent.

7.b – Visibility

Control which departments and agent teams can access the HubSpot CRM channel and inspect CRM widget data using the Visibility tab.

8- Webhook Setup and Automation Triggers

Accounts connected via Private App can receive real-time webhook events from HubSpot to trigger Supsis automations.

8.a – Webhook Configuration Steps

1. In Supsis, go to Integrations > HubSpot CRM > Channel Detail > Webhooks.
2. Copy the dedicated Target URL. (Format: https://socket.supsis.live/webhook/hubspot/{siteId}/{channelId})
3. In your HubSpot Private App settings, open the Webhooks tab and paste the Target URL.
4. Under Event subscriptions, subscribe to the recommended events:
5. contact.creation, contact.propertyChange, contact.deletion
6. deal.creation, deal.propertyChange, deal.deletion
7. company.creation, company.propertyChange
8. ticket.creation
9. Save the webhook settings in HubSpot.
10. Copy the Client Secret from the Private App Auth tab, paste it into the Detail tab of your Supsis channel, and save.

8.b – Automation Trigger Events

Under the HubSpot module in the Supsis Automation Designer, 10 distinct events are available:

9- Supsis Automation Designer & Action Blocks

The Automation Flow Designer provides 4 dedicated blocks under the orange HubSpot Actions palette:

1. Find HubSpot Contact by Phone: Searches for a contact using their phone number and returns the HubSpot Contact ID for subsequent blocks.
2. Create HubSpot Record: Creates a Contact, Deal, Note, Task, or Ticket object with dynamic property values populated from HubSpot schemas.
3. Update HubSpot Record: Updates properties on an existing record (including reassigning owners).
4. Add Note to HubSpot: Appends a rich-text note to the timeline of an associated contact or deal.

9.a – JavaScript SDK and Code Blocks

Custom programmatic workflows can be executed within Chatbot and Automation JavaScript code blocks via the supsis.hubspot object:

// Example: Find contact in HubSpot by phone number
const contact = await supsis.hubspot.findContactByPhone("+15551234567");

if (contact) {
  // Create a new Deal associated with the contact
  await supsis.hubspot.createRecord("deals", {
    dealname: "WhatsApp Inquiry Lead",
    amount: "15000",
    dealstage: "appointmentscheduled",
    pipeline: "default"
  }, { associateContactId: contact.id });

  // Append an activity note
  await supsis.hubspot.addNote(contact.id, "Customer requested a live demo via WhatsApp.");
}

10- Troubleshooting & FAQ

10.a – "Channel card displays 'Reconnection required' warning"

• The Access Token in HubSpot may have been rotated, deleted, or the user who created it may have lost developer permissions.
• Resolution: Generate a new Access Token in HubSpot, navigate to HubSpot CRM > Channel Detail > Detail in Supsis, paste the token, and save.

10.b – "Duplicate contacts are created in HubSpot"

• The phone number formatting in the source channel might not match the format stored in HubSpot (e.g., numbers formatted with + vs without +).
• Resolution: In WhatsApp channel settings, align the Phone Format setting with your HubSpot database standard (E.164 with + or Without +).

10.c – "Automation does not trigger when Deal stage changes"

• The deal.propertyChange subscription may be missing from your Private App webhooks.
• Resolution: In HubSpot Private App → Webhooks, ensure deal.propertyChange is active and verify that the Client Secret is entered in Supsis channel details.

10.d – "Rate Limit (429 Too Many Requests) errors"

• The HubSpot Search API enforces a limit of approximately 4–5 requests per second. Burst requests during bulk messaging campaigns can exceed this threshold.
• Resolution: Introduce short delay blocks between sequential searches in automation flows or leverage Contact ID caching.