---
title: "Hubungkan dari Twilio"
description: "Kirim panggilan Twilio ke agen ThunderPhone melalui SIP dengan CallSid, lalu kembalikan melalui referUrl Anda dengan hand-off di alamat transfer."
---

TwiML Anda memanggil alamat SIP agen dengan `CallSid` panggilan dalam sebuah header.
Saat penelepon membutuhkan seseorang, agen mengirimkan `REFER` SIP, Twilio meneruskan
alamat transfer beserta serah-terima di dalamnya ke handler `referUrl` Anda, dan
TwiML yang dikembalikan handler Anda menentukan ke mana penelepon dialihkan, seperti antrean Flex.

## Sebelum memulai

- Agen ThunderPhone dan [kunci API](/id/guides/api-keys) organisasi.
- Twilio Programmable Voice, serta tempat untuk menyajikan TwiML dan handler
  `referUrl`: server Anda sendiri, atau TwiML Bin dan Twilio Function. Flex
  bersifat opsional.

## 1. Buat endpoint SIP

`<Sip>` Twilio menggunakan nama pengguna dan kata sandi, jadi gunakan endpoint standar:

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

Simpan `password` dari respons segera; nilai ini hanya ditampilkan sekali. Untuk
menerima panggilan hanya dari Twilio juga, lihat
[Batasi IP sumber](/id/guides/sip-addresses).

## 2. Kirim panggilan dengan konteks

Kembalikan TwiML ini untuk panggilan yang ingin Anda serahkan kepada agen:

```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` penting: Twilio menggunakan UDP kecuali diberi tahu sebaliknya.
- `X-Call-ID` membawa `CallSid`. Twilio tidak mendokumentasikan header call-id
  miliknya sendiri, jadi tambahkan header ini: ThunderPhone menyimpannya sebagai
  `external_call_id` panggilan. `{{CallSid}}` berfungsi dalam TwiML Bin; dari
  server Anda sendiri, tuliskan `CallSid` dari permintaan masuk.
- Tambahkan konteks lainnya dengan cara yang sama, seperti `&amp;X-Account-Id=12345`. Di dalam
  TwiML, tuliskan `&` sebagai `&amp;`, karena `&` tanpa escape bukan XML yang valid. Masing-masing mencapai
  Prompt sebagai variabel, di sini `{{sip_x_account_id}}`. Twilio mengizinkan header
  `x-` dan `User-to-User`, yang dienkode persen, dengan seluruh URI di bawah 255 karakter
  dan header di bawah 1.024.
- `referUrl` memungkinkan Twilio menerima `REFER` dari agen; tanpa itu transfer
  gagal dengan [error 13802](https://www.twilio.com/docs/api/errors/13802).
  `answerOnBridge="true"` menjaga penelepon tetap terhubung hingga tujuan baru
  menjawab, sehingga transfer yang gagal dapat menggunakan fallback.

Widget **Hubungkan Panggilan Ke** Studio tidak mendokumentasikan header khusus atau
`referUrl`, jadi dari Studio serahkan panggilan ke TwiML ini, misalnya dengan widget
**Pengalihan TwiML**.

## 3. Dapatkan panggilan kembali

Agen mentransfer dengan `REFER` yang alamat transfernya membawa
id dan intent serah-terima. Tambahkan nomor transfer ini (lihat
[Tambahkan nomor transfer](/id/guides/contact-centers/overview)
dan [Header di dalam alamat transfer](/id/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 mengirimkan seluruh alamat ke `referUrl` Anda sebagai `ReferTransferTarget`, misalnya
`<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>`.
Handler Anda membaca header dari alamat tersebut dan mengembalikan TwiML untuk tujuan
penelepon selanjutnya. Bagian pengguna alamat tersebut (`support`) dapat Anda tentukan,
sehingga Anda dapat menambahkan satu nomor transfer per tujuan dan merutekannya berdasarkan nomor tersebut.

Twilio Function ini memasukkan penelepon ke antrean Flex dengan serah-terima sebagai
atribut tugas dan mencari ringkasan berdasarkan id serah-terima. Pencarian dijalankan di
Function karena widget HTTP Request Studio tidak dapat mengirim header `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);
};
```

Simpan API key di variabel lingkungan Function. Lihat
[Cari panggilan yang diserahterimakan](/api-reference/calls#look-up-a-handed-off-call)
untuk field lainnya.

## Uji

Hubungi nomor Twilio yang mengembalikan TwiML di atas, minta agen menyambungkan Anda ke seseorang,
dan pastikan handler `referUrl` Anda menerima `ReferTransferTarget` dengan kedua
header serta penelepon masuk ke antrean. Kemudian buka panggilan dengan
`GET /v1/calls/{call_id}`: `external_call_id` harus berupa `CallSid`.

## Batasan

- Twilio membatasi `Refer-To` hingga 256 karakter. ThunderPhone mempertahankan alamat hingga
  254 karakter dan mengabaikan header yang tidak muat, jadi gunakan nama dan nilai header
  yang singkat.
- Twilio tidak mendokumentasikan pembacaan header pada `BYE`, sehingga transfer balik tidak dapat membawa
  serah-terima kembali ke Twilio. Gunakan `REFER` seperti di atas.
- Twilio tidak menerima `REFER` pada panggilan yang terhubung melalui `<Conference>` atau
  `<Queue>`, jadi hubungi agen dengan `<Dial><Sip>` seperti di atas.
