How to set up WhatsApp integration with HubSpot using TimelinesAI
Connect your WhatsApp account. Works both with regular and business WhatsApp apps.
Go to HubSpot Integration and click Connect HubSpot. The workspace owner or an admin does this once for the whole team. In HubSpot, pick the account your chats should sync to and click Connect app.
You're all set. New messages from your team's connected WhatsApp numbers will sync to the matching HubSpot Contacts and Deals:
1-to-1 chats are matched by phone number (how matching works).
Group chats are matched by group name (how group sync works).
WhatsApp text and file messages are logged as activities (messages and files).
WhatsApp calls are logged too: completed calls as HubSpot Calls, scheduled calls as Meetings (call sync).
Live WhatsApp Chat: your team can read and reply to WhatsApp chats right from a Contact or Deal in HubSpot (Live WhatsApp Chat).
Optional: adjust the HubSpot Integration settings to fit how your team works (what each setting does).
What you'll see in HubSpot
Once HubSpot is connected and at least one WhatsApp number is connected to TimelinesAI, new messages sync to the matching HubSpot Contact and its Deal. Open a Contact you've messaged since connecting: the WhatsApp conversation appears in its Activity timeline.
Make WhatsApp activities visible (one time)
HubSpot may hide new activity types by default. If you don't see WhatsApp activities:
Open any Contact and go to the Activities tab.
Click the arrow next to Activity (X/Y) to open the activity filter.
Tick WhatsApp and WhatsApp Integration for Teams. Also make sure Calls and Meetings are ticked, because WhatsApp calls are synced as those types.
You only need to do this once; the filter applies to all Contacts and Deals.
Messages and files
One activity per day: all messages sent and received in a chat on the same day are grouped into one WhatsApp activity. The next day's messages start a new one.
Received messages are aligned to the left and sent messages to the right, each with its time.
Files (images, documents, voice messages) appear inside the activity next to the message they came with. They're also saved to HubSpot Files.
File Manager access is required and cannot be turned off. Attachments are uploaded to HubSpot Files.
Each activity has a link to the chat in TimelinesAI.
The same activity appears on the Contact and on the Deal the chat is synced to (see how the Contact and Deal are chosen).
WhatsApp Call Sync (Voice and Video)
WhatsApp calls in 1-to-1 chats are synced to HubSpot as native HubSpot activities:
A completed call becomes a HubSpot Call on the Contact, and on its Deal if there is one. It shows direction, outcome (Connected or No answer), duration when WhatsApp reports it, the phone numbers, and a link to the chat in TimelinesAI. It counts in HubSpot's calling reports.
A scheduled call becomes a HubSpot Meeting with the WhatsApp join link, shown as upcoming.
The call is also added to that day's WhatsApp activity, if there is one.
Good to know
Group chat calls are not synced.
A scheduled call and the actual call are separate. When a scheduled call takes place, a new Call is logged. The Meeting stays open until you close it in HubSpot.
Duration may be approximate: WhatsApp doesn't always report it reliably.
Only default outcomes are used. TimelinesAI never adds custom call outcomes, so your HubSpot call setup isn't changed.
A call doesn't appear?
Open the chat in TimelinesAI and check the Message sync log in the right panel:
HubSpot: Logged call engagement (id:…): synced.HubSpot: Created scheduled call meeting (id:…): scheduled call synced.HubSpot: Updated Whatsapp log id…: added to the day's activity.HubSpot: Call engagement can not be logged. Reason: …: not synced; contact support.
Live WhatsApp Chat
You and your team can read and reply to WhatsApp chats without leaving HubSpot. Open a Contact or a Deal and find the Live WhatsApp Chat card in the right sidebar. Click Chat with the contact to open the chat window, where you can read the conversation, reply, or start a new chat. Full guide: Embedded WhatsApp Chat View in HubSpot.
Note: to use the card, your teammates need a TimelinesAI user with the same email as their HubSpot user (see TimelinesAI app settings in HubSpot).
Add or move the card (one time)
HubSpot usually places new app cards at the bottom of the sidebar. To move the card, or to add it if you don't see it:
On a Contact or Deal page, click Customize, then open your view (usually Default view, unless you've created your own).
To move the card: drag and drop it where you want it.
To add the card: click the + (Add card) icon.
Then open Card library, set Card type to Apps, and click Add card next to Live WhatsApp Chat.
Click Save and exit. The card now appears in that position in the sidebar.
Contacts and Deals have separate layouts, so repeat this on a Deal page to change the Deal sidebar too.
TimelinesAI app settings in HubSpot
The TimelinesAI app has its own Settings page inside HubSpot. It shows your connection and lets you bring your HubSpot teammates into TimelinesAI.
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, TimelinesAI recognises them by the email address of their HubSpot user and opens the chat as their own TimelinesAI user, with their WhatsApp accounts and 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 in live chat 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.
How to open it
From any Contact or Deal: click Settings at the bottom of the Live WhatsApp Chat card.
Or in HubSpot's Connected apps: click WhatsApp Integration by TimelinesAI, or choose Actions → Go to settings.
What you see on this page depends on your role in TimelinesAI:
Workspace owner or admin
This view is also shown to the person who connected HubSpot.
Workspace connection: the connected HubSpot account and who connected it.
Team members: every active user of your HubSpot account, each with a status:
You: your own row.
Member: already on your TimelinesAI team.
Invited: invitation sent, not accepted yet. Click Resend to send it again.
Requested to join: they asked for access from their own Settings page. Click Review in TimelinesAI to approve or decline.
Join request declined
Not in TimelinesAI: select them to invite. The invitation goes to the email of their HubSpot user, and the row changes to Invited right away.
When someone is waiting for approval, a line at the top says so, with a Review requests link.
Seats: how many seats are used, for example 5 of 9 seats used, and a Manage seats link. Only the workspace owner can change seats.
Refresh updates the list without reloading HubSpot, for example after you approve a request.
An expired invitation doesn't have its own status: that person shows as Not in TimelinesAI again and can be re-invited. People added to your HubSpot account recently can take up to an hour to appear in the list.
Team member
The page shows Ready to use: your TimelinesAI user is connected, and you can use the WhatsApp chat from any Contact or Deal. Nothing to set up.
HubSpot user without TimelinesAI access
Access can be requested: click Request access to ask to join the connected TimelinesAI workspace.
Access request pending: your request was sent. A workspace admin approves it in TimelinesAI. Once approved, the Live WhatsApp Chat card works for you, with nothing else to do.
Access request declined: contact a workspace admin if you still need access.
HubSpot not connected to TimelinesAI
The page shows HubSpot is not connected: a TimelinesAI workspace owner or admin needs to connect HubSpot first. The page links to Connect HubSpot in TimelinesAI.
Unpaid subscription
If the TimelinesAI subscription is unpaid, a Subscription payment required banner appears above any of these views. Owners and admins also get a Manage subscription link.
WhatsApp action in HubSpot Workflows
Use the TimelinesAI Send a WhatsApp message action in HubSpot Workflows to send WhatsApp messages automatically, for example when a Deal moves to a new stage. The action needs the workflows permission to be turned on (see Scopes and permissions). Full guide: HubSpot Workflows: Send a WhatsApp Message.
WhatsApp tool in HubSpot Breeze Agents
HubSpot's AI-powered Breeze Agents can send WhatsApp messages through the TimelinesAI WhatsApp tool. Full guide: TimelinesAI WhatsApp tool in HubSpot Breeze Agents.
How it works
Phone-number matching logic for 1-to-1 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.
Otherwise, TimelinesAI takes the WhatsApp contact's number (always in international format, e.g.
+447441447478) and searches for it.It first searches the standard Contact fields 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 → the message goes to the most recently created of them.
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 447478form. A number you've just added to a custom field can take up to an hour to be picked up.
If nothing is found, it searches 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 → 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.
New Contact name: 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.
Renaming: 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 Contact owner: chosen in the same order as for new Deals (see below).
Which Deal the message goes to
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 it 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: Whatsapp deal (chat name). If the chat is later renamed in TimelinesAI or WhatsApp, Deal names are not updated.
Owner of new Contacts and Deals
TimelinesAI chooses the HubSpot owner 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 Group chats sync logic).
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.
If several Contacts have that First name, the most recently created one is used.
If none is found and Create new Contacts automatically is ON, a Contact is created with the group name as First name.
When a group is matched to a Contact or a Contact is created for it, 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 (see How do you send an automated message to a WhatsApp group chat via HubSpot Workflows?). Any number already in Phone Number on that Contact is replaced.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:
The same group chat auto-created as a HubSpot Contact:
HubSpot Integration Settings
Find these in HubSpot Integration in TimelinesAI (workspace owner and admins).
Create new Contacts automatically (off by default): when a message is sent or received and no Contact matches the number, a new Contact is created. If it's off, only chats with an existing Contact are synced.
Create new Deals automatically (off by default): when the Contact has no open Deal, a new Deal is created in the pipeline and stage below. If it's off, messages are still logged on the Contact, and on its most recent Deal if it has one.
Update contact and deal owner when chat assignment changes (off by default): when you assign a chat to someone in TimelinesAI, the Contact's owner and the Deal the chat syncs to are changed to that person. This works only if their TimelinesAI email matches their HubSpot user. Unassigning a chat changes nothing.
Select Pipeline: where new Deals are created. HubSpot's default pipeline is used until you pick another. If the chosen pipeline or stage is deleted in HubSpot, TimelinesAI switches back to the default one and shows a warning.
Select Pipeline Stage: the stage new Deals start in. Changing the pipeline selects its first stage.
Reload pipeline settings: fetches your pipelines and stages from HubSpot again, for example after you change them there.
Note: Select Pipeline, Select Pipeline Stage and Reload pipeline settings are available only when Create new Deals automatically is on.
How to sync multiple WhatsApp numbers into HubSpot
Your team can connect several WhatsApp numbers, for example one per salesperson, or separate numbers for sales and support.
To add a number, invite the teammate to TimelinesAI and ask them to connect their WhatsApp in the WhatsApp section. One user connects one WhatsApp number; how many users you can have depends on the seats in your plan.
Chats from all connected numbers sync to HubSpot the same way as with a single number.
QR-connected and WABA-connected numbers
TimelinesAI matches HubSpot Contacts by phone number, so you don't get a duplicate Contact when the same person reaches you over both a QR-connected account and a WABA-connected number. If a Contact with that phone already exists (from an earlier QR sync, a WABA chat, manual entry, or an import), TimelinesAI reuses that Contact instead of creating a new one.
Connect and disconnect HubSpot
This section covers the connection itself: what you approve when you connect, and how to disconnect or uninstall.
Deprecated Individual connections (for existing customers)
Note: previously, each team member could also connect HubSpot for themselves (Connect only for me). This is no longer needed, and the option has been removed. HubSpot is now connected once for the whole workspace, and each teammate is recognised by the email of their HubSpot user (see TimelinesAI app settings in HubSpot).
What happens to existing individual connections
They keep working. Teammates who connected individually before still open the Live WhatsApp Chat card as themselves, even if their HubSpot and TimelinesAI emails differ. Nobody needs to reconnect anything.
No new individual connections can be made. New teammates are recognised by email.
Only the workspace owner and admins see the HubSpot page in TimelinesAI. Other roles no longer have it in their menu, because there's nothing for them to set up.
Disconnecting HubSpot removes them. If the workspace connection is disconnected, all existing individual connections are removed as well. After you connect again, teammates are recognised by email only, so make sure their HubSpot and TimelinesAI emails match.
Scopes and permissions
When you click Connect app on the HubSpot consent screen, you approve the permissions TimelinesAI needs (HubSpot calls them scopes). File Manager is required and cannot be turned off. If your HubSpot plan does not include workflows, the connection still works, and the TimelinesAI actions in HubSpot Workflows are not available.
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. |
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. |
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. |
File Manager and workflows
Workflows | Makes the TimelinesAI custom actions — such as Send a WhatsApp message — available inside HubSpot Workflows. If your HubSpot plan does not include workflows, the connection still works. |
File Manager | Uploads attachments (images, documents, and other files) from your WhatsApp chats into HubSpot Files and links them to the synced activity. Required, and cannot be turned off. |
Disconnect HubSpot from TimelinesAI
The workspace owner or an admin can disconnect HubSpot:
Go to HubSpot Integration in TimelinesAI.
Click Disconnect.
Uninstall TimelinesAI from your HubSpot account
You can also uninstall the TimelinesAI app from HubSpot:
In HubSpot, click the Settings icon in the top-right corner.
Go to Integrations → Connected Apps.
Find the TimelinesAI app, click Actions, then Uninstall.
Confirm by typing "uninstall".
See also HubSpot's own guide: Uninstall an app.
What happens when you disconnect or uninstall
WhatsApp chats stop syncing to HubSpot.
Chats that were already synced stay in HubSpot, on your Contacts and Deals.
HubSpot Workflows that use TimelinesAI custom actions will need to be edited again to restore them.
Troubleshooting
For any sync question, start with the chat in TimelinesAI. Open it and look at the right panel: the HubSpot card links to the Contact and Deal the latest message was synced to, and the Message sync log shows what happened to each message — which Contact was found, what was created, or why the sync was skipped.
WhatsApp messages don't appear on a Contact
Check the chat's HubSpot card and Message sync log in TimelinesAI first: the messages may have been synced to a different Contact, or skipped with a reason.
Make sure WhatsApp activities are visible in HubSpot (see Make WhatsApp activities visible).
Make sure the Contact's number is in a phone field TimelinesAI searches (see Phone-number matching logic).
If the Contact doesn't exist yet and Create new Contacts automatically is off, the chat isn't synced.
A duplicate Contact was created
Check the chat's Message sync log in TimelinesAI: it shows that no Contact was found and a new one was created, or that several Contacts matched a custom phone field.
Usually the number on the existing Contact is in a field TimelinesAI doesn't search, or written in an unusual format in a custom field. Merge the two Contacts in HubSpot and save the number in a standard phone field (see Phone-number matching logic).
No Deal was created
Check the chat's Message sync log in TimelinesAI to see which Deal the messages went to.
Make sure Create new Deals automatically is on (see HubSpot Integration Settings).
If the Contact already has an open Deal, messages go to that Deal instead of a new one.
Files don't appear in HubSpot
Check the chat's Message sync log in TimelinesAI for an upload error.
File Manager access is required and cannot be turned off. A missing file is an upload error in that log.
My teammate sees "Request access" or a sign-in message, but they're on our team
Their email in HubSpot is different from their email in TimelinesAI, so TimelinesAI can't recognise them. Contact our support team in live chat and we'll change the email on their TimelinesAI user to match their HubSpot one. There's no need to reconnect or reinstall anything.
How can I test the connection?
In HubSpot Integration, click Test integration (it needs a connected WhatsApp number). It creates a test Contact TimelinesAI Support with a Deal, so you can check that messages arrive.
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.