This guide covers TimelinesAI’s native Salesforce integration. With it, your WhatsApp conversations sync into Salesforce in real time — matched to the right Leads, Contacts, and Opportunities — so your team keeps full context and accurate reporting without manual data entry.
Looking to automate custom actions between Salesforce and WhatsApp instead (e.g. send a message when an Opportunity changes stage)? See Salesforce Integration in Workflow Builder.
What the Integration Does
Real-time WhatsApp → Salesforce sync — incoming and outgoing messages are written to Salesforce the moment they happen.
Matches across Leads, Contacts, and Opportunities — conversations land on the right record; you choose which objects are in scope.
Auto-create Leads for unknown numbers (optional) — a new WhatsApp number with no match can create a Lead automatically. Only Leads are auto-created — Contacts and Opportunities are match-only.
Group chat sync (optional) — WhatsApp group conversations sync as a single record.
Attachment sync (optional) — images and documents sync as native Salesforce files.
Accurate agent attribution — activity is credited to the team member handling the chat, including handoffs.
Sync Audit Log — a downloadable log of exactly what synced, what didn’t, and why.
How the Integration Works
When a WhatsApp message is sent or received in a 1-to-1 chat, TimelinesAI:
Looks up the contact’s phone number across the Salesforce objects you enabled (Contact, Lead, Opportunity — and Person Account for B2C orgs).
If a matching record is found — the message is logged to that record.
If no match is found — if Auto-create Leads is on, a new Lead is created; if off, the message is skipped and recorded in the Sync Audit Log.
Messages are aggregated into a single daily Task per chat (based on your Salesforce org timezone), so Salesforce isn’t flooded with one record per message. Each new message that day appends to the same Task.
Tip: Store Salesforce phone numbers in international format (+country code…) with no spaces or symbols for reliable matching. If an exact match isn’t found, TimelinesAI falls back to matching on the last 7 digits.
Prerequisites
Before you connect, make sure you have:
An active TimelinesAI workspace on a plan that includes CRM integrations.
You are the Owner or Admin of the TimelinesAI workspace.
A Salesforce edition with API access — Enterprise, Unlimited, Performance, or Developer. Professional requires the Salesforce API add-on. Group and Essentials are not supported.
A Salesforce user with the “Modify All Data” permission to authorize the connection.
Step 1: Connect Salesforce to TimelinesAI
Log into your Salesforce account in the same browser.
In TimelinesAI, open Salesforce from the Integrations menu in the left sidebar.
Click Connect to Salesforce.
A Salesforce authorization window opens — authorize the app. Once authorized, the window closes and TimelinesAI automatically refreshes to the Connected state.
Note: Once an Owner or Admin establishes the connection, chats from all connected WhatsApp accounts in the same TimelinesAI workspace sync to Salesforce.
If authorization fails: make sure you’re logged into the correct Salesforce org in the same browser, and that the connecting user has the “Modify All Data” permission.
Step 2: Configure Sync Settings
After connecting, the Connected state shows your connection details (Salesforce org, authorizing Salesforce user, connecting TimelinesAI user, connection date) and these settings:
Target Objects — choose which Salesforce objects to match against: Leads, Contacts, Opportunities.
Auto-create Leads — when on, unknown numbers create a new Lead. (Available only when Leads is an enabled target.)
Sync Attachments — when on, WhatsApp files upload to Salesforce as native files. Off by default to protect your Salesforce storage.
Sync Group Chats — when on, WhatsApp group conversations sync. Requires the “Customize Application” permission on the connecting Salesforce user; if that permission is missing, this toggle is disabled with an explanation.
Step 3: Invite Team Members
Open the Team tab in the Salesforce integration settings to give your Salesforce users access:
The tab lists your Salesforce users with a status: Uninvited, Invited, or Active.
Click Send Invite for a user to send them an invitation to join your TimelinesAI workspace (this also grants the Salesforce permissions the integration needs).
Their status moves to Invited, then Active once they accept.
Use Cancel invitation to revoke access — historical synced data is preserved.
Seat availability is shown at the top (e.g. “Seats Used: 4/10”). If you’re at capacity, Send Invite is disabled until you add seats. Use Manage Seats to open your TimelinesAI Team settings.
How Messages Appear in Salesforce
WhatsApp conversations are stored as a daily Task on the matched record. Each line in the Task includes:
Timestamp — in
HH:MM UTC±X, converted to your Salesforce org timezone.Direction —
[Incoming]or[Outgoing].Sender name — the contact’s name for incoming messages; the agent’s name for outgoing (for group chats,
Participant Name / Phone).Message body.
Each Task also starts with a “Visit chat in TimelinesAI” link that opens the conversation in TimelinesAI.
What syncs: text messages; attachments (when enabled); group chats (when enabled); reactions as standalone text entries.
What doesn’t sync: message edits, deletions, and reply/forward metadata (only the raw text is synced).
Note on attachments: When Sync Attachments is off (the default), the file itself isn’t uploaded to Salesforce — instead the Task line includes a link back to the media in TimelinesAI, so the conversation record stays complete without using your Salesforce storage.
The Sync Audit Log
The Salesforce settings page includes a Sync Audit Log — a table of every processed message showing:
Timestamp, Status (Synced / Skipped / Failed / Degraded), Event Type, the WhatsApp chat/contact, the linked Salesforce record, and details/error reason.
Search and filter by status, chat name, phone/JID, or chat ID.
Export the full log for offline review.
It’s the first place to look if you expect something to have synced and it didn’t.
Upgrading from the Previous Salesforce Integration
If you previously connected Salesforce using the older integration, you’ll be prompted to move to the new version. The upgrade is a quick one-time reconnect:
Open the Salesforce integration settings in TimelinesAI.
Disconnect your existing connection.
The page refreshes to the new connection screen — reconnect using the steps in Step 1 above.
Your previously synced Salesforce data is preserved — disconnecting does not delete anything in Salesforce. Reconnecting simply switches you to the new, more capable integration.
Managing the Connection
Download Sync Audit Log — export the full log.
Disconnect — stops all sync going forward; already-synced data in Salesforce is preserved. To connect a different Salesforce org, disconnect first, then reconnect (one org per workspace).
Automatic alerts — if the connection drops (e.g. an expired token or a deactivated Salesforce user), the workspace owner receives an email explaining what to fix.
Troubleshooting
Connection won’t complete → confirm the user has “Modify All Data” and can authorize connected apps; confirm a supported edition; make sure you’re logged into the correct Salesforce org in the same browser.
Messages not syncing → check the connection is active, the target object is enabled, and phone numbers are in international format; check the Sync Audit Log.
Attachments not appearing → attachments are off by default; enable “Sync Attachments”.
Group chats not syncing → enable “Sync Group Chats” (requires “Customize Application”).
For more issues, see Salesforce Integration – Troubleshooting.
Coming Soon
We’re actively building the next phase of the Salesforce integration. These features are not available yet:
WhatsApp chat view inside Salesforce — view and reply to the WhatsApp conversation directly on a Lead, Contact, or Opportunity record page, without leaving Salesforce.
Call logging — WhatsApp calls, including missed calls, logged to Salesforce as call activities for complete communication reporting.
Auto-naming of auto-created Leads — when a Lead is auto-created from an unknown number, its placeholder name updates automatically once you set the contact’s real name in TimelinesAI.
FAQs
Which Salesforce editions are supported? Enterprise, Unlimited, Performance, Developer out of the box; Professional with the API add-on; Group and Essentials are not supported.
Does it create Contacts or Opportunities automatically? No — only Leads are auto-created (and only if you enable it). Contacts and Opportunities are matched, never created.
Are group chats synced? Yes, if you enable the Sync Group Chats toggle.
What happens if my subscription lapses? Connection details are preserved; sync pauses until the subscription is renewed.
Can multiple workspaces connect to one Salesforce org? One Salesforce org per TimelinesAI workspace.