Custom Helpdesk Integration

Overview

The Custom Helpdesk integration enables Virtual-Call Cloud PBX to connect with virtually any helpdesk or ticketing system that supports REST API. This flexible integration framework allows you to extend the functionality of your helpdesk system with advanced telecommunications features, creating a unified communication and support experience.

Through custom templates, you can configure how Virtual-Call Cloud PBX communicates with your helpdesk platform. This enables seamless interaction between your phone system and support tools, eliminating the need for multiple applications and reducing manual data entry.

Key Features

• Click-to-Call: Initiate calls directly from your helpdesk interface using the virtual phone button
• Call Popup: Automatic popup displays relevant customer information when receiving or placing calls
• Contact Synchronization: Automatically sync contacts from your helpdesk into Virtual-Call UC Client
• Contact Creation: Automatically create new contacts in your helpdesk when needed
• Call Journal: Log call details and notes directly into your helpdesk system
• Automatic Ticket Creation: Create support tickets automatically based on call events

Prerequisites

• Plan Requirements: Enterprise or Ultimate subscription plan
• API Support: Your helpdesk system must support REST API integration
• Template Limit: Up to 10 custom integration templates can be created per system
• Firmware Version: Virtual-Call Cloud PBX firmware version 84.21.0.66 or later
• API Documentation: Complete documentation for your helpdesk's REST API endpoints and authentication methods
• Network Access: Cloud PBX must have network access to your helpdesk's API endpoints

Create an Integration Template

Integration templates define how Virtual-Call Cloud PBX communicates with your helpdesk system. Create and configure templates to match your helpdesk's API requirements.

Step 1: Navigate to Helpdesk Integration

Log in to the Virtual-Call Cloud PBX management console and navigate to:

CRM > Integrations > Helpdesk

Select the Custom option to create a new custom helpdesk integration template.

Step 2: Create a New Template

Click the Add button to create a new custom integration template. You will be prompted to configure several sections.

Step 3: Configure General Settings

In the General section, configure basic parameters for your integration:

• Template Name: Enter a descriptive name for this integration template (e.g., "Zendesk Support", "Jira Service Management")
• Logo URL: Provide the URL to a logo image for your helpdesk system (displayed in the UI)
• Max Concurrent Requests: Set the maximum number of simultaneous API requests to your helpdesk system. Start with a conservative value and adjust based on performance monitoring
• Enable Testing Mode: Toggle to enable testing mode for validating configurations before deployment

Step 4: Configure Authentication

Select the authentication method required by your helpdesk's API. Virtual-Call Cloud PBX supports multiple authentication schemes:

• None: No authentication required (public API endpoints only)
• Basic Authentication: Username and password credentials
  • Enter Username and Password fields
  • Credentials are Base64 encoded in the Authorization header
• OAuth 2.0: Token-based authentication
  • Configure Token URL, Client ID, and Client Secret
  • Supports authorization code and client credentials grant types
  • Tokens are automatically refreshed as needed
• Bearer Token: Static token authentication
  • Enter your API token or key
  • Tokens are included in the Authorization header for all requests

Step 5: Configure Contact Search (Required for most features)

Contact Search configuration is essential for enabling Contact Synchronization, Call Popup, and other features that retrieve customer data from your helpdesk.

API Endpoint Configuration:

• Search API URL: Enter the REST API endpoint used to search for contacts (e.g., `https://api.example-helpdesk.com/v2/contacts/search`)
• Request Method: Select GET or POST depending on your helpdesk's API design
• Request Parameters: Define how search queries are sent (query string, request body, headers)
• Test Search: Use the test functionality to validate the API endpoint with sample data

Contact Field Mapping:

Map the response fields from your helpdesk's API to Virtual-Call Cloud PBX fields. Required mappings enable proper display of customer information:

• Contact ID: The unique identifier for each contact
• First Name: Contact's given name
• Last Name: Contact's family name
• Display Name: Name as it appears in the UI
• Phone Number: Primary contact telephone number
• Email: Email address
• Company: Organization name
• Additional Fields: Add custom fields specific to your helpdesk system

Step 6: Configure Contact Creation (Optional)

If you want Virtual-Call Cloud PBX to automatically create contacts in your helpdesk system, configure the Contact Creation settings.

• API Endpoint: Enter the REST API endpoint for creating new contacts (e.g., `https://api.example-helpdesk.com/v2/contacts`)
• Request Method: Typically POST for creating resources
• Field Mapping: Define which Virtual-Call Cloud PBX fields map to helpdesk contact fields
• Enable Contact Creation: Toggle to activate automatic contact creation during calls

Step 7: Configure Call Journal (Optional)

Call Journal integration logs call details into your helpdesk system, creating a complete communication history within your support platform.

• API Endpoint: The REST endpoint for creating journal entries or notes (e.g., `https://api.example-helpdesk.com/v2/contacts/{id}/notes`)
• Request Method: POST for creating new journal entries
• Field Mapping: Map call data (caller, date, duration, notes) to your helpdesk's journal fields
• Include Call Recording Link: Option to include links to call recordings if available
• Auto-Log Calls: Enable automatic logging of all calls, or require manual selection

