Zoho CRM Integration

What the AI can do

Summary

Zoho CRM Integration connects Zoho CRM (cloud-based CRM platform) with Newo Platform.

It enables:

• Checking real-time appointment availability via Zoho Events
• Booking appointments with automatic contact creation in Zoho CRM
• Cancelling existing appointments (event deletion)
• Automatic deal creation and pipeline stage management based on conversation outcomes
• Lead creation and conversation note tracking for client history
• Contact lookup and deduplication by phone number
• OAuth 2.0 authentication with multi-region support (.com, .eu, .in, .au)

This integration is designed for sales teams, service providers, and business owners who need automated appointment scheduling and CRM synchronization through a conversational AI agent (voice or chat).

Common use cases

• When a client asks about available slots → Query Zoho Events calendar and return free time slots
• When a client wants to book an appointment → Find or create contact, then create calendar event in Zoho CRM
• When a client wants to cancel an appointment → Delete the event from Zoho CRM
• When a conversation ends → Create/update CRM deal with AI-selected pipeline stage
• When a new caller contacts → Create lead in Zoho CRM and attach conversation notes
• When a returning caller contacts → Find existing contact and add conversation summary as note

Features at a glance

Feature	Supported	Notes
Check Availability	✅	Via Zoho Events calendar search
Book Appointment	✅	Creates Zoho Event with contact as participant
Cancel Appointment	✅	Deletes event from Zoho CRM
Contact Lookup	✅	By phone number with auto-normalization
Contact Creation	✅	Automatic during booking if not found
Deal Creation	✅	With pipeline stage and contact link
Deal Stage Update	✅	AI-powered stage selection via LLM (Gemini)
Lead Creation	✅	For new callers on session end
Conversation Notes	✅	Summary + transcript attached to contact
Multi-Region Support	✅	.com, .eu, .in, .au Zoho datacenters
OAuth 2.0 Token Management	✅	Auto-refresh with retry on 401
Silent Availability Preload	✅	Optional check on conversation start
Configurable Slot Duration	✅	Default 30 min
Multi-Location Support	❌	Single calendar/user per instance
Reschedule Appointment	❌	Cancel + rebook as workaround

Before You Start

Before installation:

• Active Zoho CRM account
• OAuth 2.0 authorization via Newo's registered app
• Zoho account region (.com, .eu, .in, or .au)

Setup

Create the Newo project

If this project already exists in Newo Builder, skip this subsection and continue with the integration-specific settings below.

1. In Newo Builder, open the projects list and click Create Project (or Create New Project from the top-right menu).

2. Fill IDN and Title. The exact names do not matter; use any clear names your team will recognize.
3. In Registry, choose the release channel:
   • staging — the newest module fixes appear here first. Use it when you need the latest fix, but expect possible unfinished changes.
   • production — the final stable version for live projects.
4. In Module, select the module for this integration.

5. Leave Module version on Latest version unless support tells you to pin a specific version, then click Create.

3.1 Step 1 — Authorize in Zoho CRM

1. In Newo platform, set zoho_region to your Zoho datacenter region
2. Click the Zoho authorization link provided by the platform
3. Authorize the Newo app in your Zoho CRM account
4. Grant the requested scopes (CRM org, settings, users, modules, etc.)
5. Copy the authorization code from the redirect URL
6. Paste the code into the zoho_oauth_code attribute

3.2 Step 2 — Connect in Platform

1. Open Newo → Projects
2. Set the following attributes in Builder / Attributes:

Attribute	Required	Description
zoho_oauth_code	✅	One-time OAuth authorization code
zoho_region	✅	Zoho datacenter: .com, .eu, .in, .au (default: .com)
zoho_timezone	❌	Appointment timezone (default: project timezone)
zoho_duration	❌	Slot duration in minutes (default: 30)
zoho_availability_days	❌	Days ahead for availability search
zoho_enable_slot_check	❌	Enable availability checking (default: True)
zoho_enable_booking	❌	Enable booking capability (default: True)
zoho_enable_cancellation	❌	Enable cancellation capability (default: True)
zoho_update_pipeline	❌	Enable auto deal stage updates (default: False)
zoho_pipeline_criteria	❌	Custom business rules for AI stage selection
zoho_check_existing_client	❌	Verify client exists before booking (default: True)
zoho_check_availability_on_conversation_start	❌	Auto-check slots on session start (default: False)

3. Click Save + Publish All
4. On publish, the SetupFlow automatically:
   • Exchanges the OAuth code for access and refresh tokens
   • Fetches Zoho CRM users and auto-selects the owner
   • Fetches deal field definitions and pipeline stages
   • Injects booking and availability payload schemas for the agent

How to use the integration

This section explains how the integration works, how to configure automation, and how to test it.

4.1 How the Integration Works

The integration combines scheduling (Events) and CRM (Contacts, Deals, Leads, Notes) capabilities via the event-driven system.

• A Trigger is a system event that starts a flow
• An Action is the API operation performed in Zoho CRM

Where to test

Testing can be done through the Newo conversation interface (chat or voice channel) by interacting with the agent. The GetOrCreateContactFlow also has a dedicated webhook test endpoint (goc_wh).

How to test that everything works

To test the integration:

1. Setup: Publish the project and verify logs show successful OAuth token exchange, user fetch, and deal stages fetch
2. Availability: Ask the agent "What slots are available this week?" — verify free slots calculated from Zoho Events calendar
3. Booking: Complete a booking conversation — verify:
   • Contact created/found in Zoho CRM
   • Calendar event created with correct time and participant
4. Cancellation: Cancel an appointment — verify event deleted from Zoho CRM
5. Client History: After a conversation ends, verify:
   • Contact note added with summary and transcript
   • Lead created if contact didn't exist
6. Pipeline: If zoho_update_pipeline is enabled, verify deal stage updated based on conversation outcome

If no action occurs:

• Ensure OAuth tokens were obtained (check zoho_access_token is not empty)
• Verify zoho_region matches your Zoho datacenter
• Confirm the OAuth code hasn't expired (codes are single-use)
• Check that feature flags are enabled (zoho_enable_booking, zoho_enable_slot_check, zoho_enable_cancellation)
• Verify zoho_user_id was populated during setup
• Re-publish the project if credentials were changed

Note: This integration performs real operations in Zoho CRM. Contacts, events, deals, leads, and notes created through the agent are reflected in the live CRM system.

FAQ

Q: Does the integration import historical CRM data? A: No. Only appointments and records created after activation are managed. Client history flow creates notes for new conversations only.

Q: Can I connect multiple Zoho CRM accounts? A: Each integration instance supports one Zoho account and user. For multiple accounts, create separate integration instances.

Q: Which Zoho regions are supported? A: All four Zoho datacenters: .com (US), .eu (Europe), .in (India), .au (Australia). Set the zoho_region attribute to match your account's datacenter.

Q: How does the AI select the deal pipeline stage? A: After each conversation, an LLM (Gemini) analyzes the conversation summary, outcome success, detailed steps, and transcript. It applies custom business rules from zoho_pipeline_criteria and selects the most appropriate deal stage. The decision includes an explanation.

Q: What happens if a contact already exists in Zoho? A: The integration searches contacts by phone number. If found, the existing contact is used for booking and notes are appended. If not found, a new contact is created automatically.

Q: How does availability checking work? A: The integration queries Zoho Events within a date range and calculates free time slots by finding gaps between existing events. Slot duration is configurable via zoho_duration (default: 30 minutes).

Q: What happens if the OAuth token expires? A: The integration automatically detects HTTP 401 responses and refreshes the token using the refresh token. The new access token is persisted and the failed request is retried.

Q: What CRM records are created during a conversation? A: Depending on configuration: Contact (during booking), Event (appointment), Deal (with pipeline stage), Lead (for new callers), and Note (conversation summary attached to contact). Not all are created every time — it depends on which flows are enabled.