Connect from Genesys Cloud

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.
• Genesys Cloud with BYOC Cloud, and an external trunk (type BYOC Carrier or PBX) with these settings turned on (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:

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:

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 and Headers inside the transfer address):

{
  "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.

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.