> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poly.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Genesys

> Connect your PolyAI agent to Genesys Cloud with a guided BYOC SIP trunk setup in Agent Studio.

Connect PolyAI to Genesys Cloud over a SIP trunk so calls to your Genesys numbers reach your PolyAI agent. Agent Studio guides you through creating the PolyAI side of the trunk, then gives you the details to finish the setup in Genesys Cloud admin.

## Before you start

* **Know your Genesys model.** The guided setup supports [BYOC Cloud](https://help.genesys.cloud/articles/about-byoc-bring-your-own-carrier/), where calls run on Genesys Cloud's own infrastructure. If you run your own Genesys Edge devices (BYOC Premises), you use the generic SIP trunk setup instead.
* **Know your Genesys Cloud region.** This is the region your Genesys Cloud organization runs in, for example US East (Virginia) or EU (Frankfurt).
* **Admin access in Genesys Cloud.** You need [permission to manage external trunks](https://help.genesys.cloud/articles/external-trunk-settings/) to finish the setup.
* **Numbers to route.** Have the phone numbers or extensions ready, written exactly as Genesys will send them to PolyAI.

<Note>
  If the **Genesys** option shows **Coming soon**, contact your PolyAI account manager.
</Note>

## Start the guided setup

1. In Agent Studio, go to **Integrations** and open the **Telephony** tab.
2. Click **Add number**. The **Add a number** panel opens.
3. Under **Integrate with your contact center platform**, select **Genesys**.

The **Genesys Cloud setup** opens. It has five steps: **Model**, **Trunk details**, **Numbers**, **Review** and **Reference**.

<Steps>
  <Step title="Model">
    Answer **Which Genesys model do you use?**

    * **BYOC Cloud** (marked **Fastest setup**): you use Genesys Cloud's own infrastructure, with no edge devices or carrier connections of your own. Pick this if you're not sure.
    * **BYOC Premises**: you've deployed your own Genesys Edge devices.

    Select **BYOC Cloud** and click **Next**.

    If you select **BYOC Premises**, Agent Studio explains that it needs a fully custom trunk. Click **Continue to SIP setup** to switch to the generic SIP trunk setup. See [Custom SIP](/integrations/voice/sip/custom-sip) for that path.
  </Step>

  <Step title="Trunk details">
    1. Choose your **Genesys Cloud region**. The list shows each region with its Genesys domain, for example **US East (Virginia) — mypurecloud.com**. The region decides which Genesys IP ranges reach PolyAI. Agent Studio also uses it to prefill the trunk **Name**, such as `Genesys Cloud — US East (Virginia)`.
    2. Copy your region's BYOC Cloud signaling and media IP ranges from the Genesys Cloud Resource Center. For signaling, see [BYOC Cloud public SIP IP addresses](https://help.genesys.cloud/articles/byoc-cloud-public-sip-ip-addresses/). PolyAI rejects calls from any address you don't list.
    3. Fill in the trunk fields:

    | Field | What to enter |
    | - | - |
    | **Name** | A name for the trunk. Prefilled from your region; you can change it. Up to 255 characters. |
    | **Encrypted** | Always on for Genesys. Calls use SIP over TLS with SRTP media. |
    | **SIP CIDR blocks** | The Genesys signaling IP ranges for your region. |
    | **RTP CIDR blocks** | The Genesys media IP ranges for your region. |
    | **Inbound authentication** | **IP allowlist only**, **SIP digest** (enter a **Username** and **Password**) or **Token** (enter a **Token**). PolyAI always enforces your CIDR allowlist as well. |

    <Tip>
      CIDR fields accept IPv4 ranges separated by commas or spaces. Each field needs at least one range and takes up to 10. Each range must be `/18` or smaller, and written in canonical form (for example `203.0.113.0/24`, not `203.0.113.5/24`). Agent Studio suggests the corrected range if you enter one with host bits set.
    </Tip>

    Click **Next**.
  </Step>

  <Step title="Numbers">
    Under **Numbers and routing**, add each number that should reach your agent:

    * **Extension**: the dialed number or extension as it arrives on this trunk, for example `+441234567890`. Enter it exactly as Genesys sends it.
    * **Environment**: which environment of your agent answers calls to this number.
    * **Variant** (optional): routes calls to a specific variant of the agent. Leave empty for the default.

    Click **Add** for each number. You must add at least one number to continue.
  </Step>

  <Step title="Review">
    Check the **Basics**, **Network and encryption**, **Authentication** and **Numbers** sections. Click **Edit** next to a section to change it, then click **Create trunk**.

    Agent Studio creates the trunk and shows **Genesys Cloud connected**. If a number fails to save, Agent Studio tells you which one. Add it again from the trunk's card on the **Telephony** tab.
  </Step>

  <Step title="Reference">
    The **Reference** step shows **Finish in Genesys Cloud** and the connection details you need. See [Configure Genesys Cloud](#configure-genesys-cloud).

    Click **Done** to close the setup. The trunk and its numbers then appear on the **Telephony** tab, where you can view the same connection details again.
  </Step>
</Steps>

## Connection details

The **Reference** step lists everything Genesys needs. Each value has a copy button.

* **Connection basics**: **Encryption**, **Port** (5061), **Signalling** (SIP over TLS), **Media** (SRTP over UDP), **RTP port range**, your **SIP CIDR** and **RTP CIDR** ranges, and **Authentication**.
* **TLS certificates**: **TLS version** 1.2, the **PolyAI root certificate** (DigiCert Global Root G2), and the requirement that **Your certificate** is signed by a publicly trusted certificate authority.
* **How to reach PolyAI**: the **SIP trunk A record** (**Recommended**) and its SIP URI, plus a **Global A record** and an **SRV service and protocol** record with their SIP URIs. If one option doesn't work with your platform, try one of the others.
* **Identifying this trunk**: the **Trunk ID**, the **Header** and **URI parameter** that carry it, and, depending on your authentication choice, the digest **Username** and **Realm** or the **Token header**.

### Use an AI assistant

The reference includes **Have an AI assistant connect your platform**. Copy the prompt and paste it into an AI assistant that can work in your Genesys Cloud admin console. The prompt contains this trunk's settings. The assistant points a trunk at PolyAI and replies with what it configured.

## Configure Genesys Cloud

Finish the setup in Genesys Cloud admin, using the values from the **Reference** step.

1. In Genesys Cloud admin, go to **Telephony** > **Trunks** and create an external trunk of type **BYOC Cloud**.
2. Set the trunk SIP server to the PolyAI **SIP trunk A record** on port `5061`, using TLS for signaling and SRTP for media.
3. If you chose **SIP digest** or **Token** authentication, configure the same credentials on the Genesys trunk. For a token, send it in the header shown as **Token header**.
4. If your organization restricts SIP traffic by IP address, allow the addresses the PolyAI trunk address resolves to.
5. Attach the trunk to a route so calls to your numbers reach it.

<Tip>
  Configure the trunk to use the `audio/PCMU` codec.
</Tip>

## Pass call data between Genesys and PolyAI

### Data on the inbound INVITE

The Genesys SIP INVITE can include:

* `x-inin-cnv`: the Genesys [conversation ID](https://developer.genesys.cloud/commdigital/digital/openmessaging/gettingConversationId).
* `X-User-to-User`: custom data, in the format `X-User-to-User:{data};encoding=ascii`. To send it, set UUI passthrough on the Genesys trunk with protocol `X-User-to-User` and encoding `Ascii`.

Your agent can read these values from `conv.sip_headers`. See [Custom SIP](/integrations/voice/sip/custom-sip).

### Data on the SIP REFER

To return data to Genesys when your agent transfers a call, use this format in the SIP REFER:

`Refer-To: <sip:{route}@{ip}?User-to-User={pd}{data}%3Bencoding%3Dhex>`

* Replace `{pd}` with the protocol discriminator (two hex digits).
* Replace `{data}` with the hex-encoded information.

### Screen pop with the Handoff API

If you need a [screen pop](https://all.docs.genesys.com/PEC-GPA/Current/Administrator/GplusScreenPop90) for live agents, Genesys can fetch the handoff data your agent saved through the [Handoff API](/api-reference/handoff/introduction). Create an API key in Agent Studio for this.

## Change or remove the trunk

On the **Telephony** tab, open the Genesys trunk's menu:

* **Add number** adds another number to the trunk.
* **Edit configuration** changes the name, CIDR ranges or authentication. Secrets are never shown again; leave a secret field blank to keep the stored one.
* **Remove trunk** deletes the trunk. Every call routing over it stops, including calls to its numbers. This cannot be undone.

## Related pages

<CardGroup cols={2}>
  <Card title="Custom SIP" icon="phone" href="/integrations/voice/sip/custom-sip">
    Read SIP headers in your agent, and set up a generic SIP trunk for BYOC Premises.
  </Card>

  <Card title="Handoffs" icon="right-left" href="/voice-channel/handoffs">
    Configure where and how your agent transfers calls.
  </Card>
</CardGroup>