> For a complete page index, fetch https://docs.synthflow.ai/llms.txt. For full documentation content, fetch https://docs.synthflow.ai/llms-full.txt.

# RingCX

> Integrate Synthflow AI as an Intelligent Virtual Agent (IVA) in RingCX voice queues using SIP.

RingCX supports Intelligent Virtual Agent (IVA) integrations over SIP, letting you route voice queue calls to a Synthflow AI agent. You create an IVA integration in RingCX, import the workflow number into Synthflow as a custom phone number, build a workflow that hands calls to Synthflow, and use the JavaScript node in Workflow Studio to pass caller context to the agent.

## 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.

## Import the number into Synthflow

Before configuring RingCX, import the workflow channel number into Synthflow as a custom phone number.

1. In the Synthflow dashboard, go to **Phone Numbers** and click **Import Phone Number**.
2. Configure the following fields:

| Field              | Value                               |
| ------------------ | ----------------------------------- |
| **Phone Provider** | Custom                              |
| **Phone Number**   | Your RingCX workflow channel number |
| **Friendly Name**  | A label such as `RingCX`            |
| **SIP Domain**     | `sip.ringcentral.com`               |

3. Click **Import** to save the number.

After importing, the **Origination URI** field shows `sip:sip.synthflow.ai:32681`. This is the address RingCX sends calls to and is auto-populated by Synthflow.

![Synthflow Phone Numbers page showing the imported RingCX number with SIP Domain and Origination URI](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/99cbfbee50bb09aff975b2c6e8951877f7a19943607775817f9309e660b3d8f0/docs/assets/screenshots/ringcx_synthflow_import.png)

4. Open the agent you want to receive calls, go to the **Configure** tab, scroll to the **Phone number** section, select the RingCX number you imported, and click **Save**.

One phone number can be assigned to one inbound agent at a time. If you need to reassign the number, remove it from the current agent first. For more on number management, see [Phone numbers](/about-phone-numbers).

## Create the IVA integration in RingCX

1. Sign in to RingCX and click the **Admin** tile.
2. Click **AI Tools** in the left navigation bar, then click **IVA Integrations**.
3. Click **New Integration** and fill in the fields:

| Field           | Value                                          |
| --------------- | ---------------------------------------------- |
| **Name**        | A label such as `Synthflow.Ai`                 |
| **Description** | Optional                                       |
| **SIP URI**     | `sip:<workflow_number>@sip.synthflow.ai:32681` |
| **Transport**   | UDP                                            |

Replace `<workflow_number>` with the channel number you imported into Synthflow (in E.164 format, e.g. `+15206414405`).

4. Select the **Active** checkbox to make the integration available in your workflows.
5. Click **Save**.

The SIP URI must include the phone number in the user part. If you omit it (e.g. `sip:sip.synthflow.ai:32681` with no number), RingCX sends an IP-only Request-URI and Synthflow rejects the call because it cannot determine which agent should handle it.

![RingCX IVA Integrations page showing the Synthflow integration with SIP URI and transport settings](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/32909ec99e3117b7b791a06299b8b3f35071c1cff5bbda99d190c5f22aa558cc/docs/assets/screenshots/ringcx_iva_integration.png)

## Build the workflow

### Add the IVA to a workflow

