Integrations Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Supported Providers
Configuration Settings
AI Integration Tools
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Are Integrations?

The Integrations module is a unified connector platform that links the PBX with external systems across three categories:

CRM Platforms - Contact sync, call logging, screen pop
Scheduling Platforms - Direct appointment booking via AI
Directory Services - LDAP/Active Directory authentication and contact lookup

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Integrations Architecture                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Ring2All PBX                                                   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Integrations Module                               │   │
│  │                                                          │   │
│  │  Categories:                                             │   │
│  │  ├─ CRM: Salesforce, HubSpot, Zoho, Pipedrive...        │   │
│  │  ├─ Scheduling: Calendly (Direct Booking API)           │   │
│  │  └─ Directory: LDAP / Active Directory                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Integration Service + Tool Gateway                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Available Actions by Category                     │   │
│  │                                                          │   │
│  │  CRM Actions:                                            │   │
│  │  ├─ Sync contacts from external CRM                     │   │
│  │  ├─ Log call activity to CRM contacts                   │   │
│  │  └─ Screen pop on incoming calls                        │   │
│  │                                                          │   │
│  │  Scheduling Actions:                                     │   │
│  │  ├─ Get event types and available time slots            │   │
│  │  ├─ Create direct bookings via API                      │   │
│  │  └─ Cancel or reschedule appointments                   │   │
│  │                                                          │   │
│  │  Directory Actions:                                      │   │
│  │  ├─ Authenticate users via LDAP/AD                      │   │
│  │  ├─ Sync users and groups                               │   │
│  │  └─ Caller lookup from directory                        │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ API / LDAP Calls                                       │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        External Platforms                                │   │
│  │                                                          │   │
│  │  CRM:        HubSpot, Salesforce, Zoho, Pipedrive,      │   │
│  │              Dynamics 365, Odoo                          │   │
│  │                                                          │   │
│  │  Scheduling: Calendly                                    │   │
│  │                                                          │   │
│  │  Directory:  Microsoft Active Directory, OpenLDAP,       │   │
│  │              FreeIPA, 389 Directory Server               │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.crm_integrations`	Integration configurations

Key Files

File	Description
`modules/integrations/`	Frontend module

---

2. Module Overview (Commercial/Business)

Business Value

CRM Integrations provides unified customer data:

Without CRM Integration	With CRM Integration
Separate systems	Unified data
Manual call logging	Auto call logging
Unknown callers	Screen pop contact info
No call history	CRM activity records

Use Cases

Contact Sync

- Import CRM contacts

- Caller ID lookup

Call Logging

- Auto-log calls to contacts

- Recording links in CRM

Screen Pop

- Show contact on incoming call

- Agent efficiency

Activity Tracking

- Call duration tracking

- Agent performance data

Feature Highlights

Feature	Benefit
Multi-CRM Support	6 major platforms
OAuth 2.0	Secure authentication
Contact Sync	Unified contact database
Call Logging	Automatic activity creation
Bi-directional	Two-way data sync

---

3. Module Overview (End User/Administrator)

What Can You Do?

Connect to major CRM platforms
Configure OAuth or API key authentication
Enable contact synchronization
Enable call activity logging
Manage multiple integrations

CRM Integrations Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              CRM Integrations                                   │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Connect your telephony system with your Customer Relationship │
│  Management software to sync contacts, calls, and activities.  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ [HubSpot Logo]                                            │  │
│  │ HubSpot                                                   │  │
│  │ Marketing, sales, and service software that helps your   │  │
│  │ business grow without compromise.                         │  │
│  │                                          [Configure]      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ [Salesforce Logo]                                         │  │
│  │ Salesforce                                                │  │
│  │ Connect to the world's #1 CRM platform.                   │  │
│  │                                    ✓ Connected [Configure]│  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ [Zoho Logo]                                               │  │
│  │ Zoho                                                      │  │
│  │ Unique and powerful suite of software to run your        │  │
│  │ entire business.                                          │  │
│  │                                          [Configure]      │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ... Pipedrive, Dynamics 365, Odoo ...                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Configure CRM

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              Configure Salesforce                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ▼ General Settings                                             │
│                                                                 │
│  Enabled: ✓                                                     │
│                                                                 │
│  ▼ Authentication                                               │
│                                                                 │
│  Authentication Type: [OAuth 2.0 ▼]                            │
│                                                                 │
│  Client ID: [your-client-id-here        ]                      │
│  Client Secret: [••••••••••••••••        ]                     │
│                                                                 │
│  Redirect URI: https://pbx.example.com/crm/callback            │
│    ⓘ Copy this URI to your CRM app settings.                  │
│                                                                 │
│  [Connect with Provider]                                        │
│                                                                 │
│  ▼ Synchronization Settings                                     │
│                                                                 │
│  Sync Contacts: ✓                                              │
│    ⓘ Automatically sync contacts between your PBX and CRM     │
│                                                                 │
│  Sync Calls: ✓                                                 │
│    ⓘ Log call activity and recordings to CRM contacts         │
│                                                                 │
│  [Save Configuration]                                           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Redirect URI: Copy to CRM app settings for OAuth.

TIP

Test Connection: Use "Connect with Provider" to verify.

NOTE

API Limits: CRM platforms have API rate limits.

---

4. Supported Providers

CRM Providers

Provider	Description	Auth Types
HubSpot	Marketing, sales, service software	OAuth 2.0
Salesforce	World's #1 CRM platform	OAuth 2.0
Zoho	Complete business suite	OAuth 2.0, API Key
Pipedrive	Sales-focused CRM	OAuth 2.0, API Key
Dynamics 365	Microsoft business apps	OAuth 2.0
Odoo	Open source ERP/CRM	API Key

Scheduling Providers

Provider	Description	Auth Types
Calendly	Scheduling automation platform	OAuth 2.0

Directory Providers

Provider	Description	Auth Types
Microsoft Active Directory	Enterprise directory service	LDAP Bind
OpenLDAP	Open source LDAP server	Simple Bind, SASL
FreeIPA	Identity, Policy, Audit for Linux	LDAP Bind
389 Directory Server	Enterprise-class LDAP	Simple Bind

Provider-Specific Settings

Provider	Unique Fields
Dynamics 365	Tenant ID
Zoho	Data Center Region
Odoo	Server URL, Database Name
Calendly	Event Type (selected during booking)
LDAP	Server URL, Base DN, Bind DN, User Filter

---

5. Configuration Settings

General Settings

Field	Description
Enabled	Activate integration

Authentication

Field	Description
Auth Type	OAuth 2.0 or API Key
Client ID	OAuth application ID
Client Secret	OAuth application secret
API Key	Direct API authentication
Redirect URI	OAuth callback URL
Server URL	Self-hosted instance URL
Tenant ID	Azure/Microsoft tenant
Data Center	Regional endpoint

Synchronization

Field	Description
Sync Contacts	Import/export contacts
Sync Calls	Log call activities

---

6. AI Integration Tools

When Enable Agent AI Access is activated, AI Agents can use the integration's tools during calls.

CRM AI Actions

Action	Description
search_contact	Search for contacts by name, phone, or email
get_contact	Get detailed contact information
add_note	Add notes to a contact record
log_call	Log call activity to the contact
create_lead	Create a new lead record
update_contact	Update contact information

Calendly AI Actions

Action	Description
get_event_types	Retrieve available event types (meetings, consultations)
get_available_times	Get available time slots for a specific event type
create_booking	Create a booking directly via API (collects name, email, timezone)
list_scheduled_events	List upcoming scheduled events
cancel_event	Cancel a scheduled event

Calendly Direct Booking Workflow

AI identifies the appropriate event type
AI checks available time slots
AI collects caller name, email, and timezone
AI creates the booking (POST /invitees)
Calendly sends confirmation and reminders automatically

NOTE

Calendly Paid Plan Required: Direct booking via the Scheduling API requires a paid Calendly subscription.

AI Policies

Policy	Description
Require confirmation for writes	AI asks for confirmation before modifying data
Max actions per conversation	Limit tool calls per call
Timeout (ms)	Maximum wait time for responses
Retry attempts	Number of retries on failure
Redact sensitive data	Hide personal information in logs
Fallback behavior	Action when tool fails: Continue, Escalate, or End
Escalation Destination	Where to transfer when escalating to human

---

7. Common Scenarios & Examples

Scenario 1: Connect HubSpot

Click Configure on HubSpot
Enable integration
Enter Client ID and Secret from HubSpot app
Copy Redirect URI to HubSpot
Click "Connect with Provider"
Complete OAuth flow
Enable Sync Contacts and Sync Calls
Save

Scenario 2: Connect Salesforce

Create Connected App in Salesforce
Copy Client ID and Secret
Add Redirect URI to Salesforce
Configure in Ring2All
Complete OAuth flow
Enable sync options

Scenario 3: API Key Authentication

Click Configure on Pipedrive
Select Auth Type = API Key
Enter API Key from Pipedrive
Enable sync options
Save

Scenario 4: Self-hosted Odoo

Click Configure on Odoo
Enter Server URL (your Odoo instance)
Enter Database Name
Enter API Key
Enable sync options
Save

Scenario 5: Connect Active Directory

Navigate to Integrations → Directory Services
Click Configure on Active Directory
Enter connection details:

- Name: Corporate AD

- Server URL: ldaps://dc.company.com

- Port: 636 (SSL) or 389 (StartTLS)

Enter bind credentials:

- Bind DN: CN=ServiceAccount,OU=Users,DC=company,DC=com

- Bind Password: (service account password)

Configure search settings:

- Base DN: DC=company,DC=com

- User Filter: (objectClass=person)

Map attributes (defaults work for most AD setups):

- Username: sAMAccountName

- Email: mail

- Display Name: displayName

- Phone: telephoneNumber

Test Connection
Enable Sync if desired
Save

Scenario 6: Calendly for AI Agent Booking

Navigate to Integrations → Scheduling
Click Configure on Calendly
Enter OAuth credentials from Calendly Developer Portal:

- Client ID: (from your Calendly app)

- Client Secret: (from your Calendly app)

Click Connect with Provider
Complete OAuth authorization flow
Enable AI Agent Access toggle
Configure AI Policies:

- Require confirmation for bookings: ✓

- Max actions per conversation: 5

Save

NOTE

Calendly Paid Plan Required: Direct booking via the Scheduling API requires a paid Calendly subscription.

---

7. Limitations & Important Notes

Technical Notes

NOTE

OAuth Callback: Redirect URI must be accessible by CRM.

NOTE

Rate Limits: CRM APIs have request limits.

WARNING

Secure Credentials: Keep Client Secret confidential.

Best Practices

Use OAuth: More secure than API keys
Test Connection: Verify before enabling sync
Monitor Sync: Check for errors
Rate Limits: Respect CRM API limits
Backup Data: Before initial sync

OAuth Setup Requirements

Requirement	Purpose
CRM App	Create connected app in CRM
Redirect URI	Configure callback URL
Scopes	Grant necessary permissions
HTTPS	Required for OAuth

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Connection failed	Wrong credentials	Verify Client ID/Secret
OAuth error	Bad Redirect URI	Check URI matches exactly
Sync not working	Rate limited	Wait and retry
Missing contacts	Permissions	Check CRM app scopes

Test CRM Connection

Bash

# Verify OAuth token (example)
curl -H "Authorization: Bearer {token}" \
  https://api.hubspot.com/contacts/v1/lists/all/contacts/all

Check Integration Status

Go to CRM Integrations
Look for ✓ Connected status
Check last sync time
Review error logs

---

9. Glossary

Term	Definition
CRM	Customer Relationship Management
OAuth 2.0	Industry auth standard
API Key	Simple authentication token
Redirect URI	OAuth callback URL
Screen Pop	Show contact on call
Sync	Data synchronization

---

Lua Script Status ℹ️

Integration Module

Component	Status
CRM Integrations	ℹ️ Configuration module - backend service handles API calls

CRM Integrations is a configuration module. The backend CRM service handles API calls to sync contacts and log calls. No Lua handlers are used for CRM integration.

---

Documentation last updated: February 2026

Integrations Module Documentation

Table of Contents

1. Module Overview (Technical)

What Are Integrations?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

CRM Integrations Interface

Configure CRM

Quick Tips

4. Supported Providers

CRM Providers

Scheduling Providers

Directory Providers

Provider-Specific Settings

5. Configuration Settings

General Settings

Authentication

Synchronization

6. AI Integration Tools

CRM AI Actions

Calendly AI Actions

Calendly Direct Booking Workflow

AI Policies

7. Common Scenarios & Examples

Scenario 1: Connect HubSpot

Scenario 2: Connect Salesforce

Scenario 3: API Key Authentication

Scenario 4: Self-hosted Odoo

Scenario 5: Connect Active Directory

Scenario 6: Calendly for AI Agent Booking

7. Limitations & Important Notes

Technical Notes

Best Practices

OAuth Setup Requirements

8. Troubleshooting Tips

Common Issues

Test CRM Connection

Check Integration Status

9. Glossary

Lua Script Status ℹ️

Integration Module