RingCentral Two-Leg Call Connect

A WordPress plugin that creates two-leg calls via RingCentral's Call Control API. Perfect for priority lead flows, sales callbacks, or any scenario where you need to connect an agent to an external caller with an optional whisper message.

Key Features

✅ Fully customizable modal - Edit title, description, buttons via admin settings
✅ Flexible trigger placement - Add id="rc-two-leg-modal-trigger" to any element
✅ Sandbox mode - Test the flow without placing real calls
✅ Phone normalization - Automatic E.164 formatting
✅ Whisper messages - Customizable TTS played to agents
✅ Security - REST nonce validation, admin-only endpoints
✅ No code required - Configure everything via WP Admin settings page

---

Developer

Tyler Batten
batten.tyler@gmail.com

---

How it works

1. Modal

   • HTML for the “High-Value Applicant” modal is injected site-wide.

   • JavaScript (modal.js) handles:

     • Auto-formatting phone numbers as (XXX) XXX-XXXX
     • Validation
     • Submitting the number to the backend

2. REST API Endpoints

   • GET /wp-json/rc-two-leg/v1/ping → Health check.

   • GET /wp-json/rc-two-leg/v1/token → Tests RingCentral auth (JWT → access token).

   • POST /wp-json/rc-two-leg/v1/connect → Main flow:

     • Reads applicant phone from request.

     • Authenticates with RingCentral (JWT).

     • Starts a telephony session:

       • First leg: dials extension 5006.
       • Plays a short whisper prompt.
       • Second leg: dials the applicant’s number.
       • Both parties bridged into one call.

3. Modal Trigger

   • Add id="rc-two-leg-modal-trigger" to any element on your site to trigger the modal

   • Or open programmatically via JavaScript:

     jQuery('#rc-two-leg-modal').show();

   • Modal content (title, description, buttons) is fully customizable via plugin settings

---

Installation & Setup

1. Install the plugin

Option A: Upload via WordPress Admin

• Zip the rc-two-leg-call/ folder
• Go to Plugins → Add New → Upload Plugin
• Upload the ZIP file and activate

Option B: Deploy via Local/FTP

• Copy the rc-two-leg-call/ folder to wp-content/plugins/
• Activate via Plugins page in WP Admin

2. Configure settings

Go to Settings → RC Two-Leg Call in WP Admin:

RingCentral Configuration:

• API Base: https://platform.ringcentral.com (default)
• Client ID: Your RingCentral app client ID
• Client Secret: Your RingCentral app client secret
• JWT: Your RingCentral JWT token
• From Extension/Number: Extension or DID to dial first (e.g., 5006)
• From Field Type: Extension Number or Phone Number (DID)
• Whisper Message: TTS message played to the agent before connecting
• Sandbox Mode: Check to enable safe testing (no calls placed)

Modal Customization:

• Modal Title: Customize the modal heading
• Modal Description: Customize the modal message
• Phone Label: Label for the phone input field
• Accept Button: Text for the "yes" button
• Decline Button: Text for the "no" button

Click Save Settings.

3. Add the modal trigger to your site

Add the trigger ID to any element on your site:

<button id="rc-two-leg-modal-trigger">Request a Call</button>

Or open the modal programmatically via JavaScript:

jQuery('#rc-two-leg-modal').show();

Note: The plugin injects the modal HTML into the footer automatically. You just need to add a trigger element with the ID rc-two-leg-modal-trigger.

4. Test the setup

• Click Test Ping button on the settings page → should return ok: true
• Click Test Auth button → should show a green success message with a partial token
• Open your site, click your modal trigger button, enter a phone number, submit
• With sandbox enabled, you'll see a success message with the normalized number; no call is placed

---

Configuration priority

Settings are read with the following priority:

1. WordPress constants (defined in wp-config.php)
2. Saved options (from Settings → Cluett Priority Lead)
3. Environment variables (via getenv)
4. Defaults

Advanced: Override via constants

If you prefer to manage credentials in wp-config.php instead of the database:

define('RC_API_BASE', 'https://platform.ringcentral.com');
define('RC_CLIENT_ID', '...');
define('RC_CLIENT_SECRET', '...');
define('RC_JWT', '...');
define('RC_FROM_EXTENSION', '5006');
define('RC_FROM_FIELD', 'extensionNumber'); // or 'phoneNumber'
define('CPL_SANDBOX', true); // or false for live calls
define('CPL_WHISPER_MESSAGE', 'You are about to be connected with a high value applicant.');

Constants will override any values saved in the settings page.

---

Making Changes

• Styling: Edit modal.css.
• JS behavior: Edit modal.js.
• REST logic: Edit rc-two-leg-call.php.

---

Security and behavior

• POST /wp-json/rc-two-leg/v1/connect requires a valid REST nonce in the X-WP-Nonce header (added automatically by the script via wp_localize_script).
• GET /wp-json/rc-two-leg/v1/token is restricted to administrators (capability manage_options).
• Phone numbers submitted by the modal are normalized server‑side to E.164 format (assumes NANP; (XXX) XXX-XXXX → +1XXXXXXXXXX).
• Frontend uses localized values (RC2LegCall.restUrl, RC2LegCall.nonce, RC2LegCall.sandbox) and shows an explicit message when sandbox mode is enabled.
• All settings saved via the admin page are properly sanitized.

---

Sandbox mode (safe testing)

Enable sandbox mode via Settings → RC Two-Leg Call by checking the "Enable sandbox mode" checkbox.

When enabled:

• Submitting the modal returns success with sandbox: true and the normalized phone
• NO call is placed to RingCentral
• Perfect for testing the flow without dialing real numbers

To place real calls during live testing with the client, uncheck sandbox mode and save.

---

From-leg configuration (RingCentral)

By default the plugin dials an internal extension (e.g., 5006) using the extensionNumber field.

If RingCentral requires a DID instead:

1. Go to Settings → RC Two-Leg Call
2. Set From Field Type to Phone Number (DID)
3. Enter your DID in From Extension/Number (e.g., 1XXXYYYZZZZ)
4. Save settings

The external caller leg always uses the normalized E.164 phoneNumber.

---

Use Cases

• Priority lead flows: Connect high-value website visitors directly to sales agents
• Callback requests: Let customers request immediate callbacks
• Support escalation: Connect urgent support cases to specialized agents
• Sales automation: Trigger calls from CRM events or forms

---

Customization

Modal Content

Customize all modal content via Settings → RC Two-Leg Call → Modal Customization:

• Title, description, button text, and labels
• No code editing required

Styling & Behavior

For advanced customization:

• CSS: Edit modal.css for styling (square corners by default)
• JavaScript: Edit modal.js for behavior
• Modal trigger ID: rc-two-leg-modal-trigger
• Programmatic trigger: jQuery('#rc-two-leg-modal').show()

Trigger Placement

Add the modal trigger anywhere on your site:

• Page builders (Elementor, Divi, etc.): Add a button with ID rc-two-leg-modal-trigger
• Theme templates: Add HTML element with the trigger ID
• Widgets: Use HTML widget with button markup
• Shortcodes: Create a custom shortcode that outputs the trigger button

---

Future Enhancements

• [ ] Add error handling for unanswered agent calls (timeouts, retries)
• [ ] Log successful connections for reporting/analytics
• [ ] Add shortcode support for embedding the modal trigger
• [ ] Support for multiple agent groups/extensions
• [ ] Scheduled callbacks and queue management