Custom CRM Integration

The Virtual-Call Cloud PBX Custom CRM integration provides a flexible solution for connecting any Customer Relationship Management system that supports REST API. Unlike pre-built integrations, the Custom CRM integration allows you to define the exact API endpoints, authentication methods, and data mappings required by your specific CRM platform. This gives your organization complete control over how call data, contact information, and customer interactions are synchronized between your PBX and your CRM system.

Overview

Custom CRM integration works by creating reusable templates that define how your Virtual-Call Cloud PBX communicates with your CRM's REST API. Each template specifies:

• Authentication method — How the PBX authenticates with your CRM (Basic Auth, OAuth 2.0, Bearer Token, or None)
• Contact search configuration — API endpoint and field mappings for looking up contacts during calls
• Contact/lead creation — Optional endpoint for creating new contacts or leads from the PBX
• Call journal logging — Optional endpoint for recording call activities and outcomes in your CRM

Once a template is created, you can assign it to specific users or extensions, and configure how it integrates with your PBX features like call popups, contact synchronization, and call journaling.

Prerequisites

Create an Integration Template

Integration templates define the API configuration and data mappings for your custom CRM. Complete the following steps to create your first template:

Step 1: Navigate to Custom CRM

1. Log in to your Virtual-Call Cloud PBX administrator console
2. Go to Integrations > CRM
3. In the CRM integrations list, locate and click Custom

Step 2: Create a New Template

1. Click the Add button to create a new custom CRM template
2. A configuration form will appear with multiple sections

Step 3: Configure General Settings

In the General section, enter the following information:

• Template Name — A descriptive name for this integration (e.g., "Salesforce Production" or "HubSpot CRM")
• Logo URL — Optional. The URL to a logo image that represents your CRM. This logo appears in the PBX UI when this template is selected
• Max Concurrent Requests — The maximum number of simultaneous API requests the PBX will send to your CRM. The recommended value is between 5 and 20, depending on your CRM's API rate limits. Start with 10 if unsure.

Step 4: Configure Authentication

The Authentication section defines how your PBX will authenticate with your CRM API. Select the method that matches your CRM's API requirements:

• None — No authentication required. Use this only if your CRM API is publicly accessible without credentials (uncommon)
• Basic Authentication — Username and password credentials. Enter your CRM API username and password
• OAuth 2.0 — Token-based authentication. You will need to:
  • Obtain authorization from your CRM using your CRM's OAuth 2.0 endpoints
  • Enter the access token and refresh token provided by your CRM
  • Specify the token refresh URL so the PBX can automatically refresh expired tokens
• Bearer Token — API key or access token provided by your CRM. Enter the token value directly

Step 5: Configure Contact Search (Required)

The Contact Search configuration is required for all other integration features to function. It defines how the PBX queries your CRM to look up contact information during calls.

API Endpoint URL: Enter the REST API endpoint from your CRM that performs contact search. This typically looks like:

• https://your-crm.com/api/v1/contacts/search
• https://api.salesforce.com/services/data/v57.0/sobjects/Contact
• https://api.hubapi.com/crm/v3/objects/contacts/search

Field Mapping for Contact Lookup: Define which fields your CRM uses for searching and which fields the PBX should extract from the response:

• Search Field (CRM) — The field name in your CRM that will be searched (usually a phone number field). For example: phone, phoneNumber, or mobile_phone
• Match Field (PBX) — Which phone number field from the call should be used for searching: caller (incoming caller ID), called (dialed number), or both (search both)

• Result Field Mapping — Define what information should be extracted from the CRM response and how it appears in the PBX:

  • contact_id — Unique identifier for the contact in your CRM
  • contact_name — Display name of the contact
  • contact_phone — Phone number to display
  • contact_email — Email address (for call popup or journaling)
  • contact_company — Company name
  • contact_department — Department or business unit
  • contact_notes — Additional notes or description

  For each field, specify the exact JSON path to the corresponding value in your CRM's API response

{
  "id": "12345",
  "fullName": "John Smith",
  "workPhone": "+1-555-0100",
  "email": "john@company.com",
  "company": "Acme Corp"
}

