電話番号への転送 | ElevenLabs Documentation

概要

transfer_to_numberシステムツールを使うと、特定の条件が満たされたときに、ElevenLabsエージェントが進行中の通話を指定した電話番号またはSIP URIへ転送できます。これにより、複雑な問題、特定のリクエスト、または人による対応が必要な状況を、ライブオペレーターに引き継げます。

この機能は、TwilioおよびSIPトランク番号経由の転送に対応しています。トリガーされると、エージェントはユーザーが待機している間のメッセージと、通話を受けるオペレーター向けに状況を要約した別のメッセージを提供できます。

transfer_to_numberシステムツールは電話通話でのみ利用でき、チャットウィジェットでは利用できません。

転送タイプ

システムは3種類の転送をサポートしています。

会議転送：デフォルトの動作です。転送先に発信して参加者を会議室に追加し、その後AIエージェントを退出させるため、発信者と転送先の参加者だけが残ります。ネイティブTwilioインテグレーションを使用する場合、オペレーターに読み上げるウォーム転送メッセージ（agent_message）に対応します。
ブラインド転送：オペレーターへのウォーム転送メッセージなしで、通話を直接転送先へ転送します。元の発信者IDは維持されます。エージェントの電話番号がネイティブTwilioインテグレーション経由でインポートされている場合にのみ利用できます。
SIP REFER転送：SIP REFERプロトコルを使用して、通話を直接転送先へ転送します。電話番号とSIP URIの両方で動作しますが、会話中にSIPプロトコルを使用している場合にのみ利用でき、SIPトランクでSIP REFER経由の転送を許可する必要があります。ウォーム転送メッセージには対応していません。

ウォーム転送メッセージ（agent_message）は、エージェントの電話番号がネイティブTwilio インテグレーション経由でインポートされている場合にのみ利用できます。SIPベースの転送ではウォーム転送メッセージはサポートされません。

ブラインド転送は、エージェントの電話番号がネイティブ Twilioインテグレーション経由でインポートされている場合にのみ利用でき、現時点ではUIのJSONエディターで設定する必要があります。転送ツール設定で「JSONとして編集」を選択し、目的の転送ルールに "transfer_type": "blind"を設定してください。

目的：AIの支援だけでは不十分な場合に、会話を人間のオペレーターへスムーズに引き継ぎます。

トリガー条件：LLMは以下の場合にこのツールを呼び出します。

人間による判断が必要な複雑な問題
ユーザーが人間による支援を明示的に求めた
特定のリクエストに対し、AIの能力の限界に達した
エスカレーションプロトコルが発動された

パラメータ：

reason（string、任意）：転送の理由
transfer_number（string、必須）：転送先の電話番号（設定済みの番号と一致する必要があります）
client_message（string、必須）：転送を待つ間に顧客へ読み上げるメッセージ
agent_message（string、必須）：通話を受ける人間のオペレーターへのメッセージ

関数呼び出し形式：

{
  "type": "function",
  "function": {
    "name": "transfer_to_number",
    "arguments": "{\"reason\": \"Complex billing issue\", \"transfer_number\": \"+15551234567\", \"client_message\": \"I'm transferring you to a billing specialist who can help with your account.\", \"agent_message\": \"Customer has a complex billing dispute about order #12345 from last month.\"}"
  }
}

実装：転送先の電話番号と条件を設定します。顧客と通話を受ける人間のオペレーターの両方に向けたメッセージを定義します。TwilioとSIPトランキングの両方で機能します。

転送可能な番号

有人転送では、SIPトランキングとTwilio電話番号の両方を使用して、外部の電話番号に転送できます。

有人転送を有効にする

有人転送はtransfer_to_numberシステムツールで設定します。

転送ツールを追加

Agentタブ内のエージェント設定でtransfer_to_numberシステムツールを選択し、有人転送を有効にします。ツールを追加する際に「人に転送」を選択してください。

ツールの説明を設定（任意）

転送をトリガーするタイミングをLLMに指示するカスタム説明を設定できます。空欄の場合は、定義済みの転送ルールを含むデフォルトの説明が使用されます。

転送ルールを定義

電話番号またはSIP URIに転送するための具体的なルールを設定します。各ルールでは以下を指定します。

転送タイプ：会議（デフォルト）、ブラインド、またはSIP REFERの転送方式から選択
番号タイプ：通常の電話番号には「電話」、SIPアドレスには「SIP URI」を選択
電話番号／SIP URI：適切な形式で指定する転送先：
- 電話番号：E.164形式（例：+12125551234）
- SIP URI：SIP形式（例：sip:1234567890@example.com）
条件：転送を行う状況についての自然言語による説明（例：「ユーザーが明示的に人との会話を希望する場合」「ユーザーが機密性の高いアカウント情報を更新する必要がある場合」）。

LLMは、これらの条件とツールの説明に基づいて、転送のタイミングと転送先を決定します。

SIP REFER転送では、会話中にSIPプロトコルを使用する必要があり、SIPトランクでSIP REFER経由の転送を許可する必要があります。SIP URIへの転送をサポートしているのはSIP REFERのみです。

ブラインド転送は、エージェントの電話番号がネイティブTwilioインテグレーション経由でインポートされている場合にのみ利用でき、JSONエディターで設定する必要があります。元の発信者IDは維持されますが、オペレーターにはウォーム転送メッセージは送信されません。

転送先が正しい形式であることを確認してください。

電話番号：E.164形式で、適切に設定されたアカウントに関連付けられていること
SIP URI：有効なSIP形式（sip:user@domainまたはsips:user@domain）

カスタムSIP REFERヘッダーを設定（任意）

SIP REFER転送を使用する場合、カスタムSIPヘッダーを含めて、追加情報を受信システムに渡すことができます。

