Zoho CRM Setup

Overview

This guide walks you through connecting Zoho CRM to VeloPBX via OAuth 2.0. Unlike HubSpot, Zoho hosts your data in regional data centers — and the integration credentials must match the region your Zoho account lives in. This is the single most common cause of failed Zoho integrations, so we’ll cover it explicitly.

Setup time: ~12 minutes. Tenant admin only.

By the end of this guide, every inbound and outbound call placed by extensions in your tenant will:

• Match against contacts, leads, and accounts in Zoho CRM
• Pop the matched record in PortSIP ONE before the call connects
• Auto-log a call activity (with recording and optional AI transcript) on the matched record

Prerequisites

Before you start, make sure you have:

• A Zoho CRM subscription on Standard, Professional, Enterprise, or Ultimate edition (Free edition is not supported — Zoho’s API access requires a paid tier)
• A Zoho user account with permission to create developer apps in your Zoho org
• The region your Zoho account lives in (more on this below)
• Tenant Admin Full Access in VeloPBX

Critical: identify your Zoho region

Zoho hosts customer data in seven regional data centers, and each region uses a different OAuth endpoint, API base URL, and developer console URL. Picking the wrong region is the #1 setup failure.

To find your region:

1. Sign into Zoho CRM at the URL you normally use.
2. Look at the URL bar.

Note your region. You’ll select it in VeloPBX and open the matching Developer Console URL.

Important: If you’ve ever migrated regions (e.g. moved from US to EU for GDPR compliance), use the current region — the one your data is in today, not where it started.

Step 1 — Open the Zoho API Console for your region

Open the Developer Console URL from the table above (matching your region) in a new browser tab. Sign in with your Zoho account.

Step 2 — Create a new self-client / server-based application

1. Click Get Started (or Add Client if you’ve used the console before).
2. Choose Server-based Applications.

Why server-based? PortSIP/VeloPBX runs on your VeloPBX server and exchanges the authorization code for a refresh token server-side. Other client types (JS, mobile) don’t apply here.

Step 3 — Fill in App details

In the Create New Client dialog:

Important: The Redirect URI must include the port your VeloPBX uses (typically :8887 for self-hosted). It must use HTTPS, and the host/port/path must match exactly — no trailing slash, no query strings.

Click Create.

Step 4 — Copy the Client ID and Client Secret

Zoho generates a Client ID and Client Secret for your new app. Copy both values immediately to a secure location.

Important: Treat these as production credentials. Anyone with the Client ID + Client Secret + your tenant’s Redirect URI can impersonate the integration. Store them in your password manager.

You can come back to this screen later if needed (Zoho preserves the values, unlike Odoo’s API keys). But it’s still good practice to copy them now.

Step 5 — Open Integrations in VeloPBX

In a new browser tab, sign into the VeloPBX Web Portal as a tenant administrator at:

https://pbx.fortis-tele.com:8887

In the left navigation, click Integrations, then CRM.

Step 6 — Select Zoho and choose your region

1. From the Select a CRM solution dropdown, choose Zoho.
2. The Zoho configuration form appears.
3. From the Region dropdown, pick your region (the one you identified in the prerequisites).

Critical: The region in VeloPBX must match the region of your Developer Console in Step 1. Mismatch causes “invalid_token” errors during authorization, even when your Client ID/Secret are correct.

Step 7 — Paste credentials and configure settings

1. Paste the Client ID and Client Secret from Step 4.
2. Configure the integration settings (recommended defaults below).
3. Click Save.

VeloPBX stores the credentials but the integration is not active yet — you still need to authorize it.

Step 8 — Authorize the app

1. After saving, an Authorize button appears.
2. Click Authorize. A new browser tab opens with Zoho’s authorization screen for your region.
3. Sign in with the Zoho user account that owns (or has access to) the CRM data you want VeloPBX to read and write.
4. Review the requested scopes — Zoho will list the permissions VeloPBX is asking for (Contacts, Leads, Accounts read/write; calls activity write).
5. Click Accept.
6. Zoho redirects back to VeloPBX with the authorization code, which VeloPBX exchanges for a refresh token. The integration becomes active immediately.

Step 9 — Configure integration settings

Recommended defaults:

Save your settings.

Verify it works

1. Place an outbound call from any extension in your tenant to a phone number that exists in your Zoho contacts, leads, or accounts.
2. The matched record should pop in PortSIP ONE during the call.
3. After the call ends, open the record in Zoho:

• The Activities section should show a new Call entry with duration, direction, and outcome.
• If recording is enabled, the activity has a recording link.
• If AI transcription is enabled at the tenant level, the transcript appears on the activity.

Settings reference

Once connected, all settings can be edited any time on Integrations → CRM → Zoho at https://pbx.fortis-tele.com:8887. Changes take effect on the next call.

Troubleshooting

“invalid_client” or “invalid_token” during authorization

Almost always a region mismatch. Verify:

• The Developer Console you used in Step 1 matches your data region (check the URL bar of your Zoho CRM).
• The Region dropdown in VeloPBX matches the same region.

If both match and the error persists, regenerate the Client Secret in Zoho’s API Console and re-paste into VeloPBX.

“redirect_uri_mismatch”

The Redirect URI in your Zoho app must match what VeloPBX sends, byte-for-byte. Common causes:

• Trailing slash mismatch (/callback/zoho/ vs /callback/zoho)
• HTTP vs HTTPS
• Port number missing or wrong
• Different host/subdomain

Edit the Authorized Redirect URIs in Zoho’s API Console and re-authorize.

“Free edition not supported”

Zoho’s CRM API is gated to paid tiers (Standard / Professional / Enterprise / Ultimate). The Free edition exposes a CRM UI but no API. Upgrade to Standard or higher to use this integration.

Calls aren’t matching contacts

• Verify phone numbers in Zoho are stored in E.164 format (e.g. +37491223344).
• Check Contact lookup order — Zoho stores phone numbers across Contacts, Leads, and Accounts. If your contacts are mostly Leads but the lookup order starts with Contacts, you may want to reorder.

Activities log to wrong record

This usually means the same phone number exists on multiple Zoho records (a Contact and a Lead, for example). Zoho’s lookup hits the first match in your Contact lookup order. Adjust the order to prefer your primary record type.

Refresh token expired

Zoho refresh tokens are long-lived but can be revoked by the user (under Zoho’s Connected Apps page). If the token is revoked, the integration breaks until you re-authorize. Click Disconnect in VeloPBX, then re-authorize from Step 8.

Recording links don’t open

• Confirm Auto-log call recording is enabled.
• If using Secure recording URL, the link expires after the configured TTL — clicking an old link will fail.

FAQ

Do I need a Zoho Enterprise subscription? Standard and above all work. Standard is the cheapest tier that includes API access. Enterprise/Ultimate add features like custom modules and advanced analytics — not required for this integration.

Can multiple VeloPBX tenants connect to the same Zoho org? Yes — each tenant registers its own Zoho self-client app with its own Client ID/Secret. They write activities under the user that authorized them.

What happens if I migrate Zoho regions? Zoho data migrations between regions are rare and typically managed by Zoho support. If your region changes:

1. Disconnect the integration in VeloPBX.
2. Create a new self-client app in the new region’s API Console.
3. Update the Region dropdown in VeloPBX.
4. Re-authorize.

Is the Saudi Arabia region production-ready? Yes. PortSIP supports zoho.sa with the same feature set as other regions. Latency and data residency match regional Zoho infrastructure.

Can I use Zoho Bigin (the SMB CRM) instead of CRM? Zoho Bigin uses a different API surface than Zoho CRM. The current PortSIP integration targets the Zoho CRM API. If your team is on Bigin, contact us — we’ll flag the request for the PortSIP roadmap.

Are AI transcripts billed by VeloPBX? No — AI transcription uses your own Azure Speech / OpenAI / AWS Transcribe credentials (configured separately under Tenant → AI Transcription). VeloPBX does not mark up cloud AI costs.

Need help?

If you get stuck (especially on region selection or OAuth flow), talk to a routing engineer — we can pair on the setup live and have your first matched call running within 24 hours.