Step 6: Configure Contact/Lead Creation (Optional)

If your organization creates new contacts or leads in your CRM from incoming calls, enable and configure this section:

• Enable Contact Creation — Toggle to enable this feature
• API Endpoint URL — The REST API endpoint for creating new contacts in your CRM. For example: https://api.hubapi.com/crm/v3/objects/contacts

• Field Mapping for New Contacts — Define which CRM fields should be populated when a new contact is created:

  • phone — Phone number from the call
  • firstName, lastName — Contact name fields
  • email — Email address (if available)
  • company — Company name (if available)
  • source — Where the contact came from (e.g., "PBX")
  • callDate, callDuration — Call metadata

  Map these PBX fields to your CRM's exact field names

Step 7: Configure Call Journal (Optional)

Call journaling records the details of every call in your CRM for complete customer interaction history. Enable this section if your CRM supports activity or call logging:

• Enable Call Journal — Toggle to enable call logging
• API Endpoint URL — The REST API endpoint for creating call records or activities in your CRM. For example: https://api.hubapi.com/crm/v3/objects/calls

• Field Mapping for Call Data — Define what call information should be logged in your CRM:

  • contact_id — The unique contact identifier to associate the call with
  • call_direction — Direction of the call: inbound or outbound
  • call_type — Type of call: inbound, outbound, missed, or voicemail
  • duration — Duration of the call in seconds
  • start_time — When the call started (Unix timestamp or ISO format)
  • from_number — The calling party's phone number
  • to_number — The called party's phone number
  • recording_url — URL to the call recording (if applicable)
  • notes — Call notes or description

  Map these to your CRM's activity fields

Step 8: Save and Test the Template

1. Click Save to create the template
2. The template is now available for assignment to users and extensions
3. After assigning the template to users, test the integration by making a test call and verifying that:
   • Contact information appears in the call popup (if enabled)
   • New contacts can be created from missed calls (if enabled)
   • Call details are logged in your CRM (if enabled)

Connect and Configure

Assign the Custom CRM Template to Users

After creating a template, you must assign it to specific users or extensions for the integration to function:

1. Go to Integrations > CRM
2. Select your custom CRM template from the list
3. In the Associated Users/Extensions section, click Add to assign the template
4. Select which users or extensions should use this CRM integration
5. Click Save

Verify Authentication Settings

Some CRM integrations require periodic re-authentication or credential refresh. Verify that:

• Your authentication credentials are correct and active in your CRM
• API keys or tokens have not expired
• OAuth 2.0 refresh tokens are properly configured if using token-based authentication

Configure Integration Features

Contact Synchronization

Contact synchronization keeps contact information in your Virtual-Call UC Client synchronized with your CRM. This feature enables:

• Automatic contact search — When a call arrives, the PBX automatically queries your CRM to find matching contact information
• Display caller information — Contact name, company, and other details appear in your UC Client during the call
• Contact labeling — Contacts from your CRM are labeled with the CRM source for easy identification

To enable contact synchronization:

1. Go to Integrations > CRM
2. Select your custom CRM template
3. Locate the Contact Synchronization section and toggle Enable
4. Verify the Contact Search configuration is properly set up (required for sync)
5. Click Save

Contact/Lead Creation

The contact creation feature allows users to create new contacts or leads in your CRM directly from the Virtual-Call UC Client when they encounter a new caller:

1. Go to Integrations > CRM
2. Select your custom CRM template
3. In the Contact Creation section, verify that:
   • Enable Contact Creation is toggled on
   • The API endpoint URL is correctly configured
   • Field mapping includes at least the phone number and name fields
4. Click Save

Once enabled, users will see a "Create Contact" option in their UC Client when viewing calls from unknown contacts.

Call Popup

Call popups display customer information on the screen when an incoming call arrives. The Custom CRM integration supports two call popup modes:

Mode 1: Popup with Contact Search Results

This mode uses the Contact Search configuration to automatically look up contact information from your CRM and display it in a popup window.

