RingCentral Agent Availability Integration

What it does#

A CallGrid destination can ping RingCentral's call queue presence API before routing a call and only accept the call when enough agents in the queue are accepting queue calls. Calls are not sent to a RingCentral queue with nobody free to answer.

This is set up on the destination's Ping tab. The destination's outbound request is its Ping.

Prerequisites#

• A RingCentral account with admin access and a RingCentral developer app with the ReadPresence permission, which RingCentral lists for reading call queue presence.
• The app's client ID and client secret, or a way to obtain an access token.
• The Account ID (~ means the account that owns the token) and the Call Queue Group ID (RingCentral Admin Portal > Groups & Users > Call Queues > select the queue).

Setup#

Setup has six steps: create the destination, configure the ping, add authorization, set acceptance parsing, map agent availability, then test and save.

1. Create the destination#

1. Go to Buyers > Destinations and click + New Destination (or open an existing one).
2. Fill Basic Information (Name, Buyer, Timezone, Business Hours) and Call Settings (Phone Type and the number or SIP URI of the RingCentral queue).
3. Click Save Destination. The Ping tab is enabled only after the destination is saved.

2. Configure the ping#

1. Open the Ping tab.
2. Under Ping Template, choose RingCentral and fill in the Call Queue Group ID, Account ID and Bearer Authentication Token fields. Otherwise configure the request manually:
   • Method GET
   • URL https://platform.ringcentral.com/restapi/v1.0/account/~/call-queues/<CallQueueGroupID>/presence
   • Timeout for the request. Keep it short so a slow response does not hold routing.
3. Headers: Authorization: Bearer <token> if you are using a fixed token. A fixed token expires, so prefer the Authorization section below.

3. Authorization (recommended)#

Turn on Authorization so CallGrid fetches and caches the access token itself. With Authorization on, CallGrid gets an access token from a token endpoint before sending the ping and injects it into the ping's request headers.

• Token request: POST to https://platform.ringcentral.com/restapi/oauth/token with Content Type form encoded and RingCentral's JWT grant: grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer and assertion=<your JWT credential>. RingCentral recommends JWT for server apps; configure the app for JWT and create the JWT credential in the RingCentral Developer Console. Under Auth Headers, add the Basic authorization header RingCentral requires with your app's client ID and secret; [[b64:clientid:clientsecret]] inserts the base64 value.
• Token Path: access_token.
• Header Name: Authorization. Header Prefix: Bearer.
• Token TTL (sec): how long to cache the token, 60 to 86400 seconds. Set it below the expires_in value (in seconds) in RingCentral's token response.

4. Acceptance parsing#

Acceptance parsing decides whether the destination is considered for the call. Parsing types are JSON, Split, Regex and XML; operators are Equals, Not Equal To, Greater Than and Less Than.

The RingCentral response lists queue members:

1{2  "records": [3    { "member": { "id": "12345", "name": "Agent One", "extensionNumber": "101" }, "acceptQueueCalls": true, "acceptCurrentQueueCalls": true },4    { "member": { "id": "12346", "name": "Agent Two", "extensionNumber": "102" }, "acceptQueueCalls": true, "acceptCurrentQueueCalls": false }5  ]6}

acceptCurrentQueueCalls is the member's availability in this queue; acceptQueueCalls applies across all of the member's queues. Run Ping shows the exact formatting of your response.

To accept when at least one agent is accepting queue calls, use Regex parsing with Regex type Count, which counts matches of the accept flag, for example the pattern "acceptCurrentQueueCalls": true; set Property to count with Greater Than 0.

5. Field mapping#

RingCentral's presence response has no agent count, so leave Field Mapping > Agent Availability empty.

6. Test and save#

1. Under Ping Testing, fill Test Variables if the request uses tags and click Run Ping.
2. Confirm the response contains the queue members and the result shows accepted when agents are free.
3. Click Save Ping.

Rate limits and volume#

• CallGrid pings RingCentral on every call considered for this destination, so a busy campaign can hit RingCentral's API rate limits. Set Max Pings Per Minute on the destination (0 means unlimited; it applies on top of any buyer-level ping cap) to stay within them.
• If RingCentral throttles with HTTP 429, CallGrid counts it as API Failed in the Pings report, and the destination is not accepted for that call.
• Rejection Protection ("Do not reject the call or bid if the webhook http status code is not 200") keeps the destination eligible on network errors, but then calls can reach the queue when availability is unknown. Use it only if missing a call is worse than sending one to a busy queue.

Monitoring#

• Reports > Agents shows Destination, Buyer and Agents Available.
• Reports > Pings, grouped by DestinationName, shows Pings, Accepted, Failed Accept, Timeout, API Failed, Rate Ltd, Avg ms and Avg Agents for the destination.

Use cases#

• Several queues: create one destination per RingCentral call queue, each with its own Call Queue Group ID, and route by tag filters or priority.
• Overflow: give the RingCentral destination a lower Priority value than external buyers so calls go to your queue when agents are free and overflow otherwise.

Troubleshooting#

Manual check outside CallGrid:

curl -H "Authorization: Bearer <token>" \  "https://platform.ringcentral.com/restapi/v1.0/account/~/call-queues/<CallQueueGroupID>/presence"

RingCentral resources#

• RingCentral Developer Portal: https://developers.ringcentral.com/
• RingCentral API reference and authentication guide on the same portal

Do it with AI#

Ask Griddy, Claude or ChatGPT. Try: "How many of today's pings to my RingCentral queue destination were 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.