Skip to main content
This guide is for teams who run their sales process in HubSpot and want their whole CRM contact base available for qualification in Text. By the end of this guide, all of your existing HubSpot contacts are added to Text as customers that qualification applies to, and the moment Text qualifies or disqualifies one, their HubSpot contact is updated to match — so your team can filter for qualified leads directly in your CRM.

How the service works

The service runs two flows, each with a single source of truth, so neither can overwrite the other. HubSpot into Text is an import you run on demand. HubSpot decides which contacts exist, and each run copies the ones Text doesn’t have yet. Text into HubSpot runs continuously. Text decides whether a customer is qualified, and a listener updates the matching HubSpot contact whenever that verdict changes, in either direction. The asymmetry is deliberate. A contact added to HubSpot after an import stays unknown to Text until the next run, and only the customers the listener monitors can send a qualification update back.
This sample doesn’t retry failures or carry state between runs, so the two systems can drift apart. Adapt it to your needs before running the service against your real contact base — see Prepare the service for production.

Prerequisites

You’ll need:
livechat/hubspot-customer-qualification-guide
Loading repository data...

Set up the integration

1

Define qualification in Text

Qualification runs on customer fields. If you don’t have this definition set up yet, in Text, go to Settings → Customer fields and create the fields your team uses to determine a lead — company size, budget, whatever your sales process turns on. Assign the Qualification category to these fields so they appear in the Qualification section of the customer’s profile.A customer qualifies once every Qualification field has a value and they have an email address or a phone number.
2

Create the Text personal access token

Go to Settings → API access → Personal access tokens and create a token with these scopes:
  • customers:ro — to look up customers by email, read merged profiles, and receive pushes.
  • customers:rw — to create the customers the import is missing.
Copy the Base64-encoded value Text displays. It encodes account_id:personal_access_token, and you’ll set it as TEXT_TOKEN_BASE64. See Personal access tokens for the full flow.Create the token on the agent account you want the listener to run as. That account’s team membership decides which customers the listener sees.
Treat the token like a password. Store it in a secrets manager for a deployed service and never commit it.
3

Create the HubSpot property and access token

The listener writes the qualification information to a contact property which you need to create yourself — the service validates it at startup but never creates it.In HubSpot, go to Settings → Properties, select Contact properties, and create:The service writes only to this property. Check the internal name before saving, because HubSpot doesn’t let you change it afterwards. Put the property in whichever contact property group suits your team. For more details, see HubSpot’s Create and edit properties.Then follow HubSpot’s Service Key setup and grant these scopes:
  • crm.objects.contacts.read — to page through contacts and look one up by email.
  • crm.objects.contacts.write — to update the property.
  • crm.schemas.contacts.read — to validate the property at startup.
If your HubSpot account already has a private app with these scopes, use its access token instead of creating a Service Key.
4

Clone and configure the service

Clone the repository and enter its directory:
Copy the example environment file:
Fill in .env:Git and the Docker build both ignore .env.Both the import and the listener read this .env file.
5

Import your HubSpot contacts

Start with a dry run. It reads every contact and reports what a real import would do, without writing anything to Text:
The command pages through every non-archived HubSpot contact, normalizes each primary email to lowercase, checks for an exact match in Text with List customers, and counts what it finds. Every counter below is a number of records. Review the summary before you run the final import:A high missing_email or duplicate count is worth resolving in HubSpot first, because email is the only key that connects the two systems. Only the primary email counts — a contact’s secondary addresses and HubSpot’s own alias resolution are outside what this sample matches on.
There’s no ceiling on how many contacts a run covers, so a large contact base costs time rather than coverage. Requests are paced at one every 200ms, which puts a floor of about five minutes on 55,000 contacts, before response times.
When the numbers look right, run the import:
The import creates the missing customers in batches of up to 100 with Create customers, copying the email and the combined first and last name. Run one import at a time.The command exits 0 when the run completes and 1 when it stops on an error.Rerun the import whenever you want to pick up contacts added to HubSpot since the last run, because nothing else brings them into Text. A later run doesn’t create anything twice, because it finds the customers earlier runs created and counts them as existing. An import never propagates later edits to a HubSpot contact, and it never deletes a Text customer.
Check in Text that the last run’s customers are there before you rerun an import. A newly created customer isn’t guaranteed to be visible to the next lookup, so a rerun can otherwise duplicate them. A run that stopped partway leaves what it created, with no rollback.
6

Start the qualification listener

Build and start the service:
At startup the service validates the HubSpot property, finds your qualified lead definition, resolves your organization from your token, and opens an RTM connection with online customer monitoring. Any of those failing stops the service with a message naming the cause.From then on the listener has to stay running. It updates HubSpot only while it’s connected, and a push that arrives while the service is stopped is gone — Text doesn’t queue it, and the listener doesn’t catch up on reconnect. Run it as a long-lived service rather than starting it when you need it.Confirm the service is connected:
/readyz returns 204 once RTM login succeeds and 503 while disconnected. /healthz reports process liveness. Readiness describes the connection, not whether every qualification update succeeded.Follow the logs while you test:
From here, a segment_memberships_updated push arrives whenever a monitored customer joins or leaves a segment. The listener ignores pushes for other segments. For one that matches, it re-reads the customer’s merged profile to get the current verdict rather than trusting the event alone.The service updates the property only when the value differs. It doesn’t create new contacts.
7

Verify qualification reaches HubSpot

Test with a visitor who is online, identified by an email address that exists on exactly one HubSpot contact and one Text customer. Text monitors only live visitors, so an imported contact who isn’t on your site can’t trigger an update.Change that visitor’s data so they meet your qualified lead conditions. The log records the event, and the contact’s Text qualified lead checkbox in HubSpot turns on.Then change the data back so they no longer qualify. The checkbox turns off again.

Act on qualification from HubSpot

Your team now has one property in HubSpot carrying the verdict your Qualification fields define. Those fields decide what qualifying means for your organization, and a conversation that fills the last one in moves the contact into view while it’s still going on. It’s an ordinary contact property, so your usual HubSpot tools work on it: a list can filter on it, a workflow can enroll a contact the moment its value changes, and a view can order a day’s follow-ups around it. One characteristic is worth designing around: the property reflects membership as it stands, not history. A contact who stops meeting your conditions leaves a filtered list as quietly as they joined it. If a record of who was ever qualified matters to your team, capture it in HubSpot when the value changes, because the service doesn’t keep one.

Troubleshooting

Prepare the service for production

Before you deploy this service, address these four areas.
An import only covers the contacts that existed when it ran, and it reads your whole contact base each time. Scheduling docker compose run --rm qualification import keeps Text roughly current without depending on someone remembering to run it.For a continuous flow, a HubSpot app can subscribe to contact creation events and create the Text customer as each contact appears, leaving the import to seed what came before. That shifts the HubSpot side from a batch you remember to run to an integration that keeps itself current.
The listener only hears about customers Text is monitoring, and it never backfills. Customers already in the qualified lead segment when you first start it are never written to HubSpot, and neither are the verdicts that changed while the service was down.Before deploying:
  • Reconcile periodically by listing qualified customers and comparing them against the HubSpot property, so a missed event self-corrects.
  • Decide what an unset property means to your sales team, given that it covers both “not qualified” and “never seen.”
  • Widen the agent’s team membership if monitoring misses customers you care about, or subscribe to specific groups with subscribe_customers. Group subscriptions add to login monitoring, so overlapping coverage delivers the same change twice.
Every request gets one attempt, including rate-limited and server-error responses, and the listener holds pending updates in a 256-event in-memory buffer that discards an update when it overflows. A failed update is logged once and never retried.Before deploying:
  • Retry temporary Text and HubSpot failures with backoff, and alert when one still fails.
  • Replace the in-memory buffer with a durable queue so a restart doesn’t drop pending updates.
  • Monitor /readyz and alert on sustained disconnection, because a stopped listener fails silently. The listener reconnects with backoff but gives up after repeated failures, so the container exits rather than retrying indefinitely.
The service copies customer identity and a qualification verdict from Text into HubSpot. Its logs hold counts, outcome labels, and status codes, and omit emails, names, customer IDs, and payloads.Before deploying:
  • Store both credentials in a secrets manager and rotate them like any other credential.
  • Confirm that copying qualification into HubSpot meets your consent and retention requirements.
  • Run the listener as a dedicated agent account, because connecting affects that account’s presence and monitoring settings.

Keep exploring

Customer Data Platform API reference
Agent Chat RTM API reference
Customer identities and merged customers
Personal access tokens