CallBack4RingCX – RingCX Callback Widget for WordPress

A WordPress plugin that adds a floating "Request Callback" button to any page. Visitors fill out a short form (name, phone number, preferred date/time, message) and the plugin creates a lead directly in RingCX via the RingCX REST API, then schedules either:

• an agent callback, reserved for a specific agent at the requested time, or
• a group/campaign callback, requeued into a dial group's campaign with a calculated delay.

Features

• Floating callback button + modal form, rendered site-wide via wp_footer
• Visitor-selectable callback target: named agent or campaign/group
• OAuth2 JWT-bearer authentication against RingCentral, exchanged for a RingCX access token, with automatic token refresh/re-authentication
• Admin settings page (Settings → CallBack4RingCX) for API credentials, base URL, default campaign, dial priority, duplicate handling, list state, timezone options, widget texts, and privacy notice
• RingCX campaign and agent-group dropdowns auto-populated live from the RingCX Admin API once credentials are configured
• Automatic phone-number origin-country detection (via giggsey/libphonenumber-for-php) for RingCX's numberOriginCountry field
• Honeypot field for basic spam protection; nonce-protected AJAX endpoints
• Debug logging gated behind WP_DEBUG

Requirements

• WordPress 5.x+, PHP 7.4+
• Composer dependency giggsey/libphonenumber-for-php (bundled in vendor/, see composer.json)
• A RingCentral app configured for JWT-bearer OAuth with access to the RingCX Voice APIs
• A RingCX account with at least one campaign (and optionally an agent group) to receive the leads

Installation

1. Copy the plugin folder into wp-content/plugins/callback4ringcx, or install it as a zip via WP Admin → Plugins → Add New → Upload.
2. Activate the plugin.
3. Go to Settings → CallBack4RingCX and fill in:
   • RingCentral Client ID / Client Secret / JWT assertion
   • RingCX Base URL (default https://ringcx.ringcentral.com/voice/api/v1)
   • Default campaign, dial priority, duplicate handling, list state, timezone options
   • Widget texts (button label, success message, privacy notice)
4. Save. The plugin authenticates immediately and, on success, auto-fills the RingCX account ID and lets you pick campaigns/agent groups from live dropdowns.

How it works

1. CallBack4RingCX_Public::render_widget() outputs the button and modal in the site footer (only when the widget is enabled).
2. On submit, the form posts via AJAX, nonce- and honeypot-checked (CallBack4RingCX_Ajax::handle_submit()).
3. CallBack4RingCX_API::get_valid_ringcx_token() returns a cached token, refreshes it, or performs the full RingCentral JWT → RingCX token exchange.
4. A lead is uploaded to RingCX (.../campaigns/{id}/leadLoader/direct).
5. Depending on the chosen target:
   • Agent – set_scheduled_callback() reserves the lead for a specific agent at the requested date/time (CALLBACK_LEADS action).
   • Group/Campaign – set_group_callback() requeues the lead into the campaign with a delay calculated from the requested time (MANUAL_LEADS action).
6. The visitor sees a success message; failures surface a user-facing error while the RingCX error details are written to the debug log.

File structure

• callback4ringcx.php – plugin bootstrap
• includes/class-callback4ringcx.php – hook wiring
• includes/class-callback4ringcx-settings.php – settings storage & defaults
• includes/class-callback4ringcx-api.php – RingCentral/RingCX API client (auth, campaigns, agent groups, leads, callbacks)
• admin/class-callback4ringcx-admin.php (+ admin/views/settings-page.php) – settings UI
• public/class-callback4ringcx-public.php – frontend widget markup & asset enqueueing
• public/class-callback4ringcx-ajax.php – AJAX submission handlers
• assets/callback-widget.{css,js} – frontend styling and behaviour

Notes

• The plugin talks to RingCX directly from the WordPress server; no callback data passes through a CRM.
• RingCX access/refresh tokens are stored in the WordPress options table (callback4ringcx_settings) — handle database backups accordingly.