How WhatsApp Conversation Syncing into HubSpot Actually Works

A WhatsApp message matches to a HubSpot Contact by phone number — if none exists, TimelinesAI creates one automatically. The message logs to the Contact's Timeline and attaches to their most recent deal, both within seconds. No Business API, no manual mapping. One identifier drives the whole match, start to finish.

"Connected" and "understood" are different things. Most teams know WhatsApp is feeding HubSpot somehow, but not what actually happens to a given message — which Contact it lands on, which Deal it attaches to, or what to check when it doesn't. Where conversation history displays once it's matched is covered here; this piece is about the mechanism itself — what happens between a message arriving and it showing up on a record.

A common moment this comes up: a rep insists they replied on WhatsApp, but the Deal record shows nothing. Before assuming the integration failed, it helps to know what the match is actually built on — because the failure, if there is one, usually happens at that first step, not somewhere deeper in HubSpot.

Knowing the mechanism also changes how fast a problem gets diagnosed. Someone who understands that everything downstream depends on a single phone-number match can rule out three other explanations in seconds instead of escalating a support ticket.

What actually happens when a message reaches HubSpot

Three things happen in sequence, and all three depend on the first one succeeding.

1. Match. TimelinesAI reads the sender's WhatsApp number and looks for a HubSpot Contact with that phone number stored on the record. That's the entire matching logic — one identifier, not several, and no separate lookup by name or email.
2. Create, if needed. No match found, no manual step required — a new Contact is created automatically, with the WhatsApp number set as the Contact's phone number so future messages from that same number resolve to it too.
3. Log and associate. The message logs to that Contact's Timeline as a WhatsApp activity and attaches to their most recent deal — both within seconds of the message arriving.

Without an integration, a rep doing this by hand has to notice a WhatsApp message arrived, search HubSpot for the right Contact, decide which Deal it belongs to, and log a note — a process that depends entirely on the rep remembering to do it, every time, for every message. The mechanism above replaces that judgment call with a fixed rule: same number, same Contact, most recent deal, no exceptions and no missed entries.

Why it matters: every downstream behavior — which record it's on, whether it's grouped by day on the Timeline (covered in full here), which Deal it reaches — is determined by whether that first match succeeded. If a message ends up somewhere unexpected, the phone-number match is almost always where to look first, not the Timeline display or the Deal logic.

Why matching by one identifier, not three, matters

respond.io's own HubSpot documentation confirms contact matching there uses either email or phone number as the identifier — not phone number alone.

One independent, named-author implementation guide covering respond.io's HubSpot setup documents this in more detail: the default matching priority is Email, then Phone, then WhatsApp ID — described in that guide as "backward" for a WhatsApp-heavy funnel. Its reasoning: most WhatsApp conversations don't have an email address yet when they start. If the integration tries to match by email first and finds none, it creates a Contact. When an email is captured later in the same conversation, that later message matches by email instead — creating a second Contact for the same person. The guide's own recommended fix is reordering the priority to Phone, then WhatsApp ID, then Email.

That account comes from a third-party implementation guide, not from respond.io's own documentation directly, so treat it as one practitioner's documented experience rather than a confirmed statement of respond.io's current default behavior — worth stating plainly rather than passing off as more settled than it is.

Why it matters: the fork this guide describes is structural, not a configuration mistake — it happens because the matching logic has more than one identifier competing for priority, and which one wins depends on what information happens to exist at the moment a message arrives. TimelinesAI's matching runs on the WhatsApp number alone, start to finish, so that particular failure mode has nothing to attach to. One identifier means one path to the same Contact, regardless of when other details get filled in later in the conversation.

Before you start

• HubSpot admin rights — to authorize the app via OAuth.
• Any WhatsApp account — regular WhatsApp, the Business app, or the Business API all work the same way for matching.
• About two minutes — a QR scan plus an OAuth authorization.

Step 1: Connect your WhatsApp account

Scan a QR code from the TimelinesAI workspace, the same way you'd connect WhatsApp Web.

Why it matters: this step determines what the WhatsApp number actually is — the identifier every downstream match runs on. Whatever number gets connected here is the number the matching logic will use for every message that follows. The full connect walkthrough is here if this is a first-time setup.

Step 2: Authorize HubSpot via OAuth

Authorize the HubSpot Marketplace app with an admin account. This is a standard OAuth flow — no API key to generate, no developer setup.

Why it matters: OAuth scope determines what the integration is actually allowed to write. An admin authorization is what makes Contacts, Deals, and Call Engagements all reachable — a restricted authorizing user can quietly narrow what actually syncs, which shows up later as "Contacts work but Deals don't" rather than as an obvious error at setup time.

Step 3: Let contact matching resolve

Send a message from a number that has an existing HubSpot Contact, and confirm it lands on that Contact rather than creating a duplicate.

Why it matters: this is the step worth actually watching once, rather than assuming. Because the match is phone-number-only, the most common way it goes wrong isn't the integration — it's a HubSpot Contact whose stored phone number is formatted differently than the incoming WhatsApp number, such as a missing country code or a leftover formatting character from a manual import. Confirming this once, on a Contact you already know, catches that early rather than after dozens of messages have created duplicates.

Step 4: Confirm the message lands on the Timeline

Open that Contact's record and check the Timeline for the message.

Why it matters: the message itself arrives within seconds — but HubSpot's Timeline groups a day's activity from one conversation into a single collapsed card, covered in full here. A message that isn't visible as its own line usually isn't missing; it's inside that day's card, and expanding it resolves the confusion in one click.

Step 5: Confirm it reaches the right Deal

Open the associated Deal and confirm the same conversation is visible there.

Why it matters: the message attaches to the Contact's most recent deal. For a Contact with more than one open Deal, that's worth checking rather than assuming — a conversation about a renewal shouldn't end up attached to an unrelated new-business Deal just because it happens to be more recent. This is a setup detail to know in advance, not something to discover after a rep has already reviewed the wrong Deal.

Common mistakes and troubleshooting

A message seems to be missing. Check the phone-number match first, not the Timeline. If the Contact already existed with a differently formatted number, a new duplicate Contact is the usual symptom — merge the duplicate in HubSpot and future messages will resolve correctly to the merged record.

A message doesn't appear on the Timeline yet. Almost always a display issue, not a sync failure — expand that day's grouped entry. Full explanation here.

A message attaches to the wrong Deal. Expected behavior if a Contact has multiple open Deals — the match always goes to the most recent one. This isn't a bug to fix; it's a setup detail worth knowing before it causes confusion for whoever reviews the Deal later.

Contacts sync but Deals don't. Usually an OAuth scope issue from Step 2 — re-authorize with a full admin account rather than a restricted one, and confirm the reauthorization actually completed rather than silently failing partway through.

Nothing is syncing at all. Check the WhatsApp connection itself before troubleshooting HubSpot — a disconnected WhatsApp session looks identical to a HubSpot sync failure from inside the CRM. Start here if that's the actual symptom.

Expected result — how to verify it worked

Send a WhatsApp message from a number with an existing HubSpot Contact. Within the same minute, that Contact's Timeline should show the message (expand the day's entry if it's grouped), and the associated Deal should show the same conversation. If both are true, the mechanism described above is working end to end.

Frequently asked questions

Does contact matching use anything besides the WhatsApp number?

No. Matching runs on the WhatsApp number against a Contact's stored phone number — no email step, no separate WhatsApp ID lookup, and no dependency on what other fields happen to be filled in.

What happens if the number isn't linked to a Contact yet?

A new Contact is created automatically from the WhatsApp number. No manual mapping step is required, and no separate approval step delays it.

Why did a message end up on a Deal I didn't expect?

Messages attach to a Contact's most recent deal. If a Contact has multiple open Deals, check which one is most recent rather than assuming it's the one you had in mind.

How fast does the sync actually happen?

Within seconds of the message arriving. What you see on the Timeline is grouped by day for display, which is separate from how fast the underlying sync happens — explained in full here.

Is the WhatsApp Business API required for matching to work?

No. Matching works the same way on a regular WhatsApp account, the Business app, or the Business API — the mechanism doesn't depend on which one is connected.

What happens to a message if two Contacts somehow have the same phone number?

This is a HubSpot data-quality issue rather than a sync one — duplicate Contacts sharing a phone number is possible in any CRM, independent of this integration. Merging duplicates in HubSpot resolves it; the matching logic itself has no way to guess which of two identical numbers was intended.

Is there a way to check whether this integration is actually reliable?

The HubSpot Marketplace listing shows install count and review data directly from HubSpot's own platform — a more current source than any third-party summary, this one included.

Does the same matching logic apply on other CRMs?

Yes — Pipedrive uses the same phone-number-based matching and auto-create logic; the object names differ by CRM, but the underlying mechanism is consistent.

Get started

Connect WhatsApp to HubSpot and see the phone-number match, Timeline log, and Deal association happen on your own Contacts. Start a free trial — no credit card required.