Skip to main content

Zoho CRM Integration

Connect your Zoho CRM to SuperWaba for real-time bidirectional sync between your WhatsApp contacts and Zoho CRM records. New WhatsApp conversations automatically create Leads in Zoho; changes in Zoho flow back to SuperWaba instantly.

Sync capabilities​

What syncs automatically​

DirectionTriggerWhat happens
SuperWaba → ZohoNew WhatsApp message from unknown numberLead auto-created in Zoho with phone, name, source
SuperWaba → ZohoContact updated in SuperWabaZoho record updated with new fields
Zoho → SuperWabaContact/Lead created in ZohoContact auto-created in SuperWaba
Zoho → SuperWabaContact/Lead edited in ZohoLocal contact updated in real-time
Zoho → SuperWabaContact/Lead deleted in ZohoMapping removed (local contact preserved)

Supported Zoho CRM modules​

ModuleSync supportDescription
LeadsFull (read + write)New WhatsApp contacts are created as Leads by default
ContactsFull (read + write)Converted leads or existing contacts sync bidirectionally
DealsRead-only (inbound)Deal info visible in SuperWaba contact panel
AccountsRead-only (inbound)Company/account info enriches contact profiles

Field mapping​

Outbound: SuperWaba → Zoho​

SuperWaba fieldZoho CRM fieldNotes
nameFirst_Name + Last_NameAutomatically split on whitespace
phonePhonePrimary deduplication field
emailEmailOptional
tags[]TagMapped as Zoho tag objects
sourceLead_SourceSee source mapping table below

Source mapping:

SuperWaba sourceZoho Lead_Source value
whatsappWhatsApp
instagramInstagram
facebookFacebook
messengerFacebook Messenger
livechatWeb Chat
manualManual Entry
campaignCampaign
apiAPI

Inbound: Zoho → SuperWaba​

Zoho CRM fieldSuperWaba fieldNotes
First_Name + Last_NamenameJoined with space
Phone or MobilephonePhone preferred; Mobile as fallback
EmailemailOptional
Tag[].nametags[]Converted to string array
—sourceSet to zoho (prevents sync loops)

Real-time sync via Watch API​

SuperWaba subscribes to Zoho's Watch API for instant change notifications — no polling required.

Subscribed events​

Zoho ModuleEvents monitored
Contactscreate, edit, delete
Leadscreate, edit, delete

How it works​

1. Record changes in Zoho CRM (user creates/edits/deletes)
2. Zoho Watch API sends notification to SuperWaba webhook
3. Webhook fetches full record details from Zoho API
4. Contact is created/updated in SuperWaba database
5. Changes appear in inbox immediately

Watch subscriptions auto-renew every 6 days (max Zoho expiry is 7 days).

Auto-sync: New WhatsApp contacts → Zoho Leads​

Every time a new contact messages your WhatsApp Business number:

1. New WhatsApp message arrives from unknown number
2. Contact record created in SuperWaba (wa_contacts table)
3. Database trigger fires automatically
4. Checks if your org has an active Zoho connection
5. Skips if contact source is 'zoho' (prevents infinite loops)
6. Creates Lead in Zoho via upsert API (deduplicates by phone)
7. Saves mapping for future sync tracking

No manual action required — contacts flow to Zoho in seconds.

Manual sync options​

Push to Zoho (outbound)​

Push existing SuperWaba contacts to Zoho CRM as Leads:

  • Batch upsert: up to 100 contacts per API call
  • Deduplicates by phone number (won't create duplicates)
  • Skips contacts that already have a Zoho mapping

Pull from Zoho (inbound)​

Import Zoho CRM records into SuperWaba:

  • First sync: fetches all Contacts (paginated, up to 10 pages)
  • Incremental sync: only fetches records modified since last sync
  • Deduplicates by phone number

Full sync (bidirectional)​

Runs outbound push followed by inbound pull. Use for initial setup or reconciliation.

Conversation logging​

When enabled, SuperWaba pushes conversation activity to Zoho:

ActivityZoho action
Conversation openedNote added to Lead/Contact
AI agent summary generatedNote added with conversation summary
Conversation closedNote updated with resolution
Labels/tags changedTags synced to Zoho record

Sync loop prevention​

Multiple safeguards prevent infinite sync loops:

  1. Source tagging — Contacts with source = 'zoho' are never pushed back to Zoho
  2. Mapping check — zoho_contact_map table checked before every sync
  3. Zoho upsert dedup — Phone number deduplication as final safety net
  4. Channel ID tracking — Watch notifications include channel ID to identify source

Setup​

Prerequisites​

  • Zoho CRM account (Free, Standard, Professional, or Enterprise)
  • SuperWaba account with WhatsApp connected
  • Admin access to your Zoho organization

Connect steps​

  1. Go to Settings > Integrations > Zoho CRM
  2. Click Connect Zoho CRM
  3. Sign in with your Zoho account and authorize SuperWaba
  4. Grant all requested permissions (Contacts, Leads, Deals, Accounts, Notifications)
  5. Configure sync settings (direction, record type, field mapping)

OAuth permissions requested​

ScopePurpose
ZohoCRM.modules.contacts.ALLRead/write Contacts
ZohoCRM.modules.leads.ALLRead/write Leads
ZohoCRM.modules.deals.ALLRead Deals
ZohoCRM.modules.accounts.ALLRead Accounts
ZohoCRM.settings.modules.READRead module metadata
ZohoCRM.notifications.ALLWatch API for real-time sync

Multi-region support​

Zoho operates across multiple data centers. SuperWaba automatically detects and stores your region:

RegionSupported
US (zoho.com)Yes
EU (zoho.eu)Yes
India (zoho.in)Yes
Australia (zoho.com.au)Yes
Japan (zoho.jp)Yes
Canada (zoho.ca)Yes

Configuration​

SettingOptionsDescription
Sync directionOne-way out, One-way in, Two-wayControls which direction data flows
Default record typeLead or ContactWhere new WhatsApp contacts land in Zoho
Auto-createOn/OffAutomatically create Zoho records for new conversations
Conversation loggingOn/OffPush conversation notes to Zoho records
Field mappingCustomMap SuperWaba fields to any Zoho custom fields

Rate limits & optimization​

Zoho API limits (per day, per Zoho org)​

Zoho PlanDaily API credits
Free5,000
Standard50,000 + 250/user
Professional50,000 + 500/user (max 3M)
Enterprise50,000 + 1,000/user (max 5M)

How SuperWaba minimizes API usage​

OptimizationEffect
Batch upserts (100 records/call)1 credit per batch, not per record
In-database connection checkNo HTTP call if no Zoho connection
Source filteringPrevents credit waste from sync loops
Incremental syncOnly syncs records modified since last run
Phone dedup on upsertPrevents duplicate record creation

Disconnect​

To disconnect Zoho CRM:

  1. Go to Settings > Integrations > Zoho CRM
  2. Click Disconnect
  3. This will:
    • Revoke the OAuth refresh token at Zoho
    • Deactivate the connection in SuperWaba
    • Stop all Watch API notifications
    • Preserve existing contact mappings (re-usable if you reconnect)

Troubleshooting​

IssueSolution
Zoho changes not appearingCheck Watch API subscription is active in Settings
New contacts not syncing to ZohoVerify auto-sync is enabled and connection is active
Duplicate records in ZohoEnsure phone numbers include country code (E.164 format)
OAuth connect failsCheck that redirect URI matches exactly in Zoho API Console
Token refresh errorsDisconnect and reconnect — refresh tokens may be revoked
Wrong Zoho regionDisconnect and reconnect from the correct region