Open in
Twilioから接続
CallSid を使用して Twilio の通話を SIP 経由で ThunderPhone エージェントに送信し、転送先アドレスのハンドオフを含む referUrl を介して通話を戻します。
TwiML は、通話の CallSid をヘッダーに含めて、エージェントの SIP アドレスをダイヤルします。
発信者が担当者を必要とする場合、エージェントは SIP REFER を送信し、Twilio は引き継ぎ先を含む転送アドレスを referUrl ハンドラーに渡します。ハンドラーが返す TwiML によって、Flex キューなど発信者の転送先が決まります。
開始前の準備
- ThunderPhone エージェントと組織の API キー。
- Twilio Programmable Voice、および TwiML と
referUrlハンドラーを提供する環境。独自のサーバー、または TwiML Bin と Twilio Function を使用できます。Flex は任意です。
1. SIP エンドポイントを作成する
Twilio の <Sip> にはユーザー名とパスワードが必要なため、標準エンドポイントを使用します。
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 を制限するを参照してください。
2. コンテキストを付けて通話を送信する
エージェントに引き渡す通話に対して、次の TwiML を返します。
<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を記述してください。&X-Account-Id=12345のように、同じ方法で追加のコンテキストを渡せます。TwiML 内では、&単体は無効な XML のため、&を&と記述します。いずれもプロンプトでは変数として利用でき、この例では{{sip_x_account_id}}になります。Twilio では、URI 全体が 255 文字未満、ヘッダーが 1,024 文字未満であれば、x-ヘッダーとパーセントエンコードされたUser-to-Userを使用できます。referUrlにより、Twilio はエージェントのREFERを受け入れられます。指定しない場合、転送は エラー 13802 で失敗します。answerOnBridge="true"は新しい転送先が応答するまで発信者を接続したままにするため、転送に失敗した場合にフォールバックできます。
Studio の 通話の接続先 ウィジェットでは、カスタムヘッダーや
referUrl は文書化されていません。そのため Studio からは、たとえば
TwiML リダイレクト ウィジェットを使用して通話をこの TwiML に引き渡してください。
3. 通話を戻す
エージェントは、転送先アドレスにハンドオフ ID とインテントを含めた REFER で転送します。この転送番号を追加します(
転送番号を追加
および転送先アドレス内のヘッダーを参照):
{
"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 で実行します。
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 の環境変数に保存します。その他のフィールドについては、 ハンドオフされた通話を検索 を参照してください。
テストする
上記の 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>でエージェントに発信してください。