1. Sign in to RingCX and click the **Admin** tile.
2. Click **Categorization** in the left navigation bar, then click **Workflows**.
3. Expand the workflow group that contains your target workflow, then click the workflow.
4. Click **Workflow Studio** in the left navigation panel.
5. Drag and drop a **JavaScript** node from the left panel and place it before the IVA node (see [Pass caller context with the JavaScript node](#pass-caller-context-with-the-javascript-node) below).
6. Drag and drop the **IVA** node from the left panel onto the canvas after the JavaScript node.
7. Hover over the IVA node and click **Edit**.
8. Select the Synthflow integration you created.
9. Optionally provide a **Context Filter** to control what session data is shared with Synthflow (e.g. `visibleData`).
10. Click **OK**.
11. Connect the JavaScript node to the IVA node. When prompted for a **Connection ID**, enter `success`.

![Workflow Studio showing a workflow with Start, Answer, JavaScript, Connect IVA, and Hangup nodes](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/ed8f577b5407e4c272955d1117579f614b3000d002cb26cbe27ff41353b0961b/docs/assets/screenshots/ringcx_workflow_studio.png)

Once the IVA session completes, the call returns to the workflow and follows one of the configured connections:

* **Success:** The IVA session completed successfully and returned a result. The customer is still connected and the workflow continues.
* **Failed:** The IVA session did not complete successfully. The customer is still connected and the workflow continues on the error handling path.
* **Disconnected:** The customer disconnected before or during the IVA session. The workflow does not continue.

### Pass caller context with the JavaScript node

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

1. Drag and drop the **JavaScript** node from the left panel and place it before the IVA node.
2. Hover over the JavaScript node and click **Edit**.
3. Add the following script to build `sessionData` with the caller's ANI:

```javascript
var ani = ivr.getAni();
var uii = ivr.getUii();

sessionData = {
  visibleData: {
    ani: ani,
    callID: uii
  }
};

ivr.debug("sessionData to IVA: " + JSON.stringify(sessionData));
```

![Workflow Studio with JavaScript Properties panel open showing sessionData code](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/cc1a63d5d9bb3103c29517fc5555142bfc2bd56ba8b5c95a32fdfdf48a0113e0/docs/assets/screenshots/ringcx_javascript_properties.png)

Do not declare `sessionData` with `var`. Using `var sessionData` creates a local variable that shadows the workflow-level global, which prevents the data from reaching the IVA node.

### Filter context sent to the IVA

You may want to send only part of the workflow `sessionData` to Synthflow. Configure a **Context Filter** in the IVA node properties:

1. Hover over the IVA node and click **Edit**.
2. Enter a filter name in the **Context Filter** field (e.g. `visibleData`). The workflow searches `sessionData` for a property matching that name and sends only that nested object to the IVA.

![Connect IVA Properties panel showing the Synthflow integration and Context Filter field](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/83c309b3b016a3a8ded4eb94459238f6bfa0cbb601f38c2118ac17f4f71883ac/docs/assets/screenshots/ringcx_iva_node_properties.png)

The Context Filter is optional. If left empty, the full `sessionData` is sent to the IVA. If the filter name does not match any property in `sessionData`, the full `sessionData` is sent as a fallback.

### Read IVA response data

After the IVA session completes and the call returns to the workflow, any metadata returned by Synthflow is available in the `sessionData` property. Use a JavaScript node after the IVA node to access this data.

![Workflow Studio showing JavaScript Connection Properties and Connect IVA Properties panels](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/08697de2af638e4683e15499c91a38216686269ac71990248f8d8c1afba2dac9/docs/assets/screenshots/ringcx_javascript_connection.png)

## Add the 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 a payload back to RingCX containing any variables you define, then the RingCX workflow continues from the IVA node's **Success** connection.

1. In the Synthflow dashboard, open the agent assigned to your RingCX number.
2. Go to the **Actions** tab and click **Add Action**.
3. Select **RingCX Handoff**.
4. Set the **Condition Description** to tell the agent when to trigger the handoff (e.g. "When the customer says goodbye").
5. Define payload fields using the **Payload** section. Each field is a key-value pair that gets sent back to RingCX as part of the IVA response data. For example, add a `final` field set to `true` to signal that the handoff is complete.

![RingCX Handoff action configuration showing condition description, payload fields, and payload preview](https://files.buildwithfern.com/synthflow.docs.buildwithfern.com/63695e333231788160a863f3db67d953cdae8d296d2f8b453664d6caa9fd57a1/docs/assets/screenshots/ringcx_handoff_action.png)

You can add multiple payload fields to pass collected information back to the RingCX workflow. For example, if your Synthflow agent collects the caller's intent, account number, or appointment preference during the conversation, add those as payload fields so the RingCX workflow can route or act on them.

RingCX receives the payload as context only. The RingCX workflow owner must parse the payload in a downstream JavaScript node before routing on fields like `intent`.

## Usage

### Inbound call handling

Once configured, calls that reach the IVA node in your workflow are routed to your Synthflow AI agent. The agent answers, follows its configured prompt, and can perform any available actions (booking, data collection, handoff).

### Returning calls to RingCX

Use the [RingCX Handoff action](#add-the-ringcx-handoff-action) to end the IVA session and return the call to the RingCX workflow. Define payload variables on the action to pass data collected by Synthflow (such as caller intent, account details, or next steps) back to RingCX, where the workflow can parse and route on them.

### Call transfers

Direct call transfers from Synthflow are not supported on RingCX trunks. The RingCX SIP trunk does not allow Synthflow to initiate transfers to external numbers or SIP endpoints during a call.

To transfer 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 from there using RingCX's built-in queue, skill, or transfer nodes. This approach gives you full control over routing logic within RingCX Workflow Studio.

### Call recordings and transcripts

Call recordings and transcripts are available in the Synthflow dashboard under the agent's call history, the same as any other Synthflow call.

## FAQ

The SIP URI format is `sip:<workflow_number>@sip.synthflow.ai:32681`. Replace `<workflow_number>` with your RingCX workflow channel number in E.164 format (e.g. `+15206414405`). The number must also be imported as a custom phone number in the Synthflow dashboard.

Select **UDP** in the Transport field when creating the IVA integration.

Set the SIP Domain to `sip.ringcentral.com` when importing the RingCX workflow number as a custom phone number in Synthflow.

The JavaScript node builds the `sessionData` object that RingCX sends to Synthflow in the `X-Bot-Context` SIP header. Without it, your agent receives no caller context (ANI, call ID, or any custom metadata).

The call follows the **Failed** connection path in your workflow. The customer remains connected, so you can route them to a queue, another IVA, or a hangup node.

No. The RingCX SIP trunk does not support direct call transfers from Synthflow. Use the RingCX Handoff action to return the call to the RingCX workflow, then handle routing with RingCX's queue, skill, or transfer nodes.

Add payload fields to the RingCX Handoff action. Each field is a key-value pair sent back to RingCX when the IVA session ends. Use a JavaScript node after the IVA node in your RingCX workflow to parse the returned `sessionData` and route based on fields like intent or account number.