177 lines
4.9 KiB
Markdown
177 lines
4.9 KiB
Markdown
# Zoho CRM Setup Guide for Queue North Admins
|
||
|
||
This guide walks you through setting up Zoho CRM integration to automatically capture leads and support cases from Queue North's website.
|
||
|
||
---
|
||
|
||
## 🔒 Prerequisites
|
||
|
||
Before you begin, ensure you have:
|
||
- A Zoho CRM account (admin access required)
|
||
- Access to Zoho API Console: https://api-console.zoho.com
|
||
|
||
---
|
||
|
||
## Step 1: Create a Zoho Self-Client App
|
||
|
||
1. Go to **https://api-console.zoho.com**
|
||
2. Click **"Create Self Client"**
|
||
3. Fill in:
|
||
- **Client Name**: Queue-North-Zoho-Integration
|
||
- **Description**: Auto-capture leads and cases from Queue North website
|
||
- **Redirect URI**: `https://www.zoho.com` (required for Self-Client, not used)
|
||
4. Click **Create**
|
||
5. **Copy and save**:
|
||
- **Client ID**
|
||
- **Client Secret**
|
||
|
||
> ⚠️ Store these securely — they're like a username and password.
|
||
|
||
---
|
||
|
||
## Step 2: Generate an Authorization Code
|
||
|
||
1. In the Self Client tab, click **"Generate Code"**
|
||
2. Set the **Scope** to:
|
||
```
|
||
ZohoCRM.modules.leads.CREATE,ZohoCRM.modules.leads.READ,ZohoCRM.modules.cases.CREATE,ZohoCRM.modules.cases.READ
|
||
```
|
||
3. Set **Expiry** to **10 minutes** (use it quickly)
|
||
4. Click **Generate**
|
||
5. **Copy the authorization code** — it expires in 10 minutes
|
||
|
||
---
|
||
|
||
## Step 3: Exchange Auth Code for Tokens
|
||
|
||
Run this `curl` command (replace placeholders):
|
||
|
||
```bash
|
||
curl -X POST https://accounts.zoho.com/oauth/v2/token \
|
||
-d "code=<YOUR_AUTH_CODE>" \
|
||
-d "client_id=<YOUR_CLIENT_ID>" \
|
||
-d "client_secret=<YOUR_CLIENT_SECRET>" \
|
||
-d "grant_type=authorization_code" \
|
||
-d "redirect_uri=https://www.zoho.com"
|
||
```
|
||
|
||
**Response will include:**
|
||
```json
|
||
{
|
||
"access_token": "1000.xxxxx.xxxxx",
|
||
"refresh_token": "1000.yyyyy.yyyyy",
|
||
"expires_in": 3600,
|
||
"token_type": "bearer"
|
||
}
|
||
```
|
||
|
||
**Save the `refresh_token`** — this never expires and must be kept secret.
|
||
|
||
---
|
||
|
||
## Step 4: Configure Environment Variables
|
||
|
||
Add these to your `.env` file:
|
||
|
||
```env
|
||
ZOHO_ENABLED=true
|
||
ZOHO_API_DOMAIN=https://www.zohoapis.com
|
||
ZOHO_ACCOUNTS_DOMAIN=https://accounts.zoho.com
|
||
ZOHO_CLIENT_ID=<from Step 1>
|
||
ZOHO_CLIENT_SECRET=<from Step 1>
|
||
ZOHO_REFRESH_TOKEN=<from Step 3>
|
||
ZOHO_CASES_ENABLED=true
|
||
```
|
||
|
||
### Datacenter Variants
|
||
|
||
If your Zoho datacenter is **outside the US**, adjust the domains:
|
||
|
||
| Region | API Domain | Accounts Domain |
|
||
|--------|-----------|-----------------|
|
||
| US | `www.zohoapis.com` | `accounts.zoho.com` |
|
||
| EU | `www.zohoapis.eu` | `accounts.zoho.eu` |
|
||
| IN | `www.zohoapis.in` | `accounts.zoho.in` |
|
||
| AU | `www.zohoapis.com.au` | `accounts.zoho.com.au` |
|
||
|
||
---
|
||
|
||
## Step 5: Test the Integration
|
||
|
||
### Test Lead Capture
|
||
1. Submit a lead on the contact form (name, email, phone, message)
|
||
2. Wait ~5–10 seconds
|
||
3. Log in to Zoho CRM → Leads tab
|
||
4. Verify the new lead appears with correct data
|
||
|
||
### Test Case Capture
|
||
1. Submit a support request (e.g., booking inquiry, technical question)
|
||
2. Wait ~5–10 seconds
|
||
3. Log in to Zoho CRM → Cases tab
|
||
4. Verify the new case appears with correct data
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### Token Errors
|
||
- **"invalid_grant"**: Your authorization code expired. Generate a new one in Step 2 and repeat Step 3.
|
||
- **"invalid_client"**: Double-check Client ID and Secret — no extra spaces.
|
||
- **"invalid_scope"**: Re-run Step 2 with the exact scopes listed above.
|
||
|
||
### Field Mismatches
|
||
- If leads/cases don't appear, check if Zoho requires custom fields like `Service_Interest`
|
||
- Edit the field mapping in `server/zoho/` to match your Zoho CRM field API names
|
||
|
||
### Cases Not Appearing
|
||
- Ensure `ZOHO_CASES_ENABLED=true` is set
|
||
- Verify the Cases tab is enabled in your Zoho CRM plan
|
||
- Check that your Zoho CRM user has **Cases CREATE** permissions
|
||
|
||
### Lead Upsert Behavior
|
||
- Leads are **upserted by email**: duplicate email = update existing lead
|
||
- Cases are **always inserted** (new ticket each time)
|
||
- If you see duplicate leads, check for slight email variations (e.g., `test@` vs `test+1@`)
|
||
|
||
---
|
||
|
||
## Architecture Notes
|
||
|
||
### Flow Overview
|
||
```
|
||
Website Contact Form → SQLite (always saved)
|
||
↓
|
||
Zoho CRM (best-effort)
|
||
↓
|
||
Fire-and-forget (no failure blocking)
|
||
```
|
||
|
||
### OAuth2 Refresh Token Flow
|
||
1. Use `refresh_token` to get a new `access_token` when expired
|
||
2. `access_token` expires in 1 hour
|
||
3. `refresh_token` never expires — store it securely
|
||
|
||
### Upsert Logic
|
||
- **Leads**: Email-based upsert (update if exists, create if new)
|
||
- **Cases**: Always insert (new case per submission)
|
||
|
||
### Fire-and-Forget Design
|
||
- Zoho failures **do not block** form submissions
|
||
- All data is saved to SQLite first
|
||
- Zoho attempts happen in the background
|
||
- No retry logic needed — users won't wait for Zoho
|
||
|
||
---
|
||
|
||
## What Happens Next?
|
||
|
||
After configuration, your team (Ripley + Bishop) will:
|
||
1. Deploy environment variables to production
|
||
2. Run integration tests
|
||
3. Verify data flows to Zoho CRM
|
||
4. Update `PROJECT.md` with the integration status
|
||
|
||
---
|
||
|
||
**Questions?** Contact Ripley (Infrastructure) or Neo (Backend).
|