RingCX

RingCX routes voice queue calls to a Synthflow agent through an Intelligent Virtual Agent (IVA) integration over SIP. Calls that reach the IVA node in a RingCX workflow go to the agent, which answers, follows its prompt, and runs its actions, such as booking or data collection.

You import the RingCX workflow channel number into Synthflow, create an IVA integration in RingCX, and add the IVA to a workflow in Workflow Studio. A JavaScript node passes caller context to the agent, and the RingCX Handoff action returns the call to the workflow when the agent is done.

Prerequisites

• A RingCX account with admin access.
• A Synthflow account on the Enterprise plan with a deployed agent.
• A RingCX workflow channel number to use as the SIP URI.

Number import

Import the workflow channel number into Synthflow before you configure RingCX.

1. In Synthflow, select Phone Numbers → New Phone Number → Import a Custom Number.
2. Fill in the fields below.
3. Select Import.

Synthflow sets the SIP domain to sip.ringcentral.com. After the import, the Origination URI field shows the address RingCX sends calls to, for example sip:sip.synthflow.ai:32681 on a Global workspace.

Then assign the number to the agent that should receive calls, under Deploy in the agent editor.

IVA integration

1. Sign in to RingCX and select the Admin tile.
2. In the left navigation bar, select AI Tools → IVA Integrations.
3. Select New Integration and fill in the fields below.
4. Select the Active checkbox to make the integration available in your workflows.
5. Select Save.

Replace <workflow_number> with the channel number you imported into Synthflow, in E.164 format, for example +15206414405. For US or EU workspaces, replace sip.synthflow.ai with your region’s SIP address, the same host shown in the number’s Origination URI.

Workflow

The workflow hands calls to Synthflow through an IVA node, with a JavaScript node before it to pass caller context.

1. Sign in to RingCX and select the Admin tile.
2. In the left navigation bar, select Categorization → Workflows.
3. Expand the workflow group that contains your target workflow, then select the workflow.
4. Select Workflow Studio in the left navigation panel.
5. Drag a JavaScript node from the left panel onto the canvas, and add the script from JavaScript node.
6. Drag the IVA node from the left panel onto the canvas after the JavaScript node.
7. Hover over the IVA node and select Edit.
8. Select the Synthflow integration you created.
9. Optionally, enter a Context Filter, such as visibleData, to limit the session data sent to Synthflow. See Context Filter.
10. Select OK.
11. Connect the JavaScript node to the IVA node. When prompted for a Connection ID, enter success.

IVA connections

When the IVA session ends, the call returns to the workflow and follows one of the IVA node’s connections:

• Success: The IVA session completed and returned a result. The customer is still connected, and the workflow continues.
• Failed: The IVA session did not complete. The customer is still connected, and the workflow continues on the error handling path, for example to a queue, another IVA, or a hangup node.
• Disconnected: The customer hung up before or during the IVA session. The workflow does not continue.

Session data

RingCX and Synthflow exchange data through the workflow’s sessionData object. RingCX sends it to Synthflow in the X-Bot-Context SIP header, and Synthflow returns data to it when the IVA session ends.

JavaScript node

A JavaScript node before the IVA node is required to pass the caller’s ANI (phone number), DNIS, and other metadata to Synthflow. Without it, the X-Bot-Context header arrives empty, and the agent receives no caller information.

Hover over the JavaScript node, select Edit, and add this script. It builds sessionData with the caller’s ANI, DNIS, and call ID:

var ani = ivr.getAni();
var dnis = ivr.getDnis();
var uii = ivr.getUii();
sessionData = {
  visibleData: {
    ani: ani,
    dnis: dnis,
    callID: uii
  }
};
ivr.debug("sessionData to IVA: " + JSON.stringify(sessionData));

You can add other keys to visibleData besides ani, dnis, and callID. Synthflow exposes each one as a flattened variable, for example {X-Bot-Context.accountId}.

Context Filter

The Context Filter in the IVA node properties sends only part of sessionData to Synthflow. Enter a property name, such as visibleData. The workflow searches sessionData for a property with that name and sends only that nested object.

The Context Filter is optional. If it is empty, RingCX sends the full sessionData. If the name does not match any property in sessionData, RingCX also falls back to sending the full sessionData.

Context variables

RingCX sends the filtered sessionData as a JSON-encoded string in the X-Bot-Context header. Synthflow flattens that JSON into header variables with dot notation. You can reference nested fields directly in prompts, greeting messages, custom actions (URLs and bodies), and call transfers.

With the JavaScript example above and a Context Filter of visibleData, the flattened variables are:

Example prompt:

The caller's phone number is {X-Bot-Context.ani}.
The number they dialed is {X-Bot-Context.dnis}.
Reference call ID {X-Bot-Context.callID} when looking up their account.

Example before-the-call action body:

{
  "phone_number": "{X-Bot-Context.dnis}",
  "ani": "{X-Bot-Context.ani}"
}

Without a Context Filter, Synthflow receives the full sessionData object, and the nested keys include the visibleData prefix, for example {X-Bot-Context.visibleData.ani} and {X-Bot-Context.visibleData.dnis}.

Custom fields follow the same {X-Bot-Context.field} pattern. Array values use 0-based bracket notation, for example {X-Bot-Context.items[0].id}.

IVA response data

After the IVA session ends and the call returns to the workflow, any data Synthflow returns is in the sessionData property. Read it with a JavaScript node after the IVA node. To send data back, add payload fields to the RingCX Handoff action.

RingCX Handoff action

The RingCX Handoff action ends the Synthflow IVA session and returns the call to the RingCX workflow. When the action fires, Synthflow sends RingCX a payload with the variables you define, and the workflow continues from the IVA node’s Success connection.

1. In Synthflow, open the agent assigned to your RingCX number.
2. Go to the Actions tab and select Add Action.
3. Select RingCX Handoff.
4. In Condition Description, tell the agent when to hand off, for example “When the customer says goodbye”.
5. In the Payload section, add the fields to send back. Each field is a key-value pair that RingCX receives as IVA response data. For example, add a final field set to true to signal that the handoff is complete.

Add a payload field for each value the agent collects that the workflow needs, such as the caller’s intent, account number, or appointment preference. The workflow can then route or act on them.

Call transfers

To send a caller to a live agent or another destination, use the RingCX Handoff action to return the call to the RingCX workflow. Then route it with RingCX’s queue, skill, or transfer nodes in Workflow Studio.

Call recordings and transcripts

Recordings and transcripts of RingCX calls appear in the agent’s call history in Synthflow, the same as any other Synthflow call.