カスタムヘッダーごとに、以下を指定します。

ヘッダー名：SIPヘッダー名（例：X-Customer-ID、X-Priority）
ヘッダー値：静的テキスト、または動的変数を含むヘッダー値

カスタムSIP REFERヘッダーは、SIP REFER転送でのみ含まれます。会議転送ではカスタムヘッダーはサポートされません。

システムヘッダーX-Conversation-IDおよびX-Caller-IDはElevenLabsによって自動的に含まれ、同名のカスタムヘッダーは大文字と小文字を区別せず上書きされます。

ユーザー間情報（UUI）を設定（任意）

SIP REFER転送では、Refer-ToヘッダーのUser-to-Userパラメーターで、受信プラットフォーム（たとえばTalkdeskやGenesys Cloud）に配信される小さなペイロードであるユーザー間情報（UUI）を送信できます。UUIは、SIP URIへのSIP REFER転送でのみ送信されます。電話番号（tel:）の転送先では送信されません。

転送ルールごとにuuiオブジェクトでUUIを設定します。

data：プレーンテキストとして送信するペイロードです。ElevenLabsが16進数エンコードし、;encoding=hexを追加します。静的テキストまたは動的変数を含めることができます。最大256バイト（UTF-8）で、動的変数の置換後に適用されます。プレーンASCIIでは256文字ですが、マルチバイト文字ではそれより少なくなります。
protocol_discriminator：単一の16進数オクテットです（例：04）。ペイロードの先頭オクテットを削除するプラットフォームでは含め、ペイロードをそのまま渡すプラットフォームでは省略してください。
protocol_discriminator_mode：prefix（デフォルト）はオクテットを先頭に追加し、04<hex>;encoding=hexを生成します。pd_parameterは別のパラメーターとして追加し、<hex>;pd=04;encoding=hexを生成します。

Talkdeskは値を変更せずに渡すため、プロトコル識別子は省略してください。Genesys Cloudは識別子が存在しない場合にペイロードの先頭オクテットを削除するため、protocol_discriminatorを含めてください。Genesys UUIデータ形式を参照してください。

256バイトの制限は動的変数の置換後に適用されます。完全な通話要約のような制限を超えて転送から除外される自由形式のテキストではなく、アカウントIDなどの識別子や短いコードを渡してください。

着信SIP通話でUUIを受信するための設定は不要です。着信INVITEにUser-to-Userヘッダーが含まれる場合、その値はエージェントで{{sip_uui_raw}}および{{sip_uui_data}}動的変数として公開されます。SIPリファレンスを参照してください。

後ダイヤル数字を設定（任意）

後ダイヤル数字は、電話が転送先に接続した後に送信されるDTMFトーンです。これにより、内線番号の入力やIVR（自動音声応答）メニューの操作を自動化できます。

各転送ルールでは、以下を含むpost_dial_digits文字列を指定できます。

数字（0-9）：標準DTMFトーン
w：0.5秒の遅延
W：1秒の遅延
*と#：特殊DTMFトーン

たとえば、ww1234は通話の接続後に1秒待機してから、内線1234をダイヤルします。

後ダイヤル数字は、エージェントの電話番号（転送を開始する番号）がネイティブTwilioインテグレーション経由でインポートされている場合にのみ利用できます。転送先番号は任意の電話番号にできます。

後ダイヤル数字は、会議およびブラインド転送タイプでのみサポートされます。SIP REFER転送では後ダイヤル数字はサポートされません。

API実装

API経由でエージェントを作成または更新する際に、transfer_to_numberシステムツールを設定できます（エージェントを作成、エージェントを更新）。このツールでは、クライアント（転送されるユーザー）とエージェント（通話を受けるオペレーター）の両方に対するメッセージを指定できます。

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
# Define transfer rules
transfer_rules = [
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15551234567"},
        "condition": "When the user asks for billing support.",
        "transfer_type": "conference",
        # Wait 1s, then dial extension 1234 (native Twilio only)
        "post_dial_digits": {"type": "static", "value": "ww1234"},
    },
    {
        "transfer_destination": {"type": "phone", "phone_number": "+15559876543"},
        "condition": "When the user asks to speak to a human.",
        # Native Twilio integration only, preserves caller ID, no warm transfer message
        "transfer_type": "blind",
    },
    {
        "transfer_destination": {"type": "sip_uri", "sip_uri": "sip:support@example.com"},
        "condition": "When the user requests to file a formal complaint.",
        "transfer_type": "sip_refer",
        "custom_sip_headers": [
            {"type": "static", "key": "X-Department", "value": "complaints"},
            {"type": "static", "key": "X-Priority", "value": "high"},
            # Use "dynamic" to read the value from a dynamic variable
            {"type": "dynamic", "key": "X-Customer-ID", "value": "{{customer_id}}"},
        ],
        "uui": {
            "data": "account_id={{customer_id}}",
            "protocol_discriminator": "04",           # Genesys Cloud; omit for Talkdesk
            "protocol_discriminator_mode": "prefix",  # or "pd_parameter"
        },
    },
]
response = elevenlabs.conversational_ai.agents.create(
    conversation_config=ConversationalConfig(
        agent=AgentConfig(
            first_message="Hi, how can I help you today?",
            prompt={
                "prompt": "You are a helpful assistant.",
                "built_in_tools": {
                    "transfer_to_number": {
                        "type": "system",
                        "name": "transfer_to_number",
                        # Optional custom description
                        "description": "Transfer the user to a human operator based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_number",
                            "transfers": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)
# Note: When the LLM decides to call this tool, it needs to provide:
# - transfer_number: The phone number to transfer to (must match one defined in rules).
# - client_message: Message read to the user during transfer.
# - agent_message: Message read to the human operator receiving the call (native Twilio integration only, not used for blind transfers or SIP).