1. Go to Integrations > CRM
2. Select your custom CRM template
3. In the Call Popup section, select Enable Call Popup
4. Choose the popup trigger event:
   • When incoming call arrives — Popup shows immediately for inbound calls
   • When answering call — Popup shows after you answer the call
   • Always Query CRM — Continuously refresh contact information during the call
5. Verify the Contact Search configuration is properly set up
6. Click Save

Mode 2: Custom HTML Popup with URL Format String

For advanced customization, you can define a custom URL format that opens your CRM to a specific customer record when a call arrives:

1. Go to Integrations > CRM
2. Select your custom CRM template.
3. In the Call Popup section, select Enable Custom URL Popup
4. Enter the Popup URL Format. This should be a URL template that includes placeholders for call information:
   • {caller_id} — The calling party's phone number
   • {contact_id} — The CRM contact ID (if found by Contact Search)
   • {contact_name} — The contact name (if found)
   • {company} — Company name (if found)
5. Example URL formats:
   • https://salesforce.com/lightning/r/Contact/{contact_id}/view
   • https://hubspot.com/contacts/{contact_id}
   • https://your-crm.com/search?phone={caller_id}
6. Click Save

Call Journal

Call journaling automatically records all call details in your CRM for complete customer interaction history:

1. Go to Integrations > CRM
2. Select your custom CRM template
3. In the Call Journal section, toggle Enable Call Journal
4. Verify the API endpoint URL and field mappings are correctly configured
5. Select which call types should be logged:
   • Answered calls
   • Missed calls
   • Voicemail messages
6. Optionally enable Include Call Recording to attach recording URLs to call journal entries
7. Click Save

After calls are logged, you can review the call activity in your CRM by navigating to the contact record. The call journal provides a complete audit trail of all customer interactions.

Edit and Manage Templates

To modify an existing custom CRM template after it has been created:

1. Go to Integrations > CRM
2. Locate your custom CRM template in the list
3. Click the Edit icon (pencil) next to the template name
4. Update any settings such as API endpoints, field mappings, or authentication credentials
5. Click Save to apply the changes

Changes to templates take effect immediately for all assigned users.

Troubleshooting

Contact Search Not Returning Results

Problem: Call popups are not appearing, or contact information is not displayed during calls.

Solutions:

• Verify that the Contact Search API endpoint URL is correct and accessible from your PBX
• Test the API endpoint manually using a tool like Postman or curl to ensure it returns contact data in the expected JSON format
• Check that the field mapping is correct — the JSON path should match the actual structure of your CRM's API response
• Verify that the phone number in your CRM matches the calling number format (some CRMs require numbers with country codes like +1-555-0100 while others use a 10-digit format)
• Ensure authentication is working correctly by verifying your credentials are valid and the token has not expired
• Check the PBX logs (Administration > System > Logs) for API errors or timeout messages

Authentication Failures

Problem: API calls are failing with 401 (Unauthorized) or 403 (Forbidden) errors.

Solutions:

• Verify that your authentication credentials (username, password, API key, or token) are correct and have not expired
• For OAuth 2.0 integrations, ensure that the access token is valid. If expired, the refresh token should be used to obtain a new access token
• Check your CRM's API documentation to confirm the correct authentication header format required by your CRM
• Verify that the API user account has the necessary permissions to perform contact search, creation, and call logging operations
• Some CRMs require IP whitelisting — confirm that your PBX's IP address is authorized to access the API
• Test the API endpoint with the same credentials using a tool like Postman to isolate whether the issue is with the PBX configuration or the CRM API

Contact Creation Not Working

Problem: New contacts cannot be created from the UC Client, or missed calls are not being logged as new contacts.

Solutions:

• Verify that the Contact Creation API endpoint URL is correct
• Check that the field mapping includes the required fields for your CRM (at minimum, the phone number field should be mapped)
• Ensure the API user account has "Create Contact" or "Create Lead" permissions in your CRM
• Review your CRM's API documentation to confirm the required and optional fields for contact creation
• Test the endpoint manually by sending a POST request with sample contact data to verify it works
• Check the PBX logs for any error messages related to contact creation failures

