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).
1-to-1 chats can also sync to the Company linked to the Contact, if you turn this on (sync to the linked Company).
Group chats are synced to their own HubSpot Contact, one per group, with their own settings (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. With Company sync on, 1-to-1 conversations also appear on the Contact's linked Company (see Sync 1-to-1 chats to the linked Company).
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, on the Deal the chat is synced to and, with Company sync on, on the linked Company (see how the Contact and Deal are chosen).
In group chats, each message shows who wrote it: the member's WhatsApp name, or the teammate who sent it from TimelinesAI.
In group chats, files are synced only when Sync attachments is on in the group chat settings (see HubSpot Integration Settings).
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.
On a Contact, the card also shows the group chats that the Contact's number is a member of.
On a Deal, click Chat with associated contacts to see the 1-to-1 and group chats of every Contact on the Deal.
In a group chat, the header shows how many members the group has; click it to see each member's name, number and role.
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 Deal it was last synced to. If there is none yet, the most recently updated Deal is used.
Deals that belong to a group chat are skipped, so 1-to-1 messages never land on a group's 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: each group is synced to its own Contact (see Group chats sync logic).
Sync 1-to-1 chats to the linked Company
1-to-1 WhatsApp chats can also appear on the HubSpot Company linked to the Contact, so your team sees the conversations with everyone at a client company in one place.
How to turn it on
In HubSpot Integration, under 1-to-1 chats, turn on When found contact/deal has a linked company. It is off by default.
How it works
The day's WhatsApp activity is also added to the Contact's primary Company. If the message is logged only on a Deal, the Deal's primary Company is used.
It is the same activity, not a copy: it appears on the Contact, the Deal and the Company.
TimelinesAI never searches for, creates or edits Companies. It only uses the primary Company already linked in HubSpot. If the Contact has no Company, nothing changes.
A Company you've just linked can take up to an hour to start receiving activities.
Group chats aren't synced to Companies yet.
To check it, open the chat in TimelinesAI: the Message sync log shows Activity associated with primary company id:… for contact/deal id:….
Group chats sync logic
Group chats have their own settings, separate from 1-to-1 chats (see HubSpot Integration Settings). Each group is synced to one HubSpot Contact that represents the group.
How the group's Contact is found
If the group was synced before, the same Contact is used.
Otherwise, TimelinesAI looks for a Contact whose Phone Number holds the group's unique identifier (JID, ending in
@g.us). Because of this, renaming the group doesn't create a new Contact.Otherwise, it looks for a Contact whose First name is exactly the group's name: the whole name, same spelling and capitalisation. To link a group to an existing Contact, copy the group name from TimelinesAI, paste it into First name, and leave Last name empty.
If nothing is found:
With Create new Contacts automatically on in the group chat settings, a Contact is created: the whole group name goes to First name, Last name stays empty.
With it off, the group isn't synced.
Coming soon (not released yet): group chats will also sync to members' own Contacts. If Create new Contacts automatically is off for group chats, TimelinesAI will log the group's activity on members who already exist as Contacts in HubSpot (up to 20 per group). Until then, a group with this setting off isn't synced.
When a group is matched or created, its JID is written to the Contact's Phone Number field, replacing any number already there. The JID is also 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?).
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.
Important: if your HubSpot account validates phone numbers on the Phone number property, HubSpot rejects the group's identifier and group chats can't sync. See Group chat sync paused: HubSpot phone validation rule.
One Contact per group
If several of your team's WhatsApp numbers are in the same group, the group still gets one Contact and each message is logged once. The group chat on the other numbers shows Messages are already synced from another chat of the same group in its Message sync log.
Owner of a new group Contact
The teammate whose WhatsApp number most recently sent a message in the group, if their email matches a HubSpot user. Otherwise, the person who connected HubSpot. With Update contact and deal owner when group chat assignment changes on, assigning the group chat in TimelinesAI changes the owner to the assignee.
What is logged
One WhatsApp activity per group per day, titled
WhatsApp Group Chat: {group name} (DD/MM/YYYY). The day follows your HubSpot account's time zone.Each message shows who wrote it: the member's WhatsApp name, or the teammate who sent it.
Files are added only when Sync attachments is on. Files over 50 MB aren't uploaded: the activity shows
Failed to upload {file name}: File is too big, and the rest of the messages still sync.Calls in group chats are not synced.
Group chats aren't synced to Companies yet.
Deals
Group chats don't create Deals. A Deal that is already associated with the group's Contact keeps receiving the group's activities; if you remove that association, it stops. If you merge that Deal in HubSpot, the activities follow the merged Deal.
Group chat as seen in TimelinesAI:
The same group chat auto-created as a HubSpot Contact:
Group chat sync paused: HubSpot phone validation rule
If 1-to-1 chats sync to HubSpot but group chats don't, the likely cause is HubSpot's phone number validation rule.
Why this happens
TimelinesAI saves the group's identifier (JID, for example [email protected]) in the Phone Number field of the group's Contact. If the Validate phone numbers, requiring a country code rule is on for the Phone number property, HubSpot rejects it, because it doesn't start with + and a country code. 1-to-1 chats aren't affected: they use real phone numbers.
How to tell
When you turn on Create new Contacts automatically for group chats, a window says HubSpot is set to reject WhatsApp group contacts on this portal, and the setting isn't saved.
The HubSpot Integration page in TimelinesAI shows a red banner: HubSpot is rejecting WhatsApp group contacts on this portal. Group chat sync is paused, and Create new Contacts automatically for group chats has been turned off.
The workspace owner gets an email: HubSpot is rejecting WhatsApp group contacts on your portal — action required.
How to fix it
You need a HubSpot user who can edit contact properties. If that isn't you, forward this section to your HubSpot admin.
In HubSpot, go to Settings → Properties.
In Select an object, choose Contact properties.
Search for
phoneand open the Phone number property.Open the Rules tab.
Turn off Validate phone numbers, requiring a country code.
Click Save.
In TimelinesAI, go to HubSpot Integration and turn Create new Contacts automatically for group chats back on. If the window is still open, click Recheck.
The window's Open my HubSpot phone settings link takes you straight to step 3.
Note: only the Phone number property matters. A rule on Mobile phone number doesn't block group chats.
After you fix it
Group chats sync again from the next message. The red banner disappears.
Messages sent while sync was paused are not added to HubSpot later. They stay in WhatsApp and TimelinesAI.
If you want to keep phone validation on
The rule and group chat sync can't work together on the same HubSpot account. With the rule on, only 1-to-1 chats sync. If you rely on the rule, contact our support team in live chat and include your HubSpot account ID (Hub ID).
HubSpot Integration Settings
Find these in HubSpot Integration in TimelinesAI. The page has two columns: settings for 1-to-1 chats and settings for group chats. They work independently.
Note: only the person who connected HubSpot can change these settings. Other admins see them as read-only with Only the connection owner can edit these settings. To take over, click Reconnect (see Reconnect HubSpot): whoever reconnects becomes the connection owner, and the settings are kept.
1-to-1 chats
Create new Contacts automatically (off by default): when 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 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 owner of the Contact and of the Deal the chat syncs to changes to that person. This works only if their TimelinesAI email matches their HubSpot user. Unassigning a chat changes nothing.
When found contact/deal has a linked company (off by default): the activity is also added to the primary Company linked to the Contact or Deal (see Sync 1-to-1 chats to the linked Company).
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.
Refresh pipelines: fetches your pipelines and stages from HubSpot again, for example after you change them there.
Note: the pipeline settings can be changed only when Create new Deals automatically is on.
Group chats
Create new Contacts automatically: when no Contact is found for a group, one is created for it (see Group chats sync logic). When you turn it on, TimelinesAI checks that HubSpot accepts group Contacts (see phone validation rule).
Update contact and deal owner when group chat assignment changes (off by default): when you assign the group chat in TimelinesAI, the owner of the group's Contact changes to that person, if their TimelinesAI email matches their HubSpot user.
Sync attachments: files sent in the group are added to the day's activity. Off by default for new connections; workspaces connected before this update keep it on.
Group chats don't create Deals, so there are no pipeline settings for them.
If HubSpot needs more permissions
If a banner says Your HubSpot connection requires additional permissions to sync correctly, click Reconnect and approve the permissions in HubSpot. Your settings are kept, and messages waiting to sync are sent after you reconnect. A setting marked Not syncing — missing permissions is turned off: turn it back on after reconnecting.
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). All 9 are required.
This includes workflows | Makes the TimelinesAI actions, such as Send a WhatsApp message, available in HubSpot Workflows. |
View properties and other details about contacts | Match an incoming WhatsApp number to an existing Contact, and find the Contact's linked Company. |
Create, delete, or make changes to contacts | Create a Contact when no match is found, and update its owner. |
View properties and other details about deals | Find the Deal to log the conversation on, and read your pipelines and stages. |
Create, delete, or make changes to deals | Create a Deal in the pipeline and stage you selected, log the activity on it, and update its owner. |
This includes access to File Manager | Upload files from your WhatsApp chats to HubSpot Files and link them to the activity. |
View properties about the installing account, including primary domain and user emails | Identify which HubSpot account the integration is connected to. |
View details about users assigned to a CRM record | Read HubSpot owners, so new Contacts and Deals get the right owner. |
View details about account users and their permissions | Match your TimelinesAI teammates to HubSpot users by email. |
Reconnect HubSpot
Click Reconnect on the Workspace connection card in HubSpot Integration to approve the connection in HubSpot again, without disconnecting.
When to use it
A banner says Your HubSpot connection requires additional permissions to sync correctly.
The person who connected HubSpot has left, or someone else needs to manage the settings.
What happens
You approve the permissions on HubSpot's consent screen.
Your settings are kept, and messages waiting to sync are sent.
You become the connection owner: you can edit the settings, and you're the fallback owner of new Contacts and Deals.
A setting marked Not syncing — missing permissions stays off. Turn it back on after reconnecting.
Disconnect HubSpot from TimelinesAI
The workspace owner or an admin can disconnect HubSpot:
Go to HubSpot Integration in TimelinesAI.
Click Disconnect, then confirm with Disconnect all.
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, Deals and Companies.
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.
Group chats don't appear in HubSpot
Check the group chat's Message sync log in TimelinesAI first.
Make sure Create new Contacts automatically is on in the group chat settings, or that a Contact with the group's exact name exists (see Group chats sync logic).
If 1-to-1 chats sync but groups don't, see Group chat sync paused: HubSpot phone validation rule.
WhatsApp activities don't appear on the Company
Make sure When found contact/deal has a linked company is on in the 1-to-1 chat settings.
Make sure the Company is the Contact's primary Company in HubSpot.
A Company linked recently can take up to an hour to start receiving activities.
Group chats aren't synced to Companies yet.
Check the chat's Message sync log in TimelinesAI: a line starting with
company association failedgives the reason.
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.
Group chats never create Deals.
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.
For group chats, make sure Sync attachments is on in the group chat settings.
HubSpot asks for additional permissions
Click Reconnect on the HubSpot Integration page and approve the permissions. You don't need to disconnect, and your settings are kept (see Reconnect HubSpot).
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.