---
title: "Připojení z Twilio"
description: "Směrujte hovory z Twilio k agentovi ThunderPhone přes SIP s CallSid a přebírejte je zpět prostřednictvím referUrl s předáním v adrese pro přesměrování."
---

Váš TwiML vytočí SIP adresu agenta s `CallSid` hovoru v hlavičce.
Když volající potřebuje člověka, agent odešle SIP `REFER`, Twilio předá
adresu přesměrování s údaji o předání do vaší obsluhy `referUrl` a TwiML,
který vaše obsluha vrátí, určí, kam bude volající přesměrován, například do fronty Flex.

## Než začnete

- Hlasový agent ThunderPhone a [klíč API](/cs/guides/api-keys) organizace.
- Twilio Programmable Voice a místo pro poskytování TwiML a obsluhy
  `referUrl`: vlastní server nebo TwiML Bin a Twilio Function. Flex je
  volitelný.

## 1. Vytvořte SIP endpoint

Twilio `<Sip>` vyžaduje uživatelské jméno a heslo, proto použijte standardní 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": "Twilio"}'
```

`password` z odpovědi si ihned uložte; zobrazí se pouze jednou. Chcete-li
přijímat hovory také pouze z Twilio, přečtěte si
[Omezení zdrojových IP adres](/cs/guides/sip-addresses).

## 2. Odesílejte hovory s kontextem

Pro hovor, který chcete předat agentovi, vraťte tento TwiML:

```xml
<Response>
  <Dial answerOnBridge="true" referUrl="https://YOUR_SERVER/thunderphone-refer">
    <Sip username="tp409667538f83" password="YOUR_ENDPOINT_PASSWORD">sip:agent-12-jhxmginwjx@sip.thunderphone.com;transport=tls?X-Call-ID={{CallSid}}</Sip>
  </Dial>
</Response>
```

- `;transport=tls` je důležité: Twilio používá UDP, pokud mu neurčíte jinak.
- `X-Call-ID` obsahuje `CallSid`. Twilio nedokumentuje vlastní hlavičku call-id,
  proto přidejte tuto: ThunderPhone ji uloží jako `external_call_id` hovoru.
  `{{CallSid}}` funguje v TwiML Bin; z vlastního serveru zapište `CallSid`
  příchozího požadavku.
- Stejným způsobem přidejte další kontext, například `&amp;X-Account-Id=12345`.
  V TwiML zapisujte `&` jako `&amp;`, protože samotné `&` je neplatné XML. Každá
  hodnota se do promptu dostane jako proměnná, zde `{{sip_x_account_id}}`.
  Twilio povoluje hlavičky `x-` a `User-to-User`, kódované pomocí procent, přičemž
  celá URI musí mít méně než 255 znaků a hlavičky méně než 1 024 znaků.
- `referUrl` umožňuje Twilio přijmout agentův `REFER`; bez něj přesměrování
  selže s [chybou 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` udrží volajícího připojeného, dokud nová destinace
  neodpoví, takže neúspěšné přesměrování může použít záložní postup.

Widget Studio **Připojit hovor k** nedokumentuje vlastní hlavičky ani
`referUrl`, proto ze Studia předejte hovor tomuto TwiML, například pomocí widgetu
**Přesměrování TwiML**.

## 3. Přijměte hovor zpět

Agent přepojí pomocí `REFER`, jehož adresa přepojení obsahuje id a záměr předání.
Přidejte toto číslo pro přepojení (viz
[Přidání čísla pro přepojení](/cs/guides/contact-centers/overview)
a [Hlavičky v adrese přepojení](/cs/guides/call-transfers)):

```json
{
  "name": "Twilio support",
  "number": "sip:support@acme.sip.twilio.com",
  "headers": {"X-Handoff-Id": "{{handoff_id}}", "X-Handoff-Intent": "{{handoff_intent}}"},
  "headers_in_uri": true
}
```

Twilio odešle celou adresu do vašeho `referUrl` jako `ReferTransferTarget`, například
`<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Váš obslužný program z ní načte hlavičky a vrátí TwiML pro další směr volajícího.
Uživatelskou část adresy (`support`) si zvolíte sami, takže můžete přidat jedno
číslo pro přepojení pro každé cílové místo a směrovat podle něj.

Tato funkce Twilio zařadí volajícího do fronty Flex s předáním jako atributy úlohy
a vyhledá souhrn podle id předání. Vyhledávání probíhá ve funkci, protože widget
HTTP Request ve Studio neumí odeslat hlavičku `Authorization`:

```js
exports.handler = async (context, event, callback) => {
  const target = (event.ReferTransferTarget || "").replace(/^<|>$/g, "");
  const params = new URLSearchParams(target.split("?")[1] || "");
  const handoffId = params.get("X-Handoff-Id") || "";
  const attributes = { handoff_id: handoffId, intent: params.get("X-Handoff-Intent") || "" };

  if (handoffId) {
    const response = await fetch(
      "https://api.thunderphone.com/v1/calls/handoff?handoff_id=" + encodeURIComponent(handoffId),
      { headers: { Authorization: "Bearer " + context.THUNDERPHONE_API_KEY } }
    );
    if (response.ok) {
      const call = await response.json();
      attributes.summary = (call.handoff && call.handoff.summary) || "";
    }
  }

  const twiml = new Twilio.twiml.VoiceResponse();
  twiml.enqueue({ workflowSid: context.FLEX_WORKFLOW_SID }).task({}, JSON.stringify(attributes));
  callback(null, twiml);
};
```

Klíč API uchovávejte v proměnných prostředí funkce. Další pole najdete v části
[Vyhledání předaného hovoru](/api-reference/calls#look-up-a-handed-off-call).

## Otestujte to

Zavolejte na číslo Twilio, které vrací výše uvedené TwiML, požádejte agenta o spojení
s člověkem a ověřte, že váš obslužný program `referUrl` obdrží `ReferTransferTarget` s oběma
hlavičkami a že se volající dostane do fronty. Poté otevřete hovor pomocí
`GET /v1/calls/{call_id}`: `external_call_id` by mělo být `CallSid`.

## Omezení

- Twilio omezuje `Refer-To` na 256 znaků. ThunderPhone udržuje adresu na
  254 znacích a vynechá hlavičku, která se nevejde, proto názvy a hodnoty hlaviček
  udržujte krátké.
- Twilio nedokumentuje čtení hlaviček při `BYE`, takže návrat nemůže předání přenést
  zpět do Twilio. Použijte `REFER` jako výše.
- Twilio nepřijímá `REFER` u hovoru připojeného prostřednictvím `<Conference>` nebo
  `<Queue>`, proto hlasového agenta vytočte pomocí `<Dial><Sip>` jako výše.
