Does V2.5 break the macOS app that uses /api/v2/screenpop?

No. The macOS app polls GET /api/v2/screenpop?pending. V2.5 leaves that response shape unchanged. POST-side hardening (HMAC signature observation, screenpop idempotency on the (tenant_id, contact_id) UNIQUE index, optional enforcement) is invisible to the app. New optional fields like signature_valid are appended to POST responses; old clients ignore unknown keys.

Does V2.5 require new permissions or break existing user roles?

No. Click-to-dial still requires the existing crm.calls.create or crm.* permission. The bulk agent mapping page is admin-gated like every other tenant settings UI. The compliance gate is automatic and applies to every user — no opt-in, no opt-out.

Can I disable the TCPA gate for non-collections tenants?

The gate fails open for tenants without customer_collections_metadata — if the table doesn't exist (Collections module not activated), all flags default to false and the only check is the FDCPA hours warning. Tenants who don't run collections-style work see no behavioral difference. The compliance audit table is only populated when there's something to audit.

NICE CXone Enhanced V2.5 — TCPA-Gated Click-to-Dial, Signed Screenpop Webhooks, Bulk Agent Mapping

RubiPro's deep NICE CXone integration: real-time agent state, click-to-dial, screenpop, contact + skill sync. V2.5 adds a TCPA/DNC pre-dial gate, HMAC-signed screenpop webhooks, click-to-dial → CRM interactions logging, bulk agent-ID mapping by email, and dual-read encryption-key migration.

V2.5 ships hardening — not a rebuild.

The macOS app's GET /api/v2/screenpop?pending contract is preserved verbatim. Every V2.5 addition is additive, optional, or backward-compatible. Encryption-key migration runs in dual-read mode so existing creds keep working.

What's new in V2.5

TCPA / DNC pre-dial gate

Mirror of Softphone Pro V2's gate. Click-to-dial runs precheckDial first — hard blocks for cease-and-desist, bankruptcy, attorney-represented, do-not-call, deceased. Soft warnings for outside FDCPA hours. Every event audited.

Click-to-dial → CRM interactions

Every successful click-to-dial writes a canonical interactions row tagged [nice_click_to_dial]. The customer profile timeline finally shows NICE-side activity alongside email, SMS, and notes.

HMAC-signed screenpop webhooks

Configure a webhook secret in tenant settings; NICE signs every screenpop POST with HMAC-SHA256. Observe-only by default — when ready, flip enforcement on per tenant. macOS app contract unchanged.

Bulk agent mapping by email

One page, all your users matched to NICE agent IDs by email. Preview shows will-map / already-mapped / conflict / no-match. Bulk commit writes users.nice_agent_id with per-batch audit.

Screenpop idempotency

UNIQUE on (tenant_id, contact_id). NICE retries are idempotent — the second POST returns the original row's id. No more duplicate screenpops on the agent's screen.

Encryption-key dual-read + retention cron

Server-wide NICE_ENCRYPTION_KEY in .env with backward-compat fallback to the legacy per-tenant key. nice_cxone_api_logs retention cron purges rows older than 90 days in chunks.

Setup steps

Run the migration. Visit /admin/run-nice-cxone-v25-migration.php as a system admin → Apply V2.5 schema. Idempotent.
Verify state. Open /admin/view-nice-state.php — every NICE-active tenant should show in the rollup with credentials, agent mapping coverage, and today's activity.
Run the email-match agent mapping per tenant. From the tenant admin sidebar (NICE CXone → Agent Mapping). Walks through preview → confirm → audit.
Enable webhook signature observation. Generate a 32-character secret, paste it into NICE's outbound webhook config and into RubiPro's tenant settings. Observe signature_valid in screenpop responses for a few days before flipping enforcement.
(Optional) Migrate the encryption key. Add NICE_ENCRYPTION_KEY to .env. Tenants migrate gradually as they touch credentials. State viewer tracks progress.
Add the retention cron. 15 3 * * * php /home/rubiprof/public_html/cron/nice-cxone-log-retention.php

FAQ

Does V2.5 break the macOS app?

No. The macOS app polls GET /api/v2/screenpop?pending. That response shape is unchanged. POST-side hardening (HMAC signature, idempotency) is invisible to the app. New optional fields are appended to POST responses; old clients ignore unknown keys.

What's the email-match bulk agent mapping for?

NICE CXone has its own agent IDs. Screenpops route via users.nice_agent_id. The bulk mapping page joins your active users to synced NICE agents by email (case-insensitive), preview-then-commit, with full audit per batch.

How does the TCPA / DNC gate work?

Mirror of Softphone Pro V2. NiceCxoneEngine::precheckDial joins customer_collections_metadata when present. Hard blocks: cease_and_desist, bankruptcy_filed, attorney_represented, do_not_call, collections_status='deceased'. Soft warning: outside FDCPA hours (8 AM–9 PM). Hard blocks abort with 403; warnings return 200 with requires_confirmation.

Is screenpop idempotent now?

Yes when contact_id is sent. NICE retries on transient failures return the original row's id with idempotent_replay: true. Legacy POSTs without contact_id still work as today (MySQL allows multiple NULLs in a UNIQUE index).

How does the encryption key migration work?

Dual-read: NICE_ENCRYPTION_KEY in .env is preferred; tenants.encryption_key is the fallback. Both work for decrypt. New encryptions use the .env key. Each tenant's next credentials save re-encrypts under the new key. No big-bang migration.

Does V2.5 require new permissions?

No. Click-to-dial still requires crm.calls.create or crm.*. The bulk agent mapping page is admin-only. The compliance gate is automatic.

Where do I see compliance blocks?

Tenant admin → NICE CXone Dashboard (today). System admin → /admin/view-nice-state.php (full audit). Same shape as Softphone V2's compliance audit.

Can non-collections tenants disable the TCPA gate?

The gate fails open without customer_collections_metadata. Tenants without the Collections module see no behavioral change beyond the FDCPA hours warning.

Resources

Three screenpop surfaces — know which one you're testing

RubiPro has three distinct screenpop surfaces. They look similar but serve different purposes:

/screenpop.php (root, URL-based) — NICE workflow opens this URL in the agent's browser with substituted query params ?tid=&guid=&ani=&agent=&contactid=. The "screen pop = open this URL" model. V2.5 does NOT touch this endpoint.
/api/v2/screenpop.php (JSON REST API) — POST is what NICE's outbound webhook config calls; GET /pending is what the macOS app polls. V2.5 hardens POST only; GET unchanged.
/tenant-admin/screenpop.php (tenant config + test) — shows the tenant their URL templates to paste into NICE, manages the per-tenant api_guid, and has a "Send test API screenpop" button that fires /api/v2/screenpop. V2.5 does NOT modify this page; it's the canonical test surface.

Last updated: 2026-04-27.