Step 8: Configure Automatic Ticket Creation (Optional)

Set up automatic ticket creation to generate support tickets based on specific call events, ensuring no customer interaction is missed.

Ticket Creation API Configuration:

• API Endpoint: The REST endpoint for creating tickets (e.g., `https://api.example-helpdesk.com/v2/tickets`)
• Request Method: POST
• Enable Automatic Ticket Creation: Toggle to activate this feature
• Trigger Events: Select which call events should trigger ticket creation:
  • Missed calls
  • Voicemail received
  • Call transfer completed
  • Manual ticket creation during call

Ticket Template Configuration:

• Subject Template: Define the format for ticket subjects (e.g., "Call from {{contact_name}} on {{call_date}}")
• Description Template: Template for ticket description body
• Priority Field: Map ticket priority levels
• Category/Type Field: Assign ticket categories
• Assignment Rules: Define how tickets are routed (by user, queue, department)
• Custom Fields: Include any required custom fields for your helpdesk

Step 9: Save the Template

Review all configuration sections to ensure accuracy, then click Save to create the integration template. The template will be validated against your helpdesk's API endpoints before being saved.

Connect and Configure

Associate the Integration with Users

After creating an integration template, associate it with users who will benefit from helpdesk integration features.

Navigate to Contacts & CRM > Settings > CRM Integration and:

• Select the custom helpdesk template from the dropdown
• Choose which features to enable for each user or group
• Configure per-user authentication if your helpdesk requires individual credentials
• Save the settings

Test the Connection

Verify the integration is working correctly:

1. Search for a contact in your helpdesk using the Virtual-Call UC Client search functionality
2. Verify that customer information displays correctly
3. Attempt a test call to validate Call Popup functionality
4. Check that call data is properly logged in your helpdesk system

Configure Integration Features

Contact Synchronization

Contacts from your helpdesk system are synchronized into Virtual-Call UC Client, making customer information readily available during communications.

Sync Configuration:

• Navigate to Contacts & CRM > Contact Sync
• Select your custom helpdesk integration
• Choose sync frequency (real-time, hourly, daily)
• Select which contacts to sync (all contacts, specific groups, filtered by criteria)
• Enable bi-directional sync to allow updates to flow back to your helpdesk
• Save and start synchronization

Contact Creation

When enabled, this feature allows Virtual-Call Cloud PBX to create new contacts in your helpdesk system directly from incoming calls or manual entry.

Activation:

• Enable contact creation in your integration template configuration
• Configure field mapping to define which caller information creates which helpdesk fields
• Users will see an option to create a contact in the helpdesk when calling an unknown number
• New contacts are immediately added to your helpdesk system and synced back to Virtual-Call UC Client

Call Popup

Call Popup displays customer information from your helpdesk automatically when receiving or placing calls, providing agents with instant access to relevant data.

Enabling Call Popup:

• Navigate to CRM > Popup Settings
• Select your custom helpdesk integration
• Configure popup trigger events (incoming call, outgoing call, or both)
• Customize the information displayed in the popup window

Custom Helpdesk URL Format:

For custom helpdesk systems, the Call Popup URL must be configured to launch your helpdesk's contact or customer record page. The URL format should include a placeholder for the contact identifier:

Example URL formats:

• https://helpdesk.example.com/contacts/{{contact_id}}
• https://crm.example.com/customer?id={{contact_id}}&view=details
• https://support.example.com/accounts/{{account_id}}/contacts/{{contact_id}}

Contact Field Configuration:

Configure which contact fields from your helpdesk are displayed in the popup:

• Select up to 8-10 relevant fields
• Arrange fields in order of importance
• Choose between name, email, phone, company, account status, custom fields
• Preview the popup layout before saving

Call Journal

Call Journal automatically records call details into your helpdesk system, creating a complete communication timeline for each customer.

Configuration Steps:

1. Enable Call Journal in your integration template
2. Configure the API endpoint for creating notes/journal entries
3. Set which call information is recorded:
   • Caller name and number
   • Call date and time
   • Call duration
   • Call direction (inbound/outbound)
   • Call recording link (if applicable)
   • Call notes from agent
4. Define automatic logging behavior (always log, prompt user, manual only)
5. Save configuration

During active calls, agents can optionally add notes which are included in the journal entry sent to your helpdesk system.

Automatic Ticket Creation

Automatically generate support tickets in your helpdesk based on call events, ensuring no customer issue goes unaddressed.

Setup Process:

1. Enable Automatic Ticket Creation in your integration template
2. Configure ticket template with subject and description formats
3. Select trigger events (missed calls, voicemails, transfers, manual creation)
4. Define ticket routing (queue assignment, priority, category)
5. Test ticket creation with a test call

Ticket Template Variables:

Use these variables in your ticket templates to populate dynamic information:

