HubSpot integration

Overview

The HubSpot integration sends the leads your chat captures to your HubSpot CRM. As contact details are captured, AtomicX Chat creates or updates a HubSpot contact, matched by email address (or by phone number if no email was collected). Optional company information from an AI follow-up form is sent as the contact’s Company Name. When a conversation ends, it can also attach the full chat transcript as a note, and open a deal or a ticket in the pipeline you choose.

Before you start, you need:

• A plan that includes integrations. If Integrations isn't in the left menu, see Plans and subscription.
• The Owner or Admin role in AtomicX Chat.
• A HubSpot super admin (or someone who can create apps in your HubSpot account).

Setup takes about 15 minutes.

Steps

Step 1: Create a HubSpot app and copy its access token

AtomicX Chat connects with a static access token from an app installed in your HubSpot account. Choose one of the two options below. Option A is the recommended option; Option B is quicker if your HubSpot account still offers legacy private apps.

Both options need these scopes:

• crm.objects.contacts.read
• crm.objects.contacts.write
• crm.objects.deals.write (only if you'll create deals)
• crm.objects.tickets.write (only if you'll create tickets)

Transcript notes use the contacts scopes, so they need nothing extra.

Option A: Project app (recommended)

You need Node.js installed on your computer.

1. Install the HubSpot CLI and sign in. The second command opens HubSpot and asks you for a personal access key:

   npm install -g @hubspot/cli
   hs account auth
   

2. Create a private project that uses static auth. Name it atomicx-chat when asked:

   hs project create --distribution private --auth static --project-base app
   

3. Open src/app/app-hsmeta.json and set the scopes:

   "auth": {
     "type": "static",
     "requiredScopes": [
       "crm.objects.contacts.read",
       "crm.objects.contacts.write",
       "crm.objects.deals.write",
       "crm.objects.tickets.write"
     ]
   }
   

4. Upload the project: hs project upload
5. In HubSpot, go to Development → Projects, open your project, and under Project components click the app. On the Distribution tab, click Install now for your account.
6. On the same Distribution tab, click Show next to the access token and copy it.

Option B: Legacy private app (no CLI)

1. In HubSpot, click the Settings (gear) icon and go to Integrations → Private Apps. On newer accounts this is under Development → Legacy Apps.
2. Click Create a private app and name it AtomicX Chat.
3. On the Scopes tab, tick the scopes listed above.
4. Click Create app, then Show token, and copy the token. It starts with pat-.

Step 2: Find your Portal ID

Your Portal ID (also called Hub ID) is the number in any HubSpot URL, for example https://app.hubspot.com/contacts/12345678/.... You can also find it under Settings → Account Management → Account Defaults.

Step 3: Connect AtomicX Chat to HubSpot

1. In AtomicX Chat, go to Integrations → Integrations and click Connect on the HubSpot card.
2. Paste the token into Private App access token, and enter your Portal ID.
3. Click Test connection and wait for the green Connected badge. If you see Failed, see Troubleshooting.

Step 4: Choose what to sync

Under What to sync, tick the options you want:

• Create contacts (upsert by email): required. Nothing else syncs without it, because notes, deals and tickets are all linked to the contact.
• Attach transcript as a Note on completion: adds the full chat to the contact's timeline.
• Create deals on completion: opens a deal. Fill in Pipeline ID and Deal stage ID (see Step 5).
• Create tickets on completion: opens a ticket. Fill in Ticket pipeline ID and Ticket stage ID (see Step 5).

Click Save. You'll see Saved. under the button.

Step 5: Find pipeline and stage IDs (deals and tickets only)

• Deals: In HubSpot, go to Settings → Objects → Deals → Pipelines. Hover over a pipeline and click Copy pipeline ID. Open the pipeline, hover over a stage, and use the code icon to copy its internal ID. The default deal pipeline is default and its first stage is appointmentscheduled.
• Tickets: Go to Settings → Objects → Tickets → Pipelines and do the same. The default ticket pipeline is 0 and its first stage (New) is 1.

Paste the IDs into AtomicX Chat and click Save again.

Step 6: Make your workflow collect contact details

The contact is created or updated as soon as the visitor gives an email address or phone number, and every detail they give afterwards (for example a phone number after the email) updates the same contact. Notes, deals and tickets are added when the conversation ends.

1. Go to Workflows and open the workflow your chat widget uses.
2. Add a Name input and an Email input node (and a Phone input node if you want phone numbers) near the start of the flow, before your AI or question nodes.
3. Make sure every path ends with an End conversation node. Conversations that close because of inactivity also count as ended.
4. Save the workflow.

See Workflow node types for details on each node.

Step 7 (optional): Map extra answers to HubSpot properties

To copy other answers from the chat, such as a budget or move-in date, into HubSpot:

1. In HubSpot, go to Settings → Properties and note the property's internal name (for example budget_range). Create the property first if it doesn't exist.
2. In AtomicX Chat, under Contact property mappings, click + Add mapping.
3. In Conversation data key, enter the key your workflow saves the answer under. In HubSpot property, enter the internal name.
4. Click Save.

Deals have their own Deal property mappings table under Deal settings, which works the same way.

Step 8: Test it

1. Open Chat test and run through a conversation. Give a real-looking name and email address, and finish the conversation.
2. In HubSpot, open CRM → Contacts. The new contact should appear within a minute (see Where leads appear in HubSpot).
3. If you turned on notes, deals or tickets, open the contact and check its timeline and associated records.

See Test your chat.

Where leads appear in HubSpot

AtomicX Chat creates contacts through the HubSpot API. They don't go through a HubSpot form, so they never appear under Marketing → Forms or in form submission reports.

• Find them in CRM → Contacts. Sort by Create date, or search for the visitor's email address.
• Their Original source is usually Offline sources, because they were created by an integration rather than a tracked website visit.
• AtomicX Chat doesn't create records in HubSpot's separate Leads workspace (Sales → Leads). If your team works from there, create the lead from the contact, or use a HubSpot workflow that creates one for new contacts.
• A returning visitor updates their existing contact instead of creating a new one, so check the contact's Last modified date too.
• With Remember returning visitors turned on, a visitor who uses their saved details updates the same contact even if they give a new email. If they choose Forget my details, the contact gets a note saying so; AtomicX Chat never deletes HubSpot contacts.

Troubleshooting

Tips

• Contacts are matched by email, so a returning visitor updates their existing HubSpot contact instead of creating a duplicate.
• Each conversation creates at most one deal and one ticket, even if it's synced more than once.
• To stop syncing without losing your settings, untick Create contacts and click Save.

Related articles

• Integrations overview
• Workflow node types
• Test your chat
• Remember returning visitors
• View conversations

Finding a captured contact

Search HubSpot Contacts by the email address collected in chat. If the contact already exists, AtomicX updates that record; you will not see a new contact at the top of a list sorted by create date. When Attach Transcript Note is enabled, open that contact’s Activities to find the conversation note after the chat ends. A displayed chat form is not evidence of a HubSpot upload. Test connection checks access; confirm an actual contact update or transcript note to verify delivery.