---
title: "Yhdistä Twiliosta"
description: "Ohjaa Twilio-puhelut ThunderPhone-agentille SIP:n kautta CallSid-tunnuksella ja palauta ne referUrl-osoitteesi kautta siirto-osoitteessa olevan siirron avulla."
---

TwiML soittaa agentin SIP-osoitteeseen ja välittää puhelun `CallSid`-tunnuksen otsakkeessa.
Kun soittaja tarvitsee henkilön, agentti lähettää SIP-`REFER`-pyynnön, Twilio välittää
siirto-osoitteen luovutustietoineen `referUrl`-käsittelijällesi, ja käsittelijäsi palauttama
TwiML määrittää, minne soittaja ohjataan, esimerkiksi Flex-jonoon.

## Ennen kuin aloitat

- ThunderPhone-agentti ja organisaation [API-avain](/fi/guides/api-keys).
- Twilio Programmable Voice sekä paikka, jossa voit palvella TwiML:ää ja
  `referUrl`-käsittelijää: oma palvelimesi tai TwiML Bin ja Twilio Function.
  Flex on valinnainen.

## 1. Luo SIP-päätepiste

Twilion `<Sip>` tarvitsee käyttäjänimen ja salasanan, joten käytä tavallista päätepistettä:

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

Tallenna vastauksen `password` heti; se näytetään vain kerran. Jos haluat
hyväksyä puheluita myös vain Twiliosta, katso
[Rajoita lähde-IP-osoitteita](/fi/guides/sip-addresses).

## 2. Lähetä puhelut kontekstin kanssa

Palauta tämä TwiML puhelulle, jonka haluat siirtää agentille:

```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` on tärkeä: Twilio käyttää UDP:tä, ellei toisin määritetä.
- `X-Call-ID` sisältää `CallSid`-tunnuksen. Twilio ei dokumentoi omaa
  call-id-otsaketta, joten lisää tämä: ThunderPhone tallentaa sen puhelun
  `external_call_id`-tunnukseksi. `{{CallSid}}` toimii TwiML Binissä; omalta
  palvelimeltasi kirjoita saapuvan pyynnön `CallSid`.
- Lisää muuta kontekstia samalla tavalla, esimerkiksi `&amp;X-Account-Id=12345`.
  TwiML:n sisällä kirjoita `&` muodossa `&amp;`, koska paljas `&` ei ole kelvollista
  XML:ää. Kukin välittyy kehotteeseen muuttujana, tässä `{{sip_x_account_id}}`.
  Twilio sallii `x-`-otsakkeet ja prosenttikoodatun `User-to-User`-otsakkeen,
  kun koko URI on alle 255 merkkiä ja otsakkeet alle 1 024 merkkiä.
- `referUrl` antaa Twilion hyväksyä agentin `REFER`-pyynnön; ilman sitä siirto
  epäonnistuu [virheellä 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` pitää soittajan yhdistettynä, kunnes uusi kohde
  vastaa, joten epäonnistunut siirto voi palata varavaihtoehtoon.

Studion **Yhdistä puhelu kohteeseen** -widget ei dokumentoi mukautettuja otsakkeita
tai `referUrl`-osoitetta, joten siirrä puhelu Studiosta tähän TwiML:ään esimerkiksi
**TwiML-uudelleenohjaus**-widgetillä.

## 3. Palauta puhelu

Agentti siirtää puhelun `REFER`-pyynnöllä, jossa siirto-osoite sisältää
siirtotunnuksen ja tarkoituksen. Lisää tämä siirtonumero (katso
[Lisää siirtonumero](/fi/guides/contact-centers/overview)
ja [Otsakkeet siirto-osoitteen sisällä](/fi/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 lähettää koko osoitteen `referUrl`-osoitteeseesi arvona `ReferTransferTarget`, esimerkiksi `<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Käsittelijäsi lukee siitä otsakkeet ja palauttaa TwiML:n sille, minne soittaja
siirtyy seuraavaksi. Osoitteen käyttäjäosa (`support`) on vapaasti valittavissasi, joten voit
lisätä yhden siirtonumeron kutakin kohdetta varten ja reitittää sen perusteella.

Tämä Twilio Function lisää soittajan Flexin jonoon siirtotiedot
tehtävän attribuutteina ja hakee yhteenvedon siirtotunnuksella. Haku suoritetaan
Functionissa, koska Studion HTTP Request -widget ei voi lähettää `Authorization`-
otsaketta:

```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);
};
```

Säilytä API-avain Functionin ympäristömuuttujissa. Katso
[Siirretyn puhelun haku](/api-reference/calls#look-up-a-handed-off-call)
muita kenttiä varten.

## Testaa

Soita Twilio-numeroon, joka palauttaa yllä olevan TwiML:n, pyydä agentilta
ihmistä ja tarkista, että `referUrl`-käsittelijäsi vastaanottaa `ReferTransferTarget`-
arvon molemmilla otsakkeilla ja että soittaja päätyy jonoon. Avaa sitten puhelu
komennolla `GET /v1/calls/{call_id}`: `external_call_id`-arvon tulee olla `CallSid`.

## Rajoitukset

- Twilio rajoittaa `Refer-To`-kentän 256 merkkiin. ThunderPhone pitää osoitteen
  254 merkissä ja jättää pois otsakkeen, joka ei mahdu, joten pidä otsakkeiden nimet ja arvot
  lyhyinä.
- Twilio ei dokumentoi otsakkeiden lukemista `BYE`-pyynnössä, joten paluu ei voi välittää
  siirtotietoja takaisin Twiliolle. Käytä yllä kuvattua `REFER`-pyyntöä.
- Twilio ei hyväksy `REFER`-pyyntöä puhelussa, joka on yhdistetty `<Conference>`- tai
  `<Queue>`-elementin kautta, joten soita agentille yllä kuvatulla `<Dial><Sip>`-rakenteella.