Call Journal Entries Not Appearing

Problem: Call details are not being recorded in your CRM after calls are completed.

Solutions:

• Verify that call journaling is enabled in the CRM integration settings
• Check that the Call Journal API endpoint URL is correct and accessible
• Ensure the field mappings for call data are correct and match your CRM's activity field names
• Verify that the contact lookup (Contact Search) is working correctly — call journal typically requires a valid contact_id to link the call activity to a contact
• Check your CRM's permissions to ensure the API user can create activity or call records
• Review the PBX logs (Administration > System > Logs) for any API failures or timeout errors during call logging
• Some CRMs have different API endpoints for different activity types — verify you are using the correct endpoint for call logging

Popup Window Not Opening

Problem: Custom URL popups are not appearing when calls arrive.

Solutions:

• Check if your web browser has popup blocking enabled. Add your CRM domain to the browser's popup whitelist
• Verify the Popup URL Format is correctly formatted with the proper placeholders ({caller_id}, {contact_id}, etc.)
• Test the URL format by manually constructing a URL with sample data and visiting it in your browser
• Ensure the CRM website supports being opened in a separate window (some applications block framing or popups for security reasons)
• Check that the URL does not contain special characters or spaces that might cause it to be malformed
• Some CRM platforms have iframe blocking enabled — verify your CRM allows external popups

API Rate Limit Exceeded

Problem: You are receiving rate limit errors (HTTP 429) from your CRM API.

Solutions:

• Reduce the Max Concurrent Requests setting in the template's General settings. Lower this value if your CRM has strict rate limits (try 5 instead of 20)
• Review your CRM's API documentation for rate limit policies and quotas
• Contact your CRM provider to request a higher rate limit quota if needed
• Disable features that are not needed (such as "Always Query CRM" during call) to reduce the frequency of API calls
• Check if your CRM offers batch API endpoints that allow querying multiple contacts in a single request, which may be more efficient

Disable or Disconnect

Temporarily Disable Integration for Specific Users

To stop the CRM integration for certain users while keeping the template configured:

1. Go to Integrations > CRM
2. Select your custom CRM template
3. In the Associated Users/Extensions section, locate the users you want to remove
4. Click the Remove button next to each user or extension
5. Click Save

The template remains saved and can be reassigned to users at any time.

Delete a Template

To permanently remove a custom CRM template:

1. Go to Integrations > CRM
2. Locate the template you want to delete
3. Click the Delete icon (trash can) next to the template name
4. Confirm the deletion when prompted

Disable the Entire Custom CRM Integration

To turn off all custom CRM functionality on your PBX:

1. Go to Integrations > CRM
2. Locate the Custom CRM section
3. Toggle Enable Custom CRM to off
4. Click Save

All contact search, call popups, contact creation, and call journaling features will be disabled. Templates and configuration data are retained and can be re-enabled at any time.

Best Practices

• Test thoroughly before deployment — Set up a test template with a non-production CRM instance first to verify all API endpoints and field mappings work correctly before rolling out to end users
• Document your API endpoints — Keep detailed notes about which CRM endpoints you are using and how fields are mapped. This will help with troubleshooting and future updates
• Monitor API rate limits — Start with conservative Max Concurrent Requests settings and increase gradually if needed while monitoring for rate limit errors
• Regularly refresh OAuth tokens — If using OAuth 2.0, verify that refresh tokens are properly configured and test periodically to ensure tokens do not expire unexpectedly
• Use contact search for all features — Ensure Contact Search is properly configured before enabling Call Popups or Call Journal, as these features depend on successful contact lookups
• Test with real phone numbers — Verify that phone numbers in your CRM match the format used by your PBX (some systems use international format +1-555-0100 while others use 10-digit format 555-0100)
• Secure API credentials — Never share API keys, tokens, or passwords. Treat them with the same security level as user passwords
• Review call journal data**— Periodically verify that calls are being recorded correctly in your CRM to ensure data quality and completeness
• Keep templates updated — If your CRM updates its API endpoints or adds new features, update your custom CRM templates accordingly.

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.