• {{caller_name}} — Name of the person calling
• {{caller_number}} — Phone number of the caller
• {{call_date}} — Date of the call
• {{call_time}} — Time of the call
• {{call_duration}} — Length of the call in seconds
• {{answering_agent}} — Name of the agent who answered
• {{call_direction}} — Incoming or Outgoing
• {{voicemail_transcript}} — Automatic transcription of voicemail (if enabled)

Example ticket subject: "Missed call from {{caller_name}} ({{caller_number}}) on {{call_date}}"

Example ticket description: "Customer {{caller_name}} called on {{call_date}} at {{call_time}} but the call was not answered. Call duration: {{call_duration}} seconds. Please contact the customer to address their inquiry."

Troubleshooting

Call Popup Not Appearing

Issue: The customer information popup does not display when receiving calls.

Solutions:

• Verify Contact Search API is properly configured and accessible
• Check that the phone number in the incoming call matches a contact in your helpdesk system
• Confirm Contact ID and Phone Number field mappings are correct
• Check browser console for popup blocker warnings
• Verify authentication credentials are valid and have not expired
• Test the Contact Search API directly using a REST client tool to isolate the issue
• Review Cloud PBX logs for API connection errors

Contact Synchronization Failures

Issue: Contacts are not syncing from helpdesk to Virtual-Call UC Client.

Solutions:

• Verify the Contact Search API endpoint URL is correct
• Test API authentication with correct credentials
• Check that contacts exist in your helpdesk system
• Review field mapping to ensure required fields (Contact ID, Display Name, Phone) are mapped correctly
• Check network connectivity to the helpdesk API server
• Review system logs for sync errors and API response codes
• Verify that Max Concurrent Requests setting is not too low
• Check helpdesk system logs for API errors or rate limiting

Authentication Errors

Issue: "Authentication failed" or "Unauthorized" errors when accessing helpdesk API.

Solutions:

• Verify authentication credentials are correct and current
• For OAuth 2.0, ensure Token URL and Client ID/Secret are correct
• Check that API user account has appropriate permissions in your helpdesk system
• Verify that API tokens or passwords have not expired
• For Basic Auth, ensure username and password are correctly encoded
• Test authentication using your helpdesk's API testing tools
• Regenerate API keys/tokens in your helpdesk system and update integration configuration

Slow API Responses

Issue: Call popups are slow to appear, or contact searches take excessive time.

Solutions:

• Reduce the number of contact fields being retrieved in API queries
• Add filtering or search criteria to the API request to reduce result sets
• Check helpdesk system performance and database query efficiency
• Monitor network latency between Cloud PBX and helpdesk API
• Optimize API queries (use indexed fields for searches)
• Reduce Max Concurrent Requests if helpdesk is being overwhelmed
• Consider caching frequently accessed contact data locally
• Review helpdesk API logs for slow or problematic queries

Incorrect Field Mapping

Issue: Contact information displays incorrectly or fields are blank in popups.

Solutions:

• Review API response format from your helpdesk system
• Verify field names in the API response match those in your field mapping configuration
• Check data types match (ensure numeric IDs are mapped correctly)
• Test Contact Search API with a sample request using your testing tool
• Compare expected field names against actual API response field names
• Update field mappings to use correct field paths (e.g., for nested objects: "customer.contact_id")

Ticket Creation Not Working

Issue: Tickets are not being created automatically when trigger events occur.

Solutions:

• Verify automatic ticket creation is enabled in the integration template
• Check that trigger events are properly configured
• Confirm the ticket creation API endpoint is correct and accessible
• Verify authentication credentials have permissions to create tickets
• Test the Ticket API endpoint manually with sample data
• Review template variable syntax—ensure variables are correctly formatted with {{ }}
• Check helpdesk system logs for ticket creation errors
• Verify required ticket fields are being populated by the template

Disable or Disconnect

Temporarily Disable the Integration

To pause integration features without removing the configuration:

1. Navigate to CRM > Integrations > Helpdesk
2. Select your custom helpdesk integration template
3. Click the toggle or checkbox to disable the template
4. All related features (Contact Popup, Sync, Journal) will immediately stop functioning
5. To re-enable, simply toggle the template back on

Disconnect from Helpdesk System

To completely remove the integration and delete the template:

1. Navigate to CRM > Integrations > Helpdesk
2. Find the custom helpdesk template to be removed
3. Click the delete/remove button (typically a trash icon)
4. Confirm removal when prompted
5. The integration template is permanently deleted, and all synchronized contacts and configurations are removed
6. Integration features stop immediately for all users

Removing User Associations

To disable integration features for specific users without removing the template:

1. Navigate to CRM > User Integration Settings
2. Select the user account to modify
3. Uncheck the custom helpdesk integration
4. Click Save
5. That user will no longer have access to integration features, but other users retain access

New Authentication Method from Version 84.23.0.24

OAuth2 PKCE Support

Custom CRM/Helpdesk integration templates now support the authentication method Authorization Code Flow with Proof Key for Code Exchange (PKCE). This method uses a challenge-verifier pair instead of a client secret, thereby improving the security of OAuth 2.0 authentication.