---
title: "Połącz z Twilio"
description: "Przekierowuj połączenia Twilio do agenta ThunderPhone przez SIP z użyciem CallSid i odbieraj je z powrotem przez swój referUrl, z przekazaniem w adresie transferu."
---

Twój TwiML wybiera adres SIP agenta z identyfikatorem `CallSid` połączenia w nagłówku.
Gdy rozmówca potrzebuje osoby, agent wysyła SIP `REFER`, Twilio przekazuje adres
transferu wraz z zawartym w nim przekazaniem do procedury obsługi `referUrl`, a
TwiML zwrócony przez procedurę określa, dokąd trafi rozmówca, na przykład do kolejki Flex.

## Zanim zaczniesz

- Agent ThunderPhone i [klucz API](/pl/guides/api-keys) organizacji.
- Twilio Programmable Voice oraz miejsce do obsługi TwiML i procedury obsługi
  `referUrl`: własny serwer albo TwiML Bin i Twilio Function. Flex jest
  opcjonalny.

## 1. Utwórz punkt końcowy SIP

Element `<Sip>` w Twilio przyjmuje nazwę użytkownika i hasło, więc użyj standardowego punktu końcowego:

```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"}'
```

Od razu zapisz `password` z odpowiedzi; jest wyświetlane tylko raz. Aby
akceptować połączenia wyłącznie z Twilio, zobacz
[Ogranicz źródłowe adresy IP](/pl/guides/sip-addresses).

## 2. Wysyłaj połączenia z kontekstem

Zwróć ten TwiML dla połączenia, które chcesz przekazać agentowi:

```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` jest wymagany: Twilio używa UDP, jeśli nie zostanie wskazane inaczej.
- `X-Call-ID` zawiera `CallSid`. Twilio nie dokumentuje własnego nagłówka
  call-id, więc dodaj ten: ThunderPhone zapisuje go jako
  `external_call_id` połączenia. `{{CallSid}}` działa w TwiML Bin; na własnym serwerze
  zapisz `CallSid` przychodzącego żądania.
- Dodaj więcej kontekstu w ten sam sposób, na przykład `&amp;X-Account-Id=12345`. W TwiML
  zapisz `&` jako `&amp;`, ponieważ samodzielne `&` jest nieprawidłowym XML. Każdy z nich trafia do
  promptu jako zmienna, tutaj `{{sip_x_account_id}}`. Twilio zezwala na nagłówki `x-`
  i `User-to-User` zakodowane procentowo, przy czym cały URI musi mieć mniej niż 255 znaków,
  a nagłówki mniej niż 1 024.
- `referUrl` umożliwia Twilio zaakceptowanie `REFER` agenta; bez niego transfer
  kończy się [błędem 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` utrzymuje połączenie z rozmówcą do czasu odebrania przez nowy cel,
  dzięki czemu w razie nieudanego transferu można zastosować rozwiązanie awaryjne.

Widget **Połącz rozmowę z** w Studio nie dokumentuje niestandardowych nagłówków ani
`referUrl`, więc ze Studio przekaż połączenie do tego TwiML, na przykład za pomocą
widgetu **Przekierowanie TwiML**.

## 3. Odbierz połączenie z powrotem

Agent przekazuje połączenie za pomocą `REFER`, którego adres przekazania zawiera
identyfikator i intencję przekazania. Dodaj ten numer przekazania (zobacz
[Dodawanie numeru przekazania](/pl/guides/contact-centers/overview)
oraz [Nagłówki w adresie przekazania](/pl/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 wysyła cały adres do `referUrl` jako `ReferTransferTarget`, na
przykład `<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Twój handler odczytuje z niego nagłówki i zwraca TwiML określający, dokąd
następnie trafia rozmówca. Część użytkownika adresu (`support`) wybierasz
samodzielnie, więc możesz dodać jeden numer przekazania dla każdego miejsca
docelowego i kierować połączenia na jego podstawie.

Ta funkcja Twilio umieszcza rozmówcę w kolejce Flex z przekazaniem jako
atrybutami zadania i wyszukuje podsumowanie według identyfikatora przekazania.
Wyszukiwanie działa w funkcji, ponieważ widżet Żądanie HTTP w Studio nie może
wysłać nagłówka `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);
};
```

Przechowuj klucz API w zmiennych środowiskowych funkcji. Zobacz
[Wyszukiwanie przekazanego połączenia](/api-reference/calls#look-up-a-handed-off-call),
aby poznać pozostałe pola.

## Przetestuj

Zadzwoń na numer Twilio, który zwraca powyższy TwiML, poproś agenta o połączenie
z osobą i sprawdź, czy handler `referUrl` otrzymuje `ReferTransferTarget` z
oboma nagłówkami oraz czy rozmówca trafia do kolejki. Następnie otwórz
połączenie za pomocą `GET /v1/calls/{call_id}`: wartość `external_call_id`
powinna być równa `CallSid`.

## Ograniczenia

- Twilio ogranicza `Refer-To` do 256 znaków. ThunderPhone ogranicza adres do
  254 znaków i pomija nagłówek, który się nie mieści, dlatego nazwy i wartości
  nagłówków powinny być krótkie.
- Twilio nie dokumentuje odczytywania nagłówków w `BYE`, więc powrót nie może
  przekazać danych przekazania z powrotem do Twilio. Użyj `REFER`, jak powyżej.
- Twilio nie akceptuje `REFER` w połączeniu zestawionym przez `<Conference>` ani
  `<Queue>`, dlatego wybieraj numer agenta przez `<Dial><Sip>`, jak powyżej.
