CXone agent platform
Connect LogicDialog live widget and SMS conversations to NICE CXone agents using Bring Your Own Channel (BYOC). The assistant requests human help, LogicDialog sends the recent transcript to CXone, and customer and agent messages continue through the original channel.
Email and asynchronous API conversations continue to use the LogicDialog inbox. This integration supports text messages and the BYOC 2.0 outbound callback. Attachments, templates, typing indicators and agent-initiated conversations are not supported.
Before you start
You need a CXone BYOC integration and digital channel, routing to an appropriate skill/queue, and an agent who can receive those interactions. Your CXone administrator also needs to configure the Studio system events described below. Follow NICE’s BYOC setup guide for the CXone-side setup.
In LogicDialog, choose the workspace, a workstream and the environment under Channels → CXone. Editing Channels requires integrations.manage or workspace.manage. Settings become active only after the workstream is deployed to that environment.
1. Configure LogicDialog’s access to CXone
Enter these values in the CXone tab. They let LogicDialog authenticate with NICE and send customer messages into the digital channel.
Only NICE HTTPS hosts are accepted for the API root. Tokens are obtained and refreshed automatically; you do not need to enter an access token or expiry time.
2. Configure CXone’s access to LogicDialog
Callback client ID and Callback client secret are a separate credential pair. CXone uses them to request an access token from LogicDialog before sending agent replies and system events.
Enter your chosen callback credentials or select Generate callback credentials. Copy the secret into your CXone BYOC integration before saving; saved secrets are encrypted and are not displayed again.
Use the URLs displayed in the CXone tab for the selected environment:
For example, a workspace support in the live environment could display:
Copy the displayed URLs rather than constructing them yourself: the host, workspace and environment must match your deployment. These are publicly reachable LogicDialog HTTPS endpoints, not the documentation host.
CXone posts grant_type=client_credentials, client_id and client_secret to the token URL as JSON or form data. LogicDialog returns a bearer token valid for one hour and scoped to that workspace, environment and callback client. If your CXone setup automatically appends /1.0/token to the authorization URL, the resulting /token/1.0/token path is also supported.
For outbound messages, CXone appends /2.0/channel/CHANNEL_ID/outbound to the integration box URL. Do not append that path yourself in the integration box setting. Leave Use Digital 3.0 Outbound API for replies disabled: this implementation accepts the 2.0 callback format.
If URLs are not displayed, the LogicDialog administrator needs to configure the platform public URL. See NICE’s middleware guide for the two authentication directions and BYOC message flow.
3. Optional customer and routing fields
Customer email field identifier
This is the internal identifier (ident) of an existing customer custom field in CXone. It is not the customer’s email address or the field’s display label. Ask your CXone administrator for the identifier of the customer field intended to hold email addresses.
For example, if that field’s identifier is customer_email, enter customer_email. When the trusted channel customer record contains alex@example.com, LogicDialog sends that email as the field value. LogicDialog does not create the custom field.
Leave this setting blank if you do not need email metadata. If no customer email is available, the field is omitted even when configured. Anonymous widget visitors do not currently supply an email address; configuring this identifier does not add an email collection form.
Contact topic field identifier and routing topic
The CXone contact topic field identifier is the internal ident of an existing contact custom field. Set the possible topics in Evaluation → Data collection → Topic and deploy the changes. When a handover is requested, the assistant selects one of those values and LogicDialog sends it to this CXone field.
Configure CXone routing rules for the exact topic values, including unknown for unclear or unmatched requests. Leave the field identifier blank to omit topic metadata. Legacy routing topic is retained only as a fallback for older conversations without a classification.
The topic used for handover is recorded separately from the final topic extracted after the AI conversation ends. Later analysis does not reroute the CXone contact. See Data collection and topics in the integration guides for configuration and reporting.
4. Configure system events
The CXone Studio integration must send these events as TEXT callbacks, with the text in messageContent.payload.text:
Normal text without the %% prefix is delivered as an agent reply. The callback thread’s idOnExternalPlatform must be the thread ID supplied by LogicDialog when it created the conversation in CXone. Do not substitute the original customer’s ID. When recipients are included, their IDs must also match that thread ID.
Agent departure starts a new AI session; the previous AI context is not restored. Configure transfers carefully: %%unassigned_from_agent means return to the assistant, not wait for a replacement agent.
5. Activate and test
The Agent platform tab is always available and defaults to Off. Off disables new live human handovers and omits the handover tool on the next environment deployment. Choose LogicDialog for its inbox or CXone for the external integration. Assistants must also opt into platform handover. If routing contains explicit Handover nodes, remove or reroute them before deploying with Off. This setting does not disable SIP transfers or asynchronous email/API review.
- Save the CXone settings in your workstream. This makes CXone available in the Agent platform tab for that environment; deployment is not required to select it.
- In Agent platform, choose CXone as the handover destination, save again and deploy the workstream to the intended environment.
- Start a new widget or SMS conversation and trigger the assistant’s handover tool.
- Confirm that CXone receives the recent transcript and routes the contact to the intended agent.
- Check queue and assignment events, then send messages in both directions.
- Close the case and verify that the customer returns to the assistant. Separately test customer disconnect and confirm that CXone permits the configured user to close the contact.
Use a CXone sandbox before rollout. The integration’s automated tests use mocked NICE APIs; your tenant’s permissions, Studio flow and routing need an end-to-end check.
Troubleshooting and operational behaviour
- 401: Check the callback credentials, token expiry and workspace/environment. NICE application credentials and LogicDialog callback credentials are not interchangeable.
- 403: Confirm CXone is the deployed handover destination and that the callback channel ID matches the configured CXone channel ID.
- 404: Confirm the conversation is still active and the callback reaches the API instance owning it.
- 422: Check for unsupported message types, unknown system events or an incompatible outbound API version.
- 502: Check NICE connectivity and application permissions. Contact-close failures are logged as
cxone.close.failedfor follow-up.
Live relay sessions are held in the owning API process. Callbacks must reach that instance, and active handovers do not survive an API restart. Duplicate replies are suppressed when CXone supplies a stable message ID; callbacks without one cannot be reliably deduplicated.
Finish active CXone conversations before changing the destination, credentials or channel ID. Callback requests validate against deployed settings. Existing conversations are not moved to another platform automatically. CXone customer messages, agent replies and notices are saved in LogicDialog’s Conversations history, using the existing live-chat storage (30-day retention and the current transcript limit). Persist that storage volume to retain history across API restarts. CXone conversations do not appear in the LogicDialog operator queue and cannot be claimed or replied to there. Returning to AI creates a separate assistant session.