---
title: "Connect from Genesys Cloud"
description: "Send Genesys Cloud calls to a ThunderPhone agent over a BYOC Cloud trunk with the conversation id and UUI, and take them back with the hand-off in UUI."
---

Your Architect flow sends the caller to the agent over a BYOC Cloud trunk, with
the conversation id and any UUI you set. When the caller needs a person, the
agent sends a SIP `REFER`, Genesys takes the call back, and the hand-off id
arrives in the call's UUI.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- Genesys Cloud with BYOC Cloud, and an external trunk (type BYOC Carrier or
  PBX) with these settings turned on
  ([external trunk settings](https://help.genesys.cloud/articles/external-trunk-settings/)):
  - **Conversation Headers**, so Genesys sends its conversation id in
    `x-inin-cnv`. It is off by default.
  - **UUI Passthrough**, with header type `User-To-User` and encoding Hex.
  - **Take Back and Transfer**, so Genesys accepts the agent's `REFER`.

## 1. Create the SIP endpoint

Genesys answers a digest challenge, so use a standard endpoint:

```bash
curl -X POST https://api.thunderphone.com/v1/sip-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": 12, "name": "Genesys Cloud"}'
```

Store the `password` from the response straight away; it is shown once. On the
trunk:

| Setting | Value |
|---|---|
| SIP server | `sip.thunderphone.com`, port `5061` |
| Protocol | TLS |
| Digest authentication | the endpoint's `username` and `password` |
| Codecs | PCMU, PCMA or G.722 |

Put the trunk on an outbound route of your site whose number plan covers the
address the flow dials.

## 2. Send calls with context

In your Architect flow:

1. Optionally, add a **Set UUI Data** action with context for the agent, such
   as `account=12345`. Genesys recommends 128 characters or fewer.
2. Add a **Transfer to Number** action with the endpoint's `sip_uri`, for
   example `sip:agent-12-jhxmginwjx@sip.thunderphone.com`.

Genesys sends the conversation id in `x-inin-cnv`. ThunderPhone stores it as
the call's `external_call_id`. The UUI reaches the prompt decoded, as
`{{sip_uui}}`.

Trunk custom headers are static in Genesys, so put per-call values in the UUI.
Genesys reserves the `x-inin`, `x-genesys`, `x-pcv` and `x-gcv` header prefixes
for itself.

## 3. Get the call back

The agent transfers with a `REFER` to an address on Genesys, with the hand-off
id as hex UUI inside that address. Add this transfer number (see
[Add the transfer number](/guides/contact-centers/overview#add-the-transfer-number)
and [Headers inside the transfer address](/guides/call-transfers#headers-inside-the-transfer-address)):

```json
{
  "name": "Genesys support",
  "number": "sip:support@acme.byoc.mypurecloud.com",
  "headers": {"User-to-User": "{{handoff_id}}"},
  "headers_in_uri": true,
  "uui_encoding": "hex"
}
```

Replace the address with one that routes back to the queue or flow that should
take the caller; confirm its form with Genesys. The `REFER` looks like this:

```
Refer-To: <sip:support@acme.byoc.mypurecloud.com?User-to-User=5A72336D59...%3Bencoding%3Dhex>
```

With **Take Back and Transfer** on, Genesys takes the call back from the trunk
and routes it to that address. Genesys documents that incoming UUI lands in
`Call.UUIData`; it doesn't document this for a take-back, so confirm with
Genesys, or on a test call, that the flow receiving the caller finds the
hand-off id there. To get the summary and intent, call the hand-off lookup with
a **Call Data Action** on a Web Services Data Actions integration:

- Request: `GET https://api.thunderphone.com/v1/calls/handoff?handoff_id=`
  followed by the id from `Call.UUIData`.
- Credentials: your API key, sent as `Authorization: Bearer sk_live_…`.
- Output: map `handoff.summary` and `handoff.intent` to flow variables.

See [Look up a handed-off call](/api-reference/calls#look-up-a-handed-off-call).

## Test it

Call a number that reaches the flow, ask the agent for a person, and check that
Genesys takes the call to the address you set. In that flow, check that
`Call.UUIData` holds the hand-off id as text (if it shows hex digits, check the
trunk's UUI encoding is Hex). Then open the call with `GET /v1/calls/{call_id}`:
`external_call_id` should be the conversation id.

## Limits

- The **Get SIP Headers** action reads only the initial `INVITE`, so it can't
  read anything from the agent's `REFER`. The hand-off reaches Genesys only
  through UUI.
- Genesys drops all UUI when a call carries more than one UUI header.
- The transfer address is kept to 254 characters, so a long UUI is cut to fit.
  A hand-off id always fits.