---
title: "Twilioから接続"
description: "CallSid を使用して Twilio の通話を SIP 経由で ThunderPhone エージェントに送信し、転送先アドレスのハンドオフを含む referUrl を介して通話を戻します。"
---

TwiML は、通話の `CallSid` をヘッダーに含めて、エージェントの SIP アドレスをダイヤルします。
発信者が担当者を必要とする場合、エージェントは SIP `REFER` を送信し、Twilio は引き継ぎ先を含む転送アドレスを `referUrl` ハンドラーに渡します。ハンドラーが返す TwiML によって、Flex キューなど発信者の転送先が決まります。

## 開始前の準備

- ThunderPhone エージェントと組織の [API キー](/ja/guides/api-keys)。
- Twilio Programmable Voice、および TwiML と `referUrl` ハンドラーを提供する環境。独自のサーバー、または TwiML Bin と Twilio Function を使用できます。Flex は任意です。

## 1. SIP エンドポイントを作成する

Twilio の `<Sip>` にはユーザー名とパスワードが必要なため、標準エンドポイントを使用します。

```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` はすぐに保存してください。表示されるのは一度だけです。
Twilio からの通話のみを受け付ける場合は、
[送信元 IP を制限する](/ja/guides/sip-addresses)を参照してください。

## 2. コンテキストを付けて通話を送信する

エージェントに引き渡す通話に対して、次の 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` は重要です。指定しない場合、Twilio は UDP を使用します。
- `X-Call-ID` は `CallSid` を渡します。Twilio は独自の Call-ID ヘッダーを文書化していないため、このヘッダーを追加してください。ThunderPhone はこれを通話の `external_call_id` として保存します。TwiML Bin では `{{CallSid}}` を使用できます。独自のサーバーでは、受信リクエストの `CallSid` を記述してください。
- `&amp;X-Account-Id=12345` のように、同じ方法で追加のコンテキストを渡せます。TwiML 内では、`&` 単体は無効な XML のため、`&` を `&amp;` と記述します。いずれもプロンプトでは変数として利用でき、この例では `{{sip_x_account_id}}` になります。Twilio では、URI 全体が 255 文字未満、ヘッダーが 1,024 文字未満であれば、`x-` ヘッダーとパーセントエンコードされた `User-to-User` を使用できます。
- `referUrl` により、Twilio はエージェントの `REFER` を受け入れられます。指定しない場合、転送は [エラー 13802](https://www.twilio.com/docs/api/errors/13802) で失敗します。`answerOnBridge="true"` は新しい転送先が応答するまで発信者を接続したままにするため、転送に失敗した場合にフォールバックできます。

Studio の **通話の接続先** ウィジェットでは、カスタムヘッダーや
`referUrl` は文書化されていません。そのため Studio からは、たとえば
**TwiML リダイレクト** ウィジェットを使用して通話をこの TwiML に引き渡してください。

## 3. 通話を戻す

エージェントは、転送先アドレスにハンドオフ ID とインテントを含めた `REFER` で転送します。この転送番号を追加します（
[転送番号を追加](/ja/guides/contact-centers/overview)
および[転送先アドレス内のヘッダー](/ja/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 はアドレス全体を `ReferTransferTarget` として `referUrl` に送信します。たとえば、`<sip:support@acme.sip.twilio.com?X-Handoff-Id=Zr3mY0b1Q9xWw2kPq4s7Tg&X-Handoff-Intent=billing_dispute>` のようになります。
ハンドラーはそこからヘッダーを読み取り、発信者が次に進む先の TwiML を返します。アドレスのユーザー部分（`support`）は任意に選択できるため、宛先ごとに転送番号を追加して、それに基づいてルーティングできます。

この Twilio Function は、ハンドオフをタスク属性として Flex に発信者をエンキューし、ハンドオフ ID で要約を検索します。Studio の HTTP Request ウィジェットは `Authorization`
ヘッダーを送信できないため、検索は Function で実行します。

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

API キーは Function の環境変数に保存します。その他のフィールドについては、
[ハンドオフされた通話を検索](/api-reference/calls#look-up-a-handed-off-call)
を参照してください。

## テストする

上記の TwiML を返す Twilio 番号に電話し、エージェントに担当者への接続を依頼します。次に、`referUrl` ハンドラーが両方のヘッダーを含む `ReferTransferTarget` を受信し、発信者がキューに到達することを確認します。その後、`GET /v1/calls/{call_id}` で通話を開きます。`external_call_id` は `CallSid` である必要があります。

## 制限事項

- Twilio では `Refer-To` は 256 文字に制限されています。ThunderPhone はアドレスを 254 文字以内に収め、収まらないヘッダーは省略するため、ヘッダー名と値は短くしてください。
- Twilio は `BYE` のヘッダーを読み取る方法をドキュメント化していないため、戻り通話でハンドオフを Twilio に返すことはできません。上記のように `REFER` を使用してください。
- Twilio は `<Conference>` または `<Queue>` 経由で接続された通話では `REFER` を受け付けないため、上記のように `<Dial><Sip>` でエージェントに発信してください。
