---
title: "Connect from Talkdesk"
description: "Send Talkdesk calls to a ThunderPhone agent with Connect to Autopilot Voice, and escalate them back with the hand-off id in UUI."
---

Your Talkdesk Studio flow sends the caller to the agent with the interaction
id and UUI. When the caller needs a person, the agent escalates with a SIP
`REFER` to Talkdesk, and the hand-off id lands in a Studio variable.

## Before you start

- A ThunderPhone agent and an organization [API key](/guides/api-keys).
- A Talkdesk **Conversation Orchestrator** license, which covers the Studio
  **Connect to Autopilot Voice** component in **External Voice Stream** mode
  ([Talkdesk's article](https://support.talkdesk.com/hc/en-us/articles/48921776047259)).
  Talkdesk bills it per minute while the agent holds the call.

## 1. Create the SIP endpoint

Talkdesk documents only an IP allowlist, so create an endpoint that accepts
calls by source address:

```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": "Talkdesk",
    "auth": "ip_allowlist",
    "allowed_source_cidrs": ["TALKDESK_SIGNALLING_RANGE_1", "TALKDESK_SIGNALLING_RANGE_2"],
    "srtp": "optional"
  }'
```

Talkdesk's article says it sends audio over SRTP, and `"srtp": "optional"`
answers SRTP when Talkdesk offers it. The article doesn't say whether Talkdesk
requires SRTP; if Talkdesk tells you it does, set `srtp` to `required`, which
refuses calls without it.

Get Talkdesk's SIP signalling ranges from Talkdesk. Each must be a public IPv4
range of `/16` or narrower (IPv6 `/48` or narrower). See
[Platforms that authenticate by source IP](/guides/sip-addresses#platforms-that-authenticate-by-source-ip).
Talkdesk sends SIP from Twilio's network, whose addresses every Twilio customer
shares, so the endpoint's address is what keeps other callers out: don't
publish it.
Keep the response's `sip_uri`, for example
`sip:agent-12-jhxmginwjx@sip.thunderphone.com`.

## 2. Send calls with context

In your Studio flow, add **Connect to Autopilot Voice** in **External Voice
Stream** mode and set its target to the endpoint's `sip_uri` with `;transport=tls` added, for
example `sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls`. The
endpoint refuses calls over UDP, which Twilio's SIP uses unless told otherwise.

Talkdesk sends:

- `X-Talkdesk-Interaction-Id`, stored as the call's `external_call_id`;
- `User-to-User`, hex-encoded, such as `business_hours=open`. It reaches the
  prompt decoded, as `{{sip_uui}}`.

Version 2.1 of the component can also send **Defined headers**. Talkdesk's
preferences page describes them as JSON sent over a WebSocket, so confirm with
Talkdesk whether they arrive as SIP headers before you rely on them.

## 3. Get the call back

The agent escalates with a `REFER` to Talkdesk's escalation address, with the
hand-off id as hex UUI inside that address, the only place Talkdesk reads it.
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": "Talkdesk escalation",
  "number": "sip:escalation@talkdesk.com",
  "headers": {"User-to-User": "autopilot_result={{handoff_id}}"},
  "headers_in_uri": true,
  "uui_encoding": "hex"
}
```

The address is the one in Talkdesk's article. Version 2.1 of the component
reads `autopilot_result=`; version 1.7 reads `escalate_to=`, so use that key on
1.7. The `REFER` looks like this:

```
Refer-To: <sip:escalation@talkdesk.com?User-to-User=6175746F70696C6F745F726573756C743D...%3Bencoding%3Dhex>
```

Talkdesk puts the value in a Studio variable. To get the summary and intent,
add an **Execute Action** step on a custom integration built with
Connections:

- Auth type **API key**, header name `Authorization`, value
  `Bearer sk_live_…`.
- Request: `GET https://api.thunderphone.com/v1/calls/handoff?handoff_id=`
  followed by the id from the variable. You can also look the call up by
  `external_call_id` with the interaction id.
- Route on `handoff.intent`, and show `handoff.summary` to the person who takes
  the call.

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

## Test it

Start a call through the Studio flow, ask the agent for a person, and check
that the flow continues past the component with the hand-off id in its
variable. Then open the call with `GET /v1/calls/{call_id}`:
`external_call_id` should be the Talkdesk interaction id.

## Limits

- Talkdesk reads at most 256 bytes of UUI and doesn't allow values separated by
  `|` or `;`, so send a single value. The hand-off id fits.
- Talkdesk's APIs can't read the agent's transcript. Use the hand-off lookup or
  `GET /v1/calls/{call_id}` instead.