HubSpot phone number property mapping (Phone Numbers section)

Phone number property mapping controls which HubSpot phone properties sync with Aloware. Admins choose which properties to track, the order new numbers fill them and, optionally, which property holds each contact's primary number.

Admins manage these settings in the Phone Numbers section at the top of Integrations > HubSpot > Settings > Contact Property Mapping. Phone properties are only available here, not in the field mapping table.

For the other contact fields, see Understanding contact property mapping settings.

Check the following before you set up the phone number property mapping:

The Phone properties found on HubSpot list shows every HubSpot contact property with the Phone number field type. Each property in the list is either tracked or ignored, and a checkbox next to it shows which.

HubSpot's three standard phone properties are phone number, mobile phone number and fax number. They're always tracked, so their checkboxes are ticked and locked with a padlock.

The rest of the list is custom phone properties your team created in HubSpot. These start unticked, so nothing syncs from them until an admin ticks them. Each property's name has a label under it saying whether it's a Standard HubSpot property or a Custom HubSpot property.

When a property is ON, Aloware works with the numbers in it:

Properties that are OFF are ignored completely. Aloware doesn't read them, write to them or search them, and doesn't treat the numbers in them as phone numbers.

Each property that's on shows a number for its position in the write order, which decides where new numbers go. Properties that are off show a dash instead. See setting the order.

Saving your changes doesn't update existing contacts right away. Each contact picks up the new settings on its next sync.

To update contacts sooner, use one of these options:

Turning a custom property OFF stops Aloware from syncing the numbers in that property. Nothing else about the contact changes. It stays linked to its HubSpot record, and its calls, messages, timeline events and other properties keep syncing as usual. Numbers already saved in HubSpot and in Aloware aren't changed or deleted, and the property keeps its position in the list.

If you turn the property back on later, Aloware resumes syncing to the same property.

Aloware doesn't search properties that are off when matching contacts. If an agent creates a contact in Aloware with a number that HubSpot already has in one of these properties, Aloware can't find the existing HubSpot record. The result depends on the Contact Creation setting in the Sync tab:

To avoid duplicate records, turn on every custom property your team uses to store contact numbers.

The order of the list decides where Aloware writes new numbers. Drag the properties that are turned on into the order you want them filled.

When an agent adds a number to a contact in Aloware, it goes into the first empty property in the order. Changing the order only affects numbers added afterward. Numbers already syncing stay in their current properties.

Aloware writes one number to each property that's on, so the number of properties you turn on sets how many numbers each contact can sync. The note below the list shows the limit. For example, with three properties on, it reads "up to 3 per contact." Any numbers beyond that limit stay in Aloware and aren't written to HubSpot.

Every Aloware contact has one primary number. The Sync the primary number with a HubSpot property switch decides whether agents choose it in Aloware or a HubSpot property decides it.

Each contact keeps the primary number it already has, and syncing doesn't change it. Agents can use Make Primary in Aloware to pick a different number. Changing the primary this way doesn't move any numbers in HubSpot.

You choose one property to hold the primary number. Phone Number is selected by default, and you can choose a custom property instead. A property that's already mapped in the Contact Property Mapping table can't be selected.

From then on, the chosen property decides each contact's primary number. On each contact's next sync, the number in that property becomes its primary in Aloware. When an agent creates a new contact in Aloware, its number is written into the chosen property.

Make Primary is disabled on every number, because the chosen property sets the primary instead.

Turning the switch on, or choosing a different property later, doesn't write anything to HubSpot or send any contacts. Each contact's primary number updates on its next sync. The switch also never moves a number that's already stored in a HubSpot property.

Click Refresh from HubSpot to re-read the list of phone properties. New properties appear unticked. Without a refresh, changes made in HubSpot appear when you reload Integration Settings, or within an hour.

When a property that's turned on is deleted in HubSpot, Aloware pauses it instead of removing it from the list. Pausing keeps your setup in place in case the property comes back.

A paused property keeps its position in the list and stays turned on, but it shows a paused tag. Its order number changes to a dash, and its checkbox can't be changed. Properties that are turned off also show a dash, so the paused tag is what identifies a deleted property.

Aloware stops writing new numbers to a paused property. Numbers already stored in it aren't changed, and the contact keeps syncing everything else as usual. A paused property never stops you from saving other changes.

To restore a paused property, recreate it in HubSpot with the same internal name. The pause clears when you click Refresh from HubSpot, the next time you open Integration Settings, or within an hour. A property with the same label but a different internal name counts as a new property, and it appears turned off.

If the property chosen to hold the primary number is deleted, it shows a paused tag. Each contact keeps the primary number it already has, and new numbers go into the first empty property in the order. Aloware doesn't write anything to the deleted property, and syncing continues without errors.

If the property won't come back, click × on its row to remove it from the list. A confirmation dialog appears, and you can undo the removal.

Once it's removed, Aloware no longer knows which property those numbers came from. The next time Aloware sends the contact to HubSpot, the numbers may move into other properties, following the order.

Changes in the Phone Numbers section don't take effect until you click Save. A confirmation message appears once they're stored. To discard changes you haven't saved yet, click Reset. This returns the section to the last saved settings.

Your saved settings stay in place as long as HubSpot stays connected. If you re-authenticate the same HubSpot portal without disconnecting it, nothing changes.

If you disconnect HubSpot and connect it again, the section returns to its defaults: the standard properties are turned on, all custom properties are turned off, and your saved order is lost.

After reconnecting, you'll need to turn your custom properties back on, set the order again and save.

Phone number property mapping affects what agents see on each contact and in the Aloware App Cards inside HubSpot.

Each number in a contact's phone list has a HubSpot mark that shows where the number is stored. Hovering over the mark shows In HubSpot as <property>. If the mark is grey and reads not synced, the number is in a property that's turned off or no longer exists in HubSpot.

When a contact's number is in a property that's turned off or deleted, the HubSpot panel shows a notice. It explains that the contact and its communications still sync, but that number doesn't.

For a property that's turned off, the notice asks the agent to have an admin turn it on. For a deleted property, it says the property must be restored in HubSpot.

When a property is chosen to hold the primary number, Make Primary is disabled on every number. Hovering over it shows "Disabled while <property> is nominated as primary in Integration Settings."

When an agent deletes a secondary number in Aloware, Aloware also clears the HubSpot property it was stored in, as long as that property is turned on. The number doesn't come back on the next sync. The primary number can't be deleted.

The calling widget reads numbers directly from the HubSpot record, so it also offers numbers stored in properties that are turned off. Calls from the widget go through and are logged on the HubSpot timeline, without creating a duplicate entry in Aloware. A call can also create the Aloware contact, or link an existing Aloware contact to the HubSpot record it was dialed from.

The SMS Messenger only uses numbers stored in properties that are turned on. If the record's only number is in a property that's off and no Aloware contact is linked yet, the messenger is blocked, with a message naming the property Aloware doesn't sync. If an Aloware contact is already linked to the record, the conversation opens normally.

When two HubSpot records have the same number in a property that's turned on, Aloware treats them as duplicates, and calls and messages appear on both timelines. Numbers in properties that are turned off are never used to match duplicates.

Phone number property mapping works together with several other settings and integrations.

Phone properties can't be mapped in the field mapping table. They appear in its dropdown but are disabled, with a hint that points to the Phone Numbers section.

Aloware only writes numbers to HubSpot when Contact Update and Contact Creation in the Sync tab are set to Bidirectional (↔).

The Delete Aloware contact when HubSpot contact has no phone numbers setting in the Sync tab only counts properties that are turned on. When HubSpot clears all of those properties, Aloware deletes the contact. If any of the contact's numbers has call or SMS history, Aloware keeps the contact and only removes its link to the HubSpot record.

Duplicate detection for Multi-Entity accounts uses the properties that are turned on.

If you use Clio Manage alongside HubSpot, turning off a HubSpot property doesn't remove the number from Clio, and the two CRMs don't conflict over a contact's numbers.

The order decides where a new number is written, and the primary switch decides which number is the primary. Neither one moves a number that's already stored in a HubSpot property.

These examples use phone number as the chosen primary property, with the order set to phone number, then mobile phone number, then fax number.