> 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

> Route RingCX voice queue calls to a Synthflow agent over SIP through an Intelligent Virtual Agent (IVA) integration.

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

| Field              | Value                               |
| ------------------ | ----------------------------------- |
| **Phone Provider** | RingCX                              |
| **Phone Number**   | Your RingCX workflow channel number |
| **Friendly Name**  | A label such as `RingCX`            |

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.

![Synthflow Phone Numbers page showing the imported RingCX number with SIP Domain and Origination URI](/_fern-img/99cbfbee50bb09aff975b2c6e8951877f7a19943607775817f9309e660b3d8f0.webp)

Then assign the number to the agent that should receive calls, under **Deploy** in the [agent editor](/the-agent-editor).

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

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

| 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, for example `+15206414405`. For US or EU workspaces, replace `sip.synthflow.ai` with your region's [SIP address](/connect-over-sip#sip-addresses), the same host shown in the number's **Origination URI**.

> **Warning**
>
> The SIP URI must include the phone number in the user part. Without it (for example `sip:sip.synthflow.ai:32681`), RingCX sends an IP-only Request-URI, and Synthflow rejects the call because it cannot tell which agent should handle it.

![RingCX IVA Integrations page showing the Synthflow integration with SIP URI and transport settings](/_fern-img/32909ec99e3117b7b791a06299b8b3f35071c1cff5bbda99d190c5f22aa558cc.webp)

## 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](#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](#context-filter).
10. Select **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](/_fern-img/ed8f577b5407e4c272955d1117579f614b3000d002cb26cbe27ff41353b0961b.webp)

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

```javascript
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}`.

![Workflow Studio with JavaScript Properties panel open showing sessionData code](/_fern-img/cc1a63d5d9bb3103c29517fc5555142bfc2bd56ba8b5c95a32fdfdf48a0113e0.webp)

> **Note**
>
> Do not declare `sessionData` with `var`. `var sessionData` creates a local variable that shadows the workflow-level global, so the data never reaches the IVA node.

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

![Connect IVA Properties panel showing the Synthflow integration and Context Filter field](/_fern-img/83c309b3b016a3a8ded4eb94459238f6bfa0cbb601f38c2118ac17f4f71883ac.webp)

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](/pass-call-context#header-values) with dot notation. You can reference nested fields directly in prompts, greeting messages, [custom actions](/actions-overview) (URLs and bodies), and [call transfers](/call-transfers).

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

| Variable                 | Source                                    |
| ------------------------ | ----------------------------------------- |
| `{X-Bot-Context.ani}`    | Caller ANI from `ivr.getAni()`            |
| `{X-Bot-Context.dnis}`   | Dialed number (DNIS) from `ivr.getDnis()` |
| `{X-Bot-Context.callID}` | Call UII from `ivr.getUii()`              |

**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](/pass-call-context#before-the-call-actions) body:**

```json
{
  "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).

![Workflow Studio showing JavaScript Connection Properties and Connect IVA Properties panels](/_fern-img/08697de2af638e4683e15499c91a38216686269ac71990248f8d8c1afba2dac9.webp)

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

![RingCX Handoff action configuration showing condition description, payload fields, and payload preview](/_fern-img/63695e333231788160a863f3db67d953cdae8d296d2f8b453664d6caa9fd57a1.webp)

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.

> **Note**
>
> 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`.

## Call transfers

> **Warning**
>
> Synthflow cannot transfer calls directly on RingCX trunks. The RingCX SIP trunk does not let Synthflow start transfers to external numbers or SIP endpoints during a call.

To send a caller to a live agent or another destination, use the [RingCX Handoff action](#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.