How to set up WhatsApp integration with HubSpot using TimelinesAI
Sign in to TimelinesAI or register a TimelinesAI Account if you don’t have it already
Connect your WhatsApp account to TimelinesAI by navigating to the "My account" tab, within the WhatsApp section; generate and scan the QR code with your WhatsApp mobile application (works both with regular and business WhatsApp accounts)
Navigate to the HubSpot Integration section within your TimelinesAI account, and click on “Connect HubSpot”. Only the workspace owner and admins see this section; the rest of your team doesn't need to connect anything (see Give your team access in HubSpot).
If your HubSpot user is linked to multiple HubSpot accounts, choose the HubSpot account you want to connect to TimelinesAI (WhatsApp conversations will sync to that account). Grant access to your HubSpot account data by clicking on “Connect app”
Configure integration settings to enable/disable auto-creation preferences for Contacts and Deals (you can always return here later, to change the settings);
Click on “Test integration” (will be disabled if you haven’t connected a WhatsApp account yet)
A pop-up will be displayed with a link to a test Contact created in your HubSpot account; click on it. If you missed the pop-up, navigate to your HubSpot account and find the “TimelinesAI Support” contact
Navigate to the “Activities” tab and tick/check the “WhatsApp” and "WhatsApp Integration for Teams" checkboxes, so that your WhatsApp message will be displayed for Contacts
Navigate to Deals and find “Whatsapp deal (TimelinesAI Support)”. Navigate to the “Activities” tab and tick the “WhatsApp” and "WhatsApp Integration for Teams" checkboxes there as well.
And you are all set! From now on, messages from the WhatsApp accounts connected to your TimelinesAI workspace appear automatically in the Activity timeline of the matching HubSpot Contacts and Deals.
For 1 on 1 direct chats: Which Contact and Deal a chat goes to follows the Phone-number matching logic and your integration settings (automatic creation of Contacts and Deals).
For group chats: Which contact and del a chat goes to follow the Group Chat sync logic and your integration settings (automatic creation of Contacts and Deals).
Phone-number matching logic for 1 on 1 direct chats
WhatsApp messages are synced to HubSpot Contacts by matching the WhatsApp contact's number with phone numbers saved on HubSpot Contacts. Example: a WhatsApp contact with +447441447478 sends a message, and TimelinesAI has to decide which HubSpot Contact to attach it to. It does this as follows:
If this number was already matched to a Contact recently, the message goes to the same Contact. If that Contact no longer exists in HubSpot, TimelinesAI searches again.
If the Contact has Deals, the message is also logged on the most recently created Deal.
With Create new Deals automatically ON, Deals in Closed won or Closed lost are skipped.
With Create new Deals automatically OFF, closed Deals can be used as well.
If the Contact has no suitable Deal and Create new Deals automatically is ON, a new Deal is created in the pipeline and stage you selected, and the message is logged there too.
New deal name: a new Deal is named Whatsapp deal ({chat name}). If the chat is later renamed in TimelinesAI or WhatsApp deal names are not updated.
New deal owner: TimelinesAI chooses the HubSpot owner for the new deal in this order:
Chat responsible: the person assigned to the chat in TimelinesAI, if their email matches a HubSpot user.
WhatsApp account owner: used when the chat has no responsible, or their email has no match in HubSpot.
Connection owner (fallback): the person who connected HubSpot to TimelinesAI.
Group chats follow different rules: they are matched by group name, not by phone number (see Sync WhatsApp Group Chats on HubSpot).
If the number was not matched to a Contact recently or matched Contact doesn't exist anymore, TimelinesAI takes the WhatsApp contact's number (always in international format, e.g.
+447441447478).It then searches the standard Contact fields in Hubspot: Phone Number, Mobile Phone Number, Fax and WhatsApp Phone Number. The number is found whatever format it's saved in: with or without
+, with or without the country code, with spaces, dashes or brackets. For example,+44 7441 447478,07441 447478and447441447478all match.One Contact found → the message is added to that Contact as a WhatsApp activity.
Several Contacts found in standard fields → the message goes to the most recently created of them.
If nothing is found, it searches for other phone-number properties you created in HubSpot yourself, for example a "WhatsApp number" field filled in by Facebook Lead Ads. These fields are found automatically; there is nothing to set up.
Up to 5 custom phone fields are searched. If you have more, fields with "WhatsApp" in their name or label come first.
One Contact found → the message is added to that Contact as a WhatsApp activity.
Several Contacts found in custom fields → none of them is used, because a custom field may hold someone else's number (an assistant, a switchboard). The chat's sync log lists the Contacts, and TimelinesAI continues as if nothing was found.
Nothing found in standard and custom fields → with Create new Contacts automatically ON, a new Contact is created with the number in Phone Number, and the message is logged there. With it OFF, nothing is synced.
A new Contact gets the chat's name from TimelinesAI: the first word goes to First name, the rest to Last name. If the chat has no name yet, which is common for a first incoming message, the phone number is used.
If the chat is later renamed in TimelinesAI or WhatsApp, the Contact's First name in HubSpot is updated too, as long as it still shows a phone number and Create new Contacts automatically is on. A Contact whose name you've already changed in HubSpot is left alone.
New deal owner: TimelinesAI chooses the HubSpot owner for the new contact in this order:
Chat responsible: the person assigned to the chat in TimelinesAI, if their email matches a HubSpot user.
WhatsApp account owner: used when the chat has no responsible, or their email has no match in HubSpot.
Connection owner (fallback): the person who connected HubSpot to TimelinesAI.
Tip: Save phone numbers in HubSpot in international format (+ and the country code). In custom phone fields, avoid unusual groupings such as +44 7441 44 74 78: write the number without spaces (+447441447478), or in the usual +44 7441 447478 / 07441 447478 form. A number you've just added to a custom field can take up to an hour to be picked up.
Group Chats sync logic
Group chats are synced too. They are matched by name, not by phone number:
TimelinesAI looks for a Contact whose First name is exactly the group chat's name: the whole name, same spelling and capitalisation. Copy the group name from TimelinesAI, paste it into First name, and leave Last name empty.
Several Contacts have that First name, the most recently created one is used.
None is found and Create new Contacts automatically is ON, a Contact is created with the group name as First name.
During contact auto-creation for a group:
The group's unique identifier (JID, ending in
@g.us) is written to the Contact's Phone Number field. It is what lets HubSpot Workflows send messages to the group. Any number already in Phone Number on that Contact is replaced. How do you send an automated message to a WhatsApp group chat via HubSpot Workflows?Messages are logged on the Contact and its Deals the same way as 1-to-1 chats. Calls in group chats are not synced.
Important: use a separate Contact for each group. Don't reuse a person's Contact for a group, or their Phone Number will be replaced by the group's identifier.
Group Chat as seen in TimelinesAI:
Same group chat auto-created as Hubspot Contact:
HubSpot Integration Settings
Create new Contacts automatically: This option will automatically create new HubSpot Contacts, whenever a new incoming chat is received in your connected WhatsApp accounts on TimelinesAI. You can choose to turn this off, in case you want to create the contacts manually on HubSpot and contact them via WhatsApp afterwards. TimelinesAI will still sync chats accordingly.
Create new Deals automatically: It will allow you to automatically create Deals, if we detect no active Deals associated with a HubSpot Contact. If you turn this off, you'd then need to create a Deal manually before contacting someone over WhatsApp, so we can properly sync the chat to it.
Update contact and deal owner when chat assignment changes ( __turned off by default__ ): If you update a chat responsible within the Shared Inbox (Chats section) on TimelinesAI, then we'll make sure to sync that update on HubSpot, so the most recent Deal ( with recent activity or synced messages) and Contact there can also be updated accordingly with the new owner.
It's important to note that your team members' email address on TimelinesAI must match the one they have on HubSpot, so we can properly identify their profiles there
Select Pipeline: This option allows you to set a Pipeline on HubSpot, where we'll be able to automatically create Deals for you. By default, the first pipeline in your HubSpot setup is shown as "Default pipeline", but you can select any available pipeline and stage from their respective dropdown menus.
Select Pipeline Stage: And with this option, you can select the specific stage you want your automatically created Deals to be in.
Reload Pipeline Settings: This button will refresh the details we receive from your HubSpot pipelines. It is ideal in case you update a pipeline and its stage(s) on HubSpot.
Note: Both, Select Pipeline and Select Pipeline Stage settings require the Create new Deals automatically setting to be enabled, so these can work as expected. Otherwise, both options will be grayed-out.
WhatsApp Call Sync (Voice and Video)
When you make, receive, or schedule a WhatsApp voice or video call on a number connected to TimelinesAI:
A completed call creates a HubSpot Call engagement on the matched contact — and on the associated deal when one exists. It appears on the contact's and deal's activity timeline like any other call, and is picked up by HubSpot's built-in calling reports.
A scheduled call creates a HubSpot Meeting engagement in
SCHEDULEDoutcome with the WhatsApp join link as the meeting's external URL. It appears on the timeline as an upcoming meeting.In both cases, if a TimelinesAI-created WhatsApp chat activity already exists on the contact/deal for that day, the call is also appended into it.
What's covered. 1:1 direct calls only — group-chat calls (and scheduled group-chat calls) are skipped.
The Call engagement carries direction, disposition, status, duration when WhatsApp reports it, the from/to numbers, and a short body with a disclaimer about WhatsApp's duration reliability plus a link back to the chat in TimelinesAI. We map to HubSpot's default Connected and No answer dispositions — never custom ones — so your team's existing call disposition setup is not touched, and we don't push your account closer to HubSpot's 30-outcome limit.
Scheduled and actual calls are independent. When a scheduled call later takes place, a separate Call engagement is created — the scheduled meeting is not auto-completed. It stays in SCHEDULED outcome until you close it manually in HubSpot, so you'll see both objects on the timeline: the meeting (yours to close when convenient) and the actual call engagement (with the result).
Where to look if a call doesn't appear. Open the WhatsApp chat in TimelinesAI → Message sync log (right panel):
HubSpot: Logged call engagement (id:XXXXX)— successHubSpot: Created scheduled call meeting (id:XXXXX)— scheduled call syncedHubSpot: Updated Whatsapp log id…— appended to the day's chat activityHubSpot: Call engagement can not be logged. Reason: <reason>— error, contact support
How to synchronize multiple WhatsApp accounts into HubSpot
Your team can connect multiple WhatsApp numbers. It may be useful in case your salespeople use individual numbers, or if you have several departments using WhatsApp for different purposes (sales, customer support, evaluating leads, etc.)
To connect additional WhatsApp numbers, you just need to invite the team member into TimelinesAI and ask them to scan the QR code in the WhatsApp section, with their Whatsapp application. One user profile can connect a single WhatsApp number, but all users in your workspace can do it. Technically, it’s possible to connect unlimited number of WhatsApp numbers this way (subject to purchase of seats in your plan).
If you have the HubSpot integration active in this workspace, all chats from all connected WhatsApp accounts will be seamlessly synchronized just like in the case with a single WhatsApp account.
Syncing both QR-connected and WABA-connected numbers
TimelinesAI matches HubSpot Contact by phone number, so you don't get a
duplicate Contact when the same counterparty reaches you over both a
QR-connected account and a WABA-connected number. If a Contact with that phone
already exists — whether from an earlier QR sync, a WABA chat, manual entry, or
an import — TimelinesAI reuses that Contact instead of creating a new one.
Give your team access in HubSpot
HubSpot is connected once per workspace, by the owner or an admin. Your teammates don't connect HubSpot themselves. When someone opens the Live WhatsApp Chat card on a HubSpot contact or deal, TimelinesAI recognises them by the email address of their HubSpot user, and opens the chat as their own TimelinesAI user: their WhatsApp accounts and their chats.
Important: a teammate's email in HubSpot must be the same as their email in TimelinesAI. If the emails are different, TimelinesAI can't recognise them, and they will be asked to sign in or request access, even though they are already on your team. Contact our support team and we'll update the email on their TimelinesAI user so the two match.
The person who connected HubSpot is always recognised, even if their HubSpot and TimelinesAI emails differ.
Connect and disconnect HubSpot
This section covers the connection itself — what you approve when you connect, and how to disconnect or uninstall.
Scopes and permissions
When you click Connect app on the HubSpot consent screen, you approve a set of permissions (HubSpot calls them scopes). TimelinesAI asks for 6 required permissions and 3 optional ones.
Required permissions
View properties and other details about contacts | Match an incoming WhatsApp number to an existing Contact |
Create, delete, or make changes to contacts | Auto-create a Contact when no match is found |
View properties and other details about deals | Find the related Deal to log the conversation on, and read your pipelines and their stages. |
View properties about the installing account, including primary domain and user emails | Identify which HubSpot account the integration is connected to, so your conversations sync to the right account. |
View details about users assigned to a CRM record | Read HubSpot owners, so Contacts and Deals we create or update can be assigned to the right person. |
View details about account users and their permissions | Match your TimelinesAI teammates to HubSpot users by email address — this is how owner assignment works. |
Optional permissions (companies)
If you skip optional permissions, the rest of the integration works exactly as normal.
This includes workflows | Make the TimelinesAI custom actions — such as Send a WhatsApp message — available inside HubSpot Workflows. |
This includes access to File Manager | Upload attachments (images, documents, and other files) from your WhatsApp chats into HubSpot Files and link them to the synced activity. |
Create, delete, or make changes to deals | Auto-create a Deal in the pipeline and stage you selected, log the WhatsApp activity on it, and update the Deal owner when chat assignment changes. |
Disconnect HubSpot from TimelinesAI
You can disconnect HubSpot from TimelinesAI by following these steps:
Go to the HubSpot Integration section on TimelinesAI
Click on "Disconnect":
Once done, both services will be disconnected and the integration will stop working
Uninstall TimelinesAI from your HubSpot Account
Another option here is to uninstall TimelinesAI from your HubSpot account:
Go to your HubSpot Account
Click on the Settings button that's in the top-right section of the screen
Once there, head to the "Account Management" section and select "Integrations → Connected Apps":
You'll see the TimelinesAI app there. Click on "Actions" and then, select "Uninstall"
HubSpot will ask you to confirm this action by typing "uninstall":
| You can also follow these steps found within HubSpot's knowledge base to uninstall TimelinesAI from your HubSpot account
How Disconnecting/Uninstalling this Integration might affect your HubSpot account(s) and data
Disconnecting/Uninstalling this integration will stop WhatsApp chats from syncing to your HubSpot account(s).
Chats that were already synced prior to the disconnection will be kept in your HubSpot account, within your Deals and Contacts
HubSpot Workflows: All of the workflows you set where you used the TimelinesAI Custom Actions will have to be re-edited to restore them
Looking to automate HubSpot ↔ WhatsApp?
You have several options, listed from most-recommended to most-flexible:
Workflow Builder (recommended — included in your TimelinesAI plan, no separate subscription, more generous credit allowance than standalone Zapier). See HubSpot Integration in Workflow Builder.
HubSpot's native workflow engine (if you prefer to drive automations from HubSpot). See HubSpot Workflows: Send a WhatsApp Message.
Zapier or Make (separate subscription required — good if you already have an account or need a connector Workflow Builder lacks). See HubSpot and WhatsApp integration through Zapier.
Not sure which to pick? See Which Automation Tool to Use: Workflow Builder vs. Make, Zapier, and N8N.