What the sync does
When your WhatsApp Business Account is onboarded into Octopods, WhatsApp can share the contacts that already exist in your Business account. For each of those contacts, Octopods:
Normalizes the phone number to E.164 international format (for example,
+14155552671).Searches HubSpot for an existing contact whose Phone number or Mobile phone number matches.
Skips numbers that already exist in HubSpot — no duplicates are created.
Creates a new HubSpot contact for any phone number that isn’t already on file.
New contacts are created with:
First name and Last name derived from the WhatsApp display name when available.
Phone number set to the normalized E.164 number.
Mobile phone number set to the same normalized number.
When the sync runs
The sync is driven by WhatsApp itself, not by an on-demand button in Octopods:
During onboarding. When you connect a WhatsApp Business number to Octopods, WhatsApp’s onboarding flow includes a consent step that lets you share your existing Business contacts. Agreeing there is what enables the sync.
As your WABA changes. After onboarding, WhatsApp can push additional contact updates to Octopods whenever your Business account changes. Octopods processes those updates in the background and mirrors new contacts into HubSpot.
You don’t need to trigger the sync manually once the initial consent is in place.
How phone numbers are normalized
Every number is parsed and converted to E.164 format before matching. That means:
A number stored in HubSpot as
(415) 555-2671will match a WhatsApp contact whose number is+14155552671.Spaces, dashes, and parentheses are stripped.
The country code is preserved.
If a phone number can’t be parsed into a valid international format, Octopods skips it rather than creating a malformed contact.
What the sync will and won’t do
Will:
Create new HubSpot contacts for WhatsApp numbers that don’t exist in HubSpot yet.
Deduplicate against existing contacts, matching on either Phone number or Mobile phone number.
Populate the new contact with a first name, last name, and the phone number in E.164 format.
Won’t:
Update existing HubSpot contacts. If an existing contact has an out-of-date name, the sync doesn’t overwrite it.
Pull contacts from any source other than your connected WABA. Your personal phone address book, other messaging apps, and third-party lists are not involved.
Act without WhatsApp’s consent. If you declined the contact-sharing step during onboarding, no sync will happen.
Sync scale and performance
Sync batches are processed in the background in chunks that stay within HubSpot’s API limits. A large batch covering thousands of contacts may take several minutes to finish, but the work happens asynchronously — your workspace stays fully usable the whole time.
Note: When a very large batch arrives, Octopods caps the initial deduplication search at a large upper bound per run. Any numbers beyond that cap are still created in HubSpot; they just aren’t cross-checked for duplicates. In practice this only matters for accounts with tens of thousands of existing contacts in a single sync.
If contacts aren’t appearing in HubSpot
A few things to check:
Consent during onboarding. If you didn’t agree to share Business contacts during WhatsApp’s onboarding step, no sync was requested. You can re-run the WhatsApp onboarding flow and choose to share contacts this time.
HubSpot permissions. Octopods needs write access to HubSpot contacts for the sync to succeed. If the permission is missing, reauthorize the HubSpot integration from the channel settings.
Phone format. WhatsApp Business numbers that don’t parse into a valid international format are skipped. Unparseable numbers are rare because WhatsApp already stores phones in international format, but they can appear for edge-case legacy entries.
What’s next
See the WhatsApp Business Platform section for guidance on setting up a WhatsApp channel