Zoho Integrations
Purpose and Scope
This page explains how to enable the Zoho family of Cal.diy integrations for a self-hosted instance: Zoho CRM, Zoho Calendar, and Zoho Bigin. Each integration uses a Zoho server-based application, an OAuth redirect back into the Cal.diy web application, and credentials that must be stored in the correct Cal.diy configuration location. The main reader task is to avoid mixing up three similar provider setups. The callback paths, storage locations, and final user-facing settings pages differ, so copy values carefully and verify each app independently. Sources: apps/docs/content/apps/zoho.mdx
The shared pattern is straightforward: create credentials in the Zoho API Console, register the Cal.diy callback URL as the OAuth redirect, save the resulting client identifier and secret in Cal.diy, enable the optional Multi-DC setting when needed, and then add or manage the integration from the relevant Cal.diy settings area. Treat the Cal.diy base URL as the externally reachable URL that users and Zoho can access, not merely a local container hostname. If the public URL changes, the registered redirect URL in Zoho and the Cal.diy environment or admin configuration should be reviewed together. Sources: apps/docs/content/apps/zoho.mdx
Relevant Source Files
- apps/docs/content/apps/zoho.mdx - The central documentation page for Zoho CRM, Zoho Calendar, and Zoho Bigin setup, including credential names, callback paths, admin paths, and calendar management guidance.
- packages/app-store/zoho-bigin/README.md - The app-store package README for Zoho Bigin, confirming the OAuth callback and the required app-store environment variable names.
- packages/app-store/zohocalendar/README.md - The app-store package README for Zoho Calendar, confirming the callback path, admin app-key storage location, calendar settings path, and double-booking note.
Integration Matrix
| Integration | OAuth callback path | Credential storage | Where users finish setup |
|---|---|---|---|
| Zoho CRM | /api/integrations/zohocrm/callback | .env with ZOHOCRM_CLIENT_ID and ZOHOCRM_CLIENT_SECRET | Cal.diy settings after credentials are configured |
| Zoho Calendar | /api/integrations/zohocalendar/callback | Admin app keys at <Cal.diy>/settings/admin/apps | /settings/my-account/calendars |
| Zoho Bigin | /api/integrations/zoho-bigin/callback | .env.appStore with ZOHO_BIGIN_CLIENT_ID and ZOHO_BIGIN_CLIENT_SECRET | Cal.diy app store |
Zoho API Console Flow
Start in the Zoho API Console by signing in or creating an account. For these integrations, choose a server-based application rather than a browser-only or client-only application, because Zoho must redirect users back to a server route in Cal.diy after authorization. For CRM and Bigin, the docs explicitly describe using the ADD CLIENT action and selecting Server-based Applications. For Zoho Calendar, the package README gives the same application type requirement and asks you to set the redirect during creation. Sources: apps/docs/content/apps/zoho.mdx, packages/app-store/zohocalendar/README.md, packages/app-store/zoho-bigin/README.md
When entering the redirect URL, replace the placeholder Cal.diy URL with the URI where your instance actually runs. A local development address can work only for a local OAuth test when Zoho can reach the redirect, while a deployed instance needs the public HTTPS application URL used by users. Do not reuse the CRM callback for Bigin or Calendar, because the path segment identifies the integration handler that receives the OAuth response. After creating the client, open the Client Secret tab, copy the generated credentials, and save or update the Zoho client before leaving the console. Sources: apps/docs/content/apps/zoho.mdx
Credential Storage by App
Zoho CRM is configured through environment variables in the main Cal.diy environment file. The documented variable names are ZOHOCRM_CLIENT_ID and ZOHOCRM_CLIENT_SECRET, and the OAuth redirect must be <Cal.diy URL>/api/integrations/zohocrm/callback. This means the CRM integration behaves like a server-configured provider: the instance operator places secrets in the deployment environment, restarts or redeploys as needed, and then users can add Zoho CRM from the Cal.diy settings. If credentials are wrong, users may see an authorization failure even though the app appears available. Sources: apps/docs/content/apps/zoho.mdx
Zoho Calendar differs because the documentation instructs operators to copy the Client ID and Client Secret into app keys in the Cal.diy admin panel at <Cal.diy>/settings/admin/apps. After the app keys are present, users manage the calendar connection from /settings/my-account/calendars. The package README reinforces both locations and adds an important operational note: if a user connects multiple calendars, enable the toggle that prevents double-bookings across calendars. This step matters because the OAuth connection only grants access; it does not by itself decide which calendars should block availability. Sources: apps/docs/content/apps/zoho.mdx, packages/app-store/zohocalendar/README.md
Zoho Bigin uses the app-store environment file rather than the main environment file or admin app-key panel. The documented variable names are ZOHO_BIGIN_CLIENT_ID and ZOHO_BIGIN_CLIENT_SECRET, stored in .env.appStore, and the OAuth redirect is <Cal.diy URL>/api/integrations/zoho-bigin/callback. This distinction is easy to miss because Bigin and CRM are both Zoho business applications, but their credential names and file locations are not interchangeable. Once configured, the Bigin integration can be added from the Cal.diy app store. Sources: apps/docs/content/apps/zoho.mdx, packages/app-store/zoho-bigin/README.md
Multi-DC and Callback Details
All three Zoho setup flows mention the Multi-DC option in the Zoho API Console settings. Enable it when you want the same OAuth credentials to work across Zoho data centers. This is especially relevant for self-hosted operators with users in more than one Zoho region, because otherwise a credential may behave correctly for one account and fail for another account hosted in a different data center. Multi-DC is not a replacement for the redirect URL; it only affects the data-center scope of the Zoho OAuth client, so still verify the callback path for each integration. Sources: apps/docs/content/apps/zoho.mdx, packages/app-store/zohocalendar/README.md, packages/app-store/zoho-bigin/README.md
A useful verification sequence is to confirm the Cal.diy base URL, confirm the exact callback path in Zoho, confirm where the credentials were stored, and then test the user-facing flow. For Calendar, open the user calendar settings and check whether the Zoho calendar appears as an available connection. For Bigin, return to the app store and add the integration. For CRM, use the Cal.diy settings path described by the docs after the environment variables are present. If one integration succeeds and another fails, compare the callback path and storage location before regenerating secrets. Sources: apps/docs/content/apps/zoho.mdx
Operational Checklist
- Create a Zoho server-based application for the specific integration you are enabling.
- Register the exact callback path for that integration under your public Cal.diy URL.
- Copy the Client ID and Client Secret from the Zoho Client Secret tab.
- Store CRM credentials in
.env, Calendar credentials in admin app keys, and Bigin credentials in.env.appStore. - Enable Zoho Multi-DC if your instance must support accounts across data centers.
- Save or update the Zoho client configuration before testing OAuth.
- Complete user setup in Cal.diy settings, calendar settings, or the app store as appropriate.
Troubleshooting Notes and Next Steps
Most Zoho integration issues come from configuration drift rather than application code changes. A common example is updating the public application URL after moving a deployment behind a reverse proxy but leaving the old redirect registered in Zoho. Another is placing Bigin credentials into the CRM environment variables because both integrations use Zoho OAuth. Calendar has its own failure mode: the connection can be present while availability is still wrong if users do not configure the calendars that should prevent double booking. Keep an integration-by-integration checklist with the callback, credential location, and final settings page. Sources: apps/docs/content/apps/zoho.mdx, packages/app-store/zohocalendar/README.md, packages/app-store/zoho-bigin/README.md
After enabling Zoho, read the broader app documentation for how Cal.diy app-store integrations are organized, then review deployment URL and reverse-proxy guidance if OAuth redirects do not return to the expected host. Calendar operators should also review booking and availability behavior so connected calendars match the intended scheduling policy. For local development or contribution work, compare these provider-specific README files with the app-store tooling pages before changing credential names or callback paths, because those values are part of the operator-facing configuration contract.