upskill-event-manager/includes/zoho/README.md

Zoho CRM Integration Setup Guide

Overview

This integration syncs WordPress Events Calendar data with Zoho CRM, mapping:

• Events → Campaigns
• Users/Trainers → Contacts
• Ticket Purchases → Invoices

Setup Steps

1. Create Zoho OAuth Application

1. Go to Zoho API Console
2. Click "CREATE NEW CLIENT"
3. Choose "Server-based Applications"
4. Fill in details:
   • Client Name: HVAC Community Events Integration
   • Homepage URL: Your WordPress site URL
   • Authorized Redirect URIs:
     • For setup script: http://localhost:8080/callback
     • For WordPress admin: https://your-site.com/wp-admin/edit.php?post_type=tribe_events&page=hvac-zoho-crm
5. Click "CREATE" and save your Client ID and Client Secret

2. Generate Credentials Using Setup Script

The easiest way to set up credentials:

cd wp-content/plugins/hvac-community-events/includes/zoho
php setup-helper.php

Follow the prompts to:

1. Enter your Client ID and Client Secret
2. Open the authorization URL in your browser
3. Grant permissions and copy the authorization code
4. The script will automatically:
   • Exchange the code for tokens
   • Get your organization ID
   • Create the zoho-config.php file

3. Alternative: Manual Setup

If you prefer manual setup:

1. Create zoho-config.php from the template:

   cp zoho-config-template.php zoho-config.php
   

2. Generate authorization URL:

   https://accounts.zoho.com/oauth/v2/auth?
   scope=ZohoCRM.settings.all,ZohoCRM.modules.all,ZohoCRM.users.all&
   client_id=YOUR_CLIENT_ID&
   response_type=code&
   access_type=offline&
   redirect_uri=http://localhost:8080/callback
   

3. Exchange code for tokens using cURL:

   curl -X POST https://accounts.zoho.com/oauth/v2/token \
     -d "grant_type=authorization_code" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "redirect_uri=http://localhost:8080/callback" \
     -d "code=YOUR_AUTH_CODE"
   

4. Get organization ID:

   curl -X GET https://www.zohoapis.com/crm/v2/org \
     -H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"
   

5. Update zoho-config.php with your credentials

4. WordPress Admin Setup

After creating the config file:

1. Go to WordPress Admin → Events → Zoho CRM
2. The integration will automatically detect your configuration
3. Click "Test Connection" to verify
4. Click "Create Custom Fields" to set up required fields in Zoho

Required Permissions

The integration needs these Zoho CRM scopes:

• ZohoCRM.settings.all - For creating custom fields
• ZohoCRM.modules.all - For reading/writing records
• ZohoCRM.users.all - For user information
• ZohoCRM.org.all - For organization details (optional)

Security Notes

• NEVER commit zoho-config.php to version control
• Keep your refresh token secure
• The integration automatically handles token refresh
• All API calls are logged for debugging (disable in production)

Troubleshooting

Common Issues

1. "Invalid Client" Error

   • Verify Client ID and Secret are correct
   • Ensure redirect URI matches exactly

2. "Invalid Code" Error

   • Authorization codes expire quickly (< 1 minute)
   • Generate and use immediately

3. "No Refresh Token" Error

   • Make sure access_type=offline in auth URL
   • Include prompt=consent to force new refresh token

Debug Mode

Enable debug logging in zoho-config.php:

define('ZOHO_DEBUG_MODE', true);
define('ZOHO_LOG_FILE', WP_CONTENT_DIR . '/zoho-crm-debug.log');

Check the log file for detailed API responses.

Support

For issues or questions:

1. Check the debug log
2. Verify credentials in Zoho API Console
3. Ensure all required modules are enabled in Zoho CRM