NICE inContact Agent Availability Integration

Overview#

This integration lets a CallGrid destination check live agent availability in a NICE inContact (NICE CXone) contact center before a call is sent. The destination's Ping calls NICE's real-time data API for each call or bid. If no agents with the right skill are available, acceptance parsing rejects the ping and CallGrid routes the call elsewhere.

Where it lives: Buyers > Destinations > Edit Destination > Ping tab. It is a destination Ping, not an integration webhook.

Prerequisites#

• NICE inContact administrator access and an API application with real-time data permissions.
• NICE CXone API credentials. NICE access tokens expire (the token response gives the lifetime in expires_in), so you need the client ID and secret NICE issues when your application is registered, plus an access key ID and secret for the CXone user the integration runs as.
• The NICE skill (or skills) whose agents take these calls.
• A CallGrid destination that dials the NICE inbound number or SIP address for that skill.

Step 1: Get NICE credentials#

1. Register your integration with NICE (the Getting Started guide on NICE's developer portal, developer.niceincontact.com, describes the registration form); NICE replies with a client ID and secret. Then in CXone open Admin > Employees, select the integration user, open the Security tab and click Generate New Access Key. Copy the secret key; CXone shows it only once.
2. Grant it access to real-time agent and skill data.
3. Note the API base URL for your NICE cluster and the skill IDs to monitor.
4. NICE access tokens expire. For the Authorization section in Step 3, follow NICE's developer Getting Started guide (https://developer.niceincontact.com/Documentation/GettingStarted) for how to request a token with your client ID and secret and access key.

Step 2: Create or open the destination#

1. Buyers > Destinations, create or edit the NICE destination.
2. Call Settings > Phone Type: Phone or SIP pointing at the NICE inbound entry for the skill.
3. Capacity and Limit Settings: set Max Concurrent Calls to the seat count as a backstop, and consider Capacity Guard so one available agent is not sent overlapping calls from several auction wins.
4. Save the destination. The Ping tab is enabled once the destination is saved.

Step 3: Configure the Ping#

1. Open the Ping tab and enable the ping integration.
2. In the Ping Template picker, choose NICE inContact and fill in the Bearer Authentication Token. Otherwise configure manually.

Request#

Tip: if Run Ping fails, use your own NICE API host for your area. NICE API hosts follow https://api-{area}.{domain}, for example https://api-na1.niceincontact.com; NICE's API discovery returns your area and domain. Replace the host in the URL and keep the path.

If the endpoint takes a JSON body, for example to filter by skill, take the field names from NICE's Real-Time Data API reference rather than guessing. CallGrid tags such as [[tag:InboundStateCode]] can be used in body values. InboundNumber and InboundStateCode are default CallGrid tags. A state-specific skill can be chosen by routing different states to different destinations with Tag Routing Rules, rather than by relying on NICE to interpret the state.

Authentication#

• Static token: under Headers, add Authorization: Bearer YOUR_TOKEN. This is authentication to NICE, not to CallGrid.
• Rotating OAuth token: NICE access tokens expire, so a pasted static token stops working. Enable Authorization. Enter the token request as NICE's developer Getting Started guide describes it, set Token Path (for example access_token), Header Name Authorization, Header Prefix Bearer and Token TTL between 60 and 86400 seconds, below the expires_in value in NICE's token response. CallGrid caches the token for the TTL and injects it into the ping headers.

Acceptance Parsing#

Parsing Type JSON (also Split, Regex, XML). Operators: Equals, Not Equal To, Greater Than, Less Than.

The NICE inContact template accepts on agentsAvaliable Greater Than 0. The template's key is spelled agentsAvaliable, exactly as shown. Run Ping and read the response: if it uses agentsAvailable instead, change the acceptance path and the Field Mapping path below to agentsAvailable.

Field Mapping#

Map agentsAvaliable (or agentsAvailable, to match the response) to Agent Availability to record available agents.

Rejection Protection#

Leave it off if an API error should stop calls going to NICE. Turn it on only if a non-200 response should not reject the destination (for example during brief NICE API blips), accepting that calls may reach a skill with no agents.

Step 4: Test#

1. In Ping Testing, fill any Test Variables the request uses (for example InboundNumber 5551234567, InboundStateCode CA).
2. Click Run Ping and read the raw NICE response.
3. Confirm acceptance passes when agents are available and fails when none are.
4. Click Save Ping, add the destination to the campaign routing, and place a test call.

Reproduce outside CallGrid if needed:

curl -X POST "https://api.niceincontact.com/real-time-data/skills-activity-search" \  -H "Authorization: Bearer YOUR_NICE_TOKEN"

Timeouts and rate limits#

• The Ping Timeout applies to this destination. Campaign > Sources > Configure source overrides > Webhook Timeout overrides destination ping timeouts for a source (the label still says Webhook). To exempt NICE, turn on Override Timeout on the NICE destination's Ping so it keeps its own timeout. The Webhook Timeout minimum is 1 second.
• Use Max Pings Per Minute on the destination, and the buyer-level ping cap, to keep ping volume within what NICE allows for your account; ask NICE for your API limits.
• A 429 from NICE is counted as API Failed in the Pings report, the same bucket as genuine errors.

Monitoring#

• Reports > Agents: Destination, Buyer, Agents Available.
• Reports > Pings for the destination: Accepted, Failed Accept, Timeout, Timeout %, API Failed, Rate Ltd, Avg ms, Avg Agents.
• Per-call ping requests and responses are visible on the call timeline and the Pings detail log.

Troubleshooting#

Do it with AI#

Ask Griddy, Claude or ChatGPT. Try: "Show me the pings to my NICE inContact destination from the last hour and whether each one was accepted." Claude and ChatGPT need the CallGrid connector turned on (setup guides for Claude and ChatGPT).

The connector is read only. It looks things up and reads your data. You make the changes in CallGrid.