This guide walks you through setting up and using the TimelinesAI and SugarAI (formerly SugarCRM) integration. With this integration, your WhatsApp conversations are automatically synchronized into your SugarAI instance, and your team can view and send WhatsApp messages directly from SugarAI Contact pages.
What the Integration Does
With TimelinesAI's SugarAI integration, you can:
Sync WhatsApp messages to SugarAI Contacts — incoming and outgoing WhatsApp conversations are automatically written to SugarAI as message records linked to the matching Contact
View and send WhatsApp messages inside SugarAI — an embedded Chat View on each Contact page lets your team read and reply to WhatsApp conversations without leaving SugarAI
Sync attachments — files, images, and voice messages are uploaded to SugarAI and linked within the conversation transcript
Invite team members — the integration admin can invite additional SugarAI users so they can access Chat View from within their own SugarAI sessions
How the Integration Works
When the SugarAI integration is connected and a new WhatsApp message is sent or received in a direct (1-to-1) chat, TimelinesAI:
Looks up the WhatsApp contact's phone number across all Contact phone fields in SugarAI
If a matching Contact is found — syncs the message to that Contact's message record
If no matching Contact is found — skips the message (no Contacts or Leads are auto-created). The skip is logged in the sync audit log for troubleshooting
Messages are aggregated into 24-hour conversation windows per chat, so SugarAI is not overwhelmed with individual message records
Tip: Save all SugarAI Contact phone numbers in international format (+country code...) without any non-numeric symbols or whitespaces to ensure reliable matching. If an exact match isn't found, a fallback lookup using the last 7 digits of the phone number is attempted.
Prerequisites
Before you begin, make sure you have:
✅ An active TimelinesAI workspace on an Integration plan
✅ You are the owner or admin of the TimelinesAI workspace
✅ Admin access to your SugarAI instance
✅ SugarAI admin credentials (username and password for a SugarAI user with admin privileges)
✅ Your SugarAI instance base URL (the URL you use to access your SugarAI instance)
✅ At least one free webhook slot in your TimelinesAI workspace
Step 1: Install the TimelinesAI Custom Module Package in SugarAI
The integration requires a custom module package to be installed in your SugarAI instance. This package adds the data structures and server-side components that TimelinesAI needs to sync messages, store attachments, and power the embedded Chat View.
Log in to TimelinesAI as a workspace owner or admin
Open SugarAI from the Integrations menu in the left sidebar
On the setup page, click the download link for the TimelinesAI Module Package
Save the
.zipfile to your computerLog in to your SugarAI instance as an administrator
Navigate to Admin → Module Loader
Upload the downloaded
.zipfile and install it
Add the TimelinesAI Chat View dashlet to the Contacts page
After installing the module package, you need to add the Chat View dashlet to the Contacts page so your team can access WhatsApp conversations from within SugarAI. This is a one-time configuration that applies to all users in your SugarAI instance.
Open any Contact record in SugarAI
Click the hamburger menu (☰) on the Contact page
Select Add Dashlet
Choose TimelinesAI Chat View from the list of available dashlets
Save the layout
Step 2: Connect SugarAI to TimelinesAI
Once the custom module package is installed in your SugarAI instance:
In TimelinesAI, open SugarAI from the Integrations menu
Click Connect SugarAI
Enter the required connection details:
SugarAI instance URL — the base URL of your SugarAI instance
SugarAI admin username
SugarAI admin password
Click Connect
TimelinesAI will validate API compatibility and verify that the custom module package is correctly installed. If validation fails, you will see an actionable error message explaining what needs to be fixed
On success, the page transitions to the Connected state showing your connection details
Connection Details
After connecting, the integration settings page displays:
Field | Description |
SugarAI Instance | Base URL of the connected SugarAI instance |
Connected By | TimelinesAI user who established the connection (name and email) |
SugarAI User | SugarAI user used for the connection (name and email) |
Connected Since | Date and time the connection was established |
These details are read-only and provided for transparency and auditability.
Step 3: Invite Team Members
After connecting, you can invite additional team members so they can use the embedded Chat View inside SugarAI.
In the SugarAI integration settings, go to the Team Members tab
Enter the team member's email address and click Send Invite
The invited user will receive an email invitation to join your TimelinesAI workspace
Once they accept the invitation, their status changes from Invited to Active
Requirements for Chat View Access
For a team member to use the embedded Chat View in SugarAI, they must:
Have a SugarAI user with the same email address as a TimelinesAI user in the connected workspace
Be logged in to SugarAI
Users who don't meet these conditions will see an instructional message when attempting to access Chat View.
Note: A personal WhatsApp account is not strictly required to use Chat View — team members can chat on behalf of other users by selecting chats belonging o other connected WhatsApp accounts. A personal account is only needed if the user wants to sync messages from their own WhatsApp account or send messages from their own number.
Seat Management
The Team Members page shows how many seats are used out of the total available in your workspace
If you're at capacity, you'll need to upgrade your plan before inviting more users
Step 4: Verify the Integration
After connecting, you can verify that messages are syncing correctly:
Send a test WhatsApp message to or from a phone number that exists as a Contact in SugarAI
Wait a few moments for synchronization
Open the matching Contact in SugarAI
Check for a new Messages record containing the conversation transcript
The connected state dashboard also shows sync statistics:
Last sync — timestamp of the most recent message sync
Messages synced today — count of messages synchronized
Contacts matched — number of Contacts that received messages
How Messages Appear in SugarAI
WhatsApp conversations are stored in SugarAI as message records linked to the matching Contact. Messages are grouped into 24-hour conversation windows per chat (based on your TimelinesAI workspace timezone), so each record contains a day's worth of conversation rather than individual messages.
Each message entry within the transcript includes:
Timestamp — in HH:MM format, converted to your workspace timezone
Sender name — for outgoing messages, the name of the TimelinesAI user who sent it; for incoming messages, the SugarAI Contact name
Message body — the text content of the message
Attachments — displayed as clickable links with the original filename, pointing to the file stored in SugarAI
Each message record also includes a "Visit chat in TimelinesAI" link that opens the corresponding WhatsApp chat in the TimelinesAI interface.
What Syncs
Text messages, attachments (images, files, voice messages), and locations
Only 1-to-1 WhatsApp conversations — group chats are not synced
Emoji reactions are synced as standalone message entries
What Doesn't Sync
Group chat messages
Message metadata such as replies, forwards, deletions, and edit history
Using Chat View Inside SugarAI
The embedded Chat View lets you read and send WhatsApp messages directly from a SugarAI Contact page, without switching to the TimelinesAI interface.
Open a Contact page in SugarAI
Locate the TimelinesAI Chat View dashlet (added during setup in Step 1)
Chat View shows all WhatsApp chats associated with the Contact's phone numbers
You can read the full conversation history and send new messages directly
Note: Chat View only displays chats associated with phone numbers belonging to the current Contact. Your access is governed by the same permissions you have in TimelinesAI.
Phone Number Matching
TimelinesAI matches WhatsApp messages to SugarAI Contacts by phone number. For best results, store phone numbers in your SugarAI Contacts in international format (e.g., +12345678900).
If an exact match isn't found, TimelinesAI performs a fallback lookup using the last 7 digits of the phone number. If multiple Contacts match, the most recently updated Contact is selected.
Managing the Connection
Viewing Sync Logs
The integration provides a downloadable sync audit log that records the outcome of every processed message:
In the SugarAI integration settings, click View sync log or navigate to the audit log section
You can see which messages were synced, which were skipped (and why), and which Contacts were matched
Use the Export feature to download logs as a file for offline review or troubleshooting
Exports are retained for 30 days after generation.
Disconnecting
To disconnect the SugarAI integration:
In TimelinesAI, open SugarAI from the Integrations menu
Click Disconnect
Confirm in the dialog
Important: Disconnecting stops all message synchronization going forward. Messages and attachments already synced to SugarAI are not deleted.
Replacing the Connection
To connect to a different SugarAI instance:
Click Disconnect to remove the current connection
Follow Steps 1–2 above to install the module package on the new instance and connect
Only one SugarAI instance can be connected per TimelinesAI workspace at a time.
Advanced Workflows with Workflow Builder
Beyond automatic message sync and Chat View, you can build advanced automation workflows between SugarAI and WhatsApp directly inside TimelinesAI using the built-in Workflow Builder — no code or third-party tools required.
Example use cases:
Automatically create or update a SugarAI Contact when a new WhatsApp message arrives
Send a welcome WhatsApp message when a new Contact or Lead is created in SugarAI
Add a Note in SugarAI with WhatsApp message details for record-keeping
Trigger WhatsApp notifications based on changes to SugarAI Accounts or Notes
Workflow Builder supports SugarAI triggers (Watch Contacts, Leads, Accounts, Notes) and actions (Create, Update, Search, and Get records) across all four modules.
For the full list of available triggers, actions, and step-by-step setup instructions, see SugarAI Integration in Workflow Builder.
Troubleshooting
Messages are not syncing
Check the connection status — make sure the SugarAI connection is active in the integration settings
Check your plan — the SugarAI integration requires an Integration plan
Check the sync log — review the audit log for skipped messages and the reasons they were skipped. If the audit log has no entries at all, the integration may not be receiving message events — go to the Webhooks section in TimelinesAI and verify that the SugarAI webhook is present and active
Verify phone numbers — ensure the Contact in SugarAI has the phone number saved in international format
Chat View shows "not authorized" or an instructional message
The user's SugarAI email must match a TimelinesAI user in the connected workspace
The user must be logged in to SugarAI
If the user needs to message from their own WhatsApp account, they must have a personal TimelinesAI account — invite them via the Team Members page
Chat View dashlet is not visible on the Contact page
The dashlet must be added manually after installing the module package (see Step 1)
This is a one-time setup per SugarAI instance — once added, all users will see it
Connection fails with a module validation error
Ensure you have installed the TimelinesAI custom module package in SugarAI (Step 1)
Verify you used the module package downloaded from your TimelinesAI setup page (not from another environment)
Check that the module installation in SugarAI completed without errors
Contact not matched
Verify the Contact's phone number in SugarAI is in international format (e.g.,
+12345678900)Remember that only Contacts are matched — Leads are not in scope for this integration
FAQs
Which SugarAI plan is required?
The integration works with SugarAI instances that support custom module installation via Module Loader and REST API access. Check with your SugarAI account representative if you're unsure whether your edition supports these features.
Can I sync messages to Leads?
No. The SugarAI integration only syncs to Contacts. Leads are not in scope. No Contacts or Leads are auto-created by the integration.
What happens when my TimelinesAI trial ends or subscription lapses?
Your connection details are preserved, but message synchronization pauses until your TimelinesAI subscription is renewed.
Can multiple TimelinesAI workspaces connect to the same SugarAI instance?
No. Each TimelinesAI workspace can connect to exactly one SugarAI instance, and each SugarAI instance should be connected to only one TimelinesAI workspace.
Are group chats synced?
No. Only 1-to-1 WhatsApp conversations are synchronized to SugarAI.