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.Prerequisites
You’ll need:- A Text account with API access permission. The service connects as this account.
- A HubSpot account with permission to edit property settings and create a Service Key.
- Docker with Docker Compose v2.
- Git to clone the sample repository.
Set up the integration
Define qualification in Text
Create the Text personal access token
customers:ro— to look up customers by email, read merged profiles, and receive pushes.customers:rw— to create the customers the import is missing.
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.Create the HubSpot property and access token
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.
Clone and configure the service
.env:.env.Both the import and the listener read this .env file.Import your HubSpot contacts
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.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.Start the qualification listener
/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: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.Verify qualification reaches HubSpot
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.Keep Text current as contacts are added to HubSpot
Keep Text current as contacts are added to HubSpot
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.Close the coverage gap on qualification
Close the coverage gap on qualification
- 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.
Make updates durable
Make updates durable
- 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
/readyzand 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.
Protect customer data in both systems
Protect customer data in both systems
- 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