Setup connector

The Zoho Desk connector provides comprehensive access to Zoho's customer service platform, enabling ticket management, agent administration, and file handling capabilities. This guide will walk you through setting up and configuring the Zoho Desk connector.

Zoho Desk is a customer service and support platform that helps teams manage customer inquiries, track tickets, and provide efficient support. The Zoho Desk connector allows Leena AI to automate ticket management, agent operations, and file handling seamlessly.

Overview

The Zoho Desk connector uses OAuth 2.0 authentication to securely connect with Zoho's customer service platform.

Prerequisites

Before setting up the Zoho Desk connector, ensure you have:

1. Access to Zoho API Console (https://api-console.zoho.in/)
2. Zoho Desk administrator privileges
3. Ability to create OAuth 2.0 applications in Zoho
4. Access to your Leena AI workspace with connector management permissions

Setting up the Zoho Desk Connector

Step 1: Access the Integrations Page

1. Log in to your Leena AI workspace
2. Navigate to Settings > Integrations
3. Click on Add Connector
4. Search for "Zoho Desk" and select it from the list

Step 2: Create OAuth 2.0 Application in Zoho

1. Login to Zoho API Console: Go to https://api-console.zoho.in/
2. Create OAuth Client:
   • Click on Add Client button
   • Choose Server based Applications
   • Fill in the form fields:
     • Client Name: Enter a descriptive name (e.g., "Leena AI Integration")
     • Homepage URL: Enter your organization's URL
     • Authorized Redirect URIs: Use the Redirect URI provided by Leena AI (from Step 3)
   • Click the Create button
   • Important: Note the Client ID and Client Secret that are displayed

Step 3: Configure Connection in Leena AI

The Zoho Desk connector uses OAuth 2.0 authentication. You'll need to provide:

Step 4: Configure Connection Settings

Note: Replace <location> in the Base URL with your Zoho data center location (e.g., com, in, eu, com.au, jp).

Step 5: Required Scopes

Configure the following scopes for your Zoho Desk connector:

Step 6: Test Connection

1. After entering all required credentials, click Test Connection
2. If successful, you'll see a green confirmation message
3. If the test fails, verify your OAuth configuration and credentials

Step 7: Save Configuration

1. Once the connection test passes, click Save
2. The Zoho Desk connector is now ready to use in your workflows

Troubleshooting Common Issues

OAuth 2.0 Issues:

• Invalid credentials: Verify Client ID and Client Secret are correct
• Redirect URI mismatch: Ensure the Redirect URI in Zoho matches the one provided by Leena AI
• Authorization failed: Check if the authorization code is valid and not expired
• Scope errors: Ensure all required scopes are added to your Zoho OAuth application

Connection Issues:

• Base URL errors: Verify the correct data center location in the Base URL
• Token refresh failed: Check if your OAuth application has the necessary permissions
• API version mismatch: Ensure you're using the correct API version (v1)

Security Best Practices

1. Client Secret Security: Store Client ID and Client Secret securely
2. Principle of Least Privilege: Only grant necessary scopes to the OAuth application
3. Access Monitoring: Monitor API usage through Zoho admin panels
4. Regular Audits: Review connector permissions and access logs periodically
5. Token Management: Ensure automatic token refresh is working properly

The connector is now ready to be used by your Leena AI Agents for automated customer service and ticket management workflows.

Create a ticket

Creates a new ticket in the organization.

Scope: Desk.tickets.CREATE

Required Parameters

Optional Parameters

Example Usage

Basic Ticket Creation

{
  "organization": "Leena AI Support",
  "subject": "Unable to login to account",
  "department": "Technical Support"
}

Ticket with Full Details

{
  "organization": "Leena AI Support",
  "subject": "Payment processing error",
  "department": "Billing",
  "contact": "[email protected]",
  "description": "Customer experiencing issues with payment processing on checkout page",
  "priority": "High",
  "status": "Open",
  "assignee": "[email protected]",
  "category": "Technical Issue",
  "channel": "Web Form",
  "classification": "Incident"
}

Ticket with Attachments

{
  "organization": "Leena AI Support",
  "subject": "Bug report - UI issue",
  "department": "Development",
  "contact": "[email protected]",
  "description": "Button not responding on mobile view",
  "priority": "Medium",
  "uploads": ["file-id-123"],
  "category": "Bug Report",
  "product": "Mobile App"
}

Ticket with Team Assignment

{
  "organization": "Leena AI Support",
  "subject": "Feature request - Dashboard customization",
  "department": "Product",
  "contact": "[email protected]",
  "description": "Request for custom dashboard widgets",
  "priority": "Low",
  "team": "Product Development Team",
  "classification": "Question",
  "dueDate": "2025-12-31"
}

Response

Upon successful creation, the action returns:

• Ticket ID
• Ticket number
• Subject
• Status
• Created timestamp
• Assignee information
• Department details

Common Use Cases

1. Customer Support: Create tickets from customer inquiries via chat, email, or phone
2. Bug Reporting: Automatically create tickets for reported bugs
3. Service Requests: Generate tickets for internal service requests
4. Incident Management: Create incident tickets for system issues
5. Feature Requests: Track feature requests through ticketing system
6. Automated Workflows: Create tickets from external system triggers

Get a ticket

Retrieves detailed information about a specific ticket.

Scope: Desk.tickets.READ

Required Parameters

Optional Parameters

Example Usage

Get Basic Ticket Info

{
  "organization": "Leena AI Support",
  "ticketId": "12345"
}

Get Ticket with Additional Data

{
  "organization": "Leena AI Support",
  "ticketId": "12345",
  "include": "contacts,products,assignee,departments,team"
}

Get Ticket with Contact Details

{
  "organization": "Leena AI Support",
  "ticketId": "67890",
  "include": "contacts,assignee"
}

Response

The action returns detailed ticket information including:

• Ticket ID and number
• Subject and description
• Status and priority
• Department and team
• Assignee information
• Contact details (if included)
• Product information (if included)
• Created and updated timestamps
• Custom fields
• Attachments

Common Use Cases

1. Status Checking: Allow users to check ticket status via virtual assistant
2. Ticket Details: Retrieve complete ticket information for agents
3. Reporting: Generate reports with detailed ticket data
4. Integration: Sync ticket information with external systems
5. Audit Trail: Review ticket history and changes
6. Customer Updates: Provide customers with ticket progress updates

List all tickets

Retrieves all tickets for the given organization.

Scope: Desk.tickets.READ

Required Parameters

Optional Parameters

Example Usage

List All Tickets

{
  "organization": "Leena AI Support"
}

List Tickets with Pagination

{
  "organization": "Leena AI Support",
  "from": 1,
  "limit": 50
}

List Open Tickets by Department

{
  "organization": "Leena AI Support",
  "departments": ["Technical Support", "Billing"],
  "status": "Open",
  "sortBy": "createdTime",
  "sortOrder": "desc"
}

List High Priority Tickets

{
  "organization": "Leena AI Support",
  "priority": "High",
  "status": "Open",
  "assignee": "[email protected]",
  "limit": 25
}

List Recent Tickets with Filters

{
  "organization": "Leena AI Support",
  "receivedInDays": 7,
  "channel": "Email",
  "include": "contacts,assignee",
  "sortBy": "priority",
  "sortOrder": "desc"
}

List Tickets by Team

{
  "organization": "Leena AI Support",
  "teams": ["Support Team A", "Support Team B"],
  "status": "Open",
  "from": 1,
  "limit": 100
}

Response

The action returns a list of tickets with:

• Ticket ID and number
• Subject
• Status and priority
• Department and team
• Assignee information
• Created and updated timestamps
• Contact information (if included)
• Total count of tickets
• Pagination information

Common Use Cases

1. Dashboard Display: Show all open tickets on support dashboard
2. Agent Workload: List tickets assigned to specific agents
3. Department Reports: Generate department-wise ticket reports
4. Priority Management: Filter and display high-priority tickets
5. Performance Metrics: Analyze ticket volume and response times
6. Escalation Management: Identify tickets requiring escalation

Upload a file

Uploads a file to Zoho Desk for use in tickets. While creating a ticket, an uploaded file/document can be associated with a ticket.

Scope: Desk.basic.CREATE

Required Parameters

Example Usage

Upload File from URL

{
  "organization": "Leena AI Support",
  "fileName": "error-screenshot.png",
  "fileData": "https://example.com/files/error-screenshot.png"
}

Upload File from Base64

{
  "organization": "Leena AI Support",
  "fileName": "log-file.txt",
  "fileData": "data:text/plain;base64,VGhpcyBpcyBhIHNhbXBsZSBsb2cgZmlsZQ=="
}

Upload Document

{
  "organization": "Leena AI Support",
  "fileName": "user-manual.pdf",
  "fileData": "https://example.com/documents/user-manual.pdf"
}

Upload Image

{
  "organization": "Leena AI Support",
  "fileName": "product-image.jpg",
  "fileData": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEAYABgAAD..."
}

Response

Upon successful upload, the action returns:

• File ID
• File name
• File size
• Upload timestamp
• File URL

Common Use Cases

1. Ticket Attachments: Upload files before creating tickets
2. Documentation: Upload user guides or manuals
3. Evidence: Upload screenshots or error logs
4. Reports: Upload analysis reports or test results
5. Images: Upload product images or diagrams
6. Logs: Upload system or application logs

Create a ticket's attachment

Adds an attachment to a specific ticket.

Scope: Desk.tickets.UPDATE

Required Parameters

Optional Parameters

Example Usage

Add Private Attachment

{
  "organization": "Leena AI Support",
  "ticket": "12345",
  "fileName": "troubleshooting-steps.pdf",
  "fileData": "https://example.com/files/troubleshooting-steps.pdf"
}

Add Public Attachment

{
  "organization": "Leena AI Support",
  "ticket": "12345",
  "fileName": "solution-guide.pdf",
  "fileData": "https://example.com/files/solution-guide.pdf",
  "isPublic": true
}

Add Screenshot from Base64

{
  "organization": "Leena AI Support",
  "ticket": "67890",
  "fileName": "error-screenshot.png",
  "fileData": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  "isPublic": false
}

Add Log File

{
  "organization": "Leena AI Support",
  "ticket": "54321",
  "fileName": "application-log.txt",
  "fileData": "data:text/plain;base64,VGhpcyBpcyBhbiBhcHBsaWNhdGlvbiBsb2c="
}

Response

Upon successful attachment, the action returns:

• Attachment ID
• File name
• File size
• Visibility status (public/private)
• Upload timestamp
• Associated ticket ID

Common Use Cases

1. Resolution Evidence: Attach screenshots showing issue resolution
2. Documentation: Add relevant documentation to tickets
3. Customer Communication: Attach files for customer reference
4. Internal Notes: Add internal documentation (private attachments)
5. Public Resources: Share publicly accessible resources with customers
6. Audit Trail: Attach evidence for compliance or audit purposes

Best Practices

File Management:

1. File Size: Keep file sizes reasonable to avoid upload issues
2. File Formats: Use appropriate file formats (PDF for documents, PNG/JPG for images)
3. Naming Convention: Use descriptive file names with proper extensions
4. Visibility: Set appropriate public/private visibility based on content

Security:

1. Sensitive Data: Use private attachments for sensitive information
2. Public Access: Only make attachments public when necessary
3. File Validation: Validate file types and sizes before upload
4. Access Control: Ensure proper permissions are set

Error Handling

Common error scenarios:

• File Too Large: File exceeds maximum size limit
• Invalid Format: File format is not supported
• Ticket Not Found: Invalid ticket ID
• Upload Failed: Network or server issues during upload
• Permission Denied: Insufficient permissions to add attachments
• Organization Mismatch: Ticket doesn't belong to specified organization