Công cụ Transfer to number trong ElevenAgents

Chuyển cuộc gọi đến các số điện thoại bên ngoài hoặc URI SIP dựa trên những điều kiện đã định nghĩa.

Tổng quan

Công cụ hệ thống transfer_to_number cho phép một agent ElevenLabs chuyển cuộc gọi đang diễn ra đến một số điện thoại hoặc SIP URI cụ thể khi đáp ứng các điều kiện nhất định. Tính năng này giúp agent chuyển tiếp các vấn đề phức tạp, yêu cầu đặc thù hoặc các tình huống cần sự can thiệp của con người sang cho nhân viên trực tổng đài.

Tính năng này hỗ trợ chuyển cuộc gọi thông qua Twilio và các số SIP trunk. Khi được kích hoạt, agent có thể phát một thông báo cho người gọi trong lúc chờ đợi, đồng thời gửi một thông báo riêng biệt để tóm tắt tình huống cho nhân viên tiếp nhận cuộc gọi.

Các hình thức chuyển cuộc gọi

Hệ thống hỗ trợ 3 hình thức chuyển cuộc gọi:

• Conference Transfer: Đây là cơ chế mặc định; hệ thống sẽ gọi đến đích đến, thêm người tham gia vào một phòng hội nghị, sau đó loại bỏ AI agent để chỉ còn lại người gọi và người tiếp nhận cuộc gọi. Khi sử dụng tích hợp Twilio nguyên bản, hình thức này hỗ trợ thông báo chuyển tiếp (agent_message) dành cho nhân viên tiếp nhận cuộc gọi.
• Blind Transfer: Chuyển thẳng cuộc gọi đến đích mà không gửi thông báo cho nhân viên tiếp nhận. Hình thức này giữ nguyên ID của người gọi ban đầu. Chỉ khả dụng khi số điện thoại của agent được nhập thông qua tích hợp Twilio nguyên bản.
• SIP REFER Transfer: Sử dụng giao thức SIP REFER để chuyển trực tiếp cuộc gọi đến đích. Hình thức này hoạt động với cả số điện thoại và SIP URI, nhưng chỉ khả dụng khi sử dụng giao thức SIP trong suốt cuộc hội thoại; đồng thời yêu cầu SIP Trunk của bạn phải cho phép chuyển cuộc gọi qua SIP REFER. Không hỗ trợ thông báo chuyển tiếp (agent_message).

Thông báo chuyển tiếp (agent_message) chỉ khả dụng khi số điện thoại của agent được nhập thông qua tích hợp Twilio nguyên bản. Các hình thức chuyển cuộc gọi dựa trên giao thức SIP không hỗ trợ loại thông báo này.

Blind Transfer chỉ khả dụng khi số điện thoại của agent được nhập thông qua tích hợp Twilio nguyên bản và hiện cần được cấu hình thông qua trình chỉnh sửa JSON trong giao diện người dùng. Hãy chọn “Edit as JSON” tại phần cấu hình công cụ chuyển cuộc gọi và thiết lập "transfer_type": "blind" cho quy tắc chuyển cuộc gọi mong muốn.

Mục đích: Chuyển tiếp cuộc hội thoại một cách liền mạch sang nhân viên con người trong trường hợp sự hỗ trợ từ AI là chưa đủ.

Các điều kiện kích hoạt: LLM nên gọi công cụ này khi:

• Các vấn đề phức tạp đòi hỏi sự đánh giá từ con người
• Người dùng yêu cầu sự hỗ trợ từ con người một cách rõ ràng
• AI đạt đến giới hạn năng lực đối với yêu cầu cụ thể đó
• Các quy trình chuyển giao được kích hoạt

Các tham số:

• reason (chuỗi, tùy chọn): Lý do thực hiện chuyển tiếp
• transfer_number (chuỗi, bắt buộc): Số điện thoại cần chuyển tiếp đến (phải khớp với các số đã được cấu hình)
• client_message (chuỗi, bắt buộc): Thông điệp dành cho khách hàng trong lúc chờ chuyển tiếp
• agent_message (chuỗi, bắt buộc): Thông điệp dành cho nhân viên hỗ trợ (con người) tiếp nhận cuộc gọi

Định dạng gọi hàm:

{
  "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.\"}"
  }
}

Triển khai: Thiết lập các số điện thoại chuyển tiếp và những điều kiện đi kèm. Xác định nội dung tin nhắn dành cho khách hàng và nhân viên trực tổng đài. Tính năng này hỗ trợ cả Twilio và SIP trunking.

Các số điện thoại có thể chuyển tiếp đến

Tính năng chuyển tiếp cho nhân viên hỗ trợ chuyển cuộc gọi đến các số điện thoại bên ngoài thông qua SIP trunking hoặc số điện thoại Twilio.

Kích hoạt tính năng chuyển tiếp cho nhân viên

Tính năng này được thiết lập thông qua công cụ hệ thống transfer_to_number.

1. Thêm công cụ chuyển tiếp

Kích hoạt tính năng chuyển tiếp cho nhân viên bằng cách chọn công cụ hệ thống transfer_to_number trong phần cấu hình agent tại tab Agent. Chọn "Transfer to Human" khi thêm công cụ.

2. Cấu hình mô tả công cụ (tùy chọn)

Bạn có thể cung cấp mô tả tùy chỉnh để hướng dẫn mô hình ngôn ngữ lớn (LLM) về thời điểm cần thực hiện chuyển tiếp. Nếu để trống, hệ thống sẽ sử dụng mô tả mặc định bao gồm các quy tắc chuyển tiếp đã được thiết lập.

3. Xác định các quy tắc chuyển tiếp

Thiết lập các quy tắc cụ thể cho việc chuyển tiếp đến những số điện thoại hoặc địa chỉ SIP URI. Với mỗi quy tắc, hãy chỉ định:

• Loại chuyển tiếp (Transfer Type): Chọn một trong các phương thức: Conference (mặc định), Blind (chuyển tiếp trực tiếp), hoặc SIP REFER.
• Loại số (Number Type): Chọn "Phone" hoặc "SIP URI".
• Số điện thoại/SIP URI: Điểm đến mục tiêu theo định dạng phù hợp:
  
  • Số điện thoại: Định dạng E.164 (ví dụ: +12125551234)
  • SIP URI: Định dạng SIP (ví dụ: sip:1234567890@example.com)
• Điều kiện (Condition): Mô tả bằng ngôn ngữ tự nhiên về các tình huống cần thực hiện chuyển tiếp (ví dụ: "Người dùng yêu cầu trực tiếp được nói chuyện với nhân viên", "Người dùng cần cập nhật thông tin tài khoản nhạy cảm").

LLM sẽ sử dụng các điều kiện này, cùng với mô tả công cụ, để quyết định thời điểm thực hiện chuyển tiếp và điểm đến phù hợp.

Phương thức chuyển tiếp SIP REFER yêu cầu sử dụng giao thức SIP trong suốt cuộc hội thoại; đồng thời, SIP Trunk của bạn phải cho phép thực hiện chuyển tiếp thông qua SIP REFER. Chỉ phương thức SIP REFER mới hỗ trợ chuyển tiếp đến một địa chỉ SIP URI. Chuyển cuộc gọi kiểu "blind transfer" chỉ khả dụng khi số điện thoại của tổng đài viên được nhập thông qua tích hợp Twilio gốc và phải được cấu hình bằng trình chỉnh sửa JSON. Thông tin người gọi ban đầu (caller ID) vẫn được giữ nguyên, nhưng sẽ không có thông báo nào được gửi đến tổng đài viên trước khi cuộc gọi được chuyển tới.

Đảm bảo các đích đến được định dạng chính xác:

• Số điện thoại: Theo định dạng E.164 và phải gắn với một tài khoản đã được cấu hình đúng cách.
• SIP URI: Theo định dạng SIP hợp lệ (ví dụ: sip:user@domain hoặc sips:user@domain).

4. Cấu hình các header SIP REFER tùy chỉnh (tùy chọn)

Khi sử dụng phương thức chuyển cuộc gọi SIP REFER, bạn có thể thêm các header SIP tùy chỉnh để truyền thông tin bổ sung tới hệ thống tiếp nhận.

Đối với mỗi header tùy chỉnh, hãy chỉ định:

• Header Name: Tên của header SIP (ví dụ: X-Customer-ID, X-Priority).
• Header Value: Giá trị của header, có thể là văn bản tĩnh hoặc bao gồm các biến động.

Các header SIP REFER tùy chỉnh chỉ được bao gồm trong các cuộc gọi chuyển theo phương thức SIP REFER. Phương thức chuyển cuộc gọi dạng hội nghị không hỗ trợ các header tùy chỉnh.

5. Cấu hình thông tin người dùng (User-to-User Information - UUI) (tùy chọn)

Các cuộc gọi chuyển theo phương thức SIP REFER có thể mang theo thông tin người dùng (UUI) - một đoạn dữ liệu nhỏ được gửi tới nền tảng tiếp nhận (ví dụ: Talkdesk hoặc Genesys Cloud) thông qua tham số User-to-User trong header Refer-To. UUI chỉ được gửi trong các cuộc gọi SIP REFER có đích đến là SIP URI; các đích đến là số điện thoại (định dạng tel:) sẽ không mang theo thông tin này.

Cấu hình UUI cho từng quy tắc chuyển cuộc gọi thông qua đối tượng uui:

• data: Dữ liệu cần gửi (dưới dạng plain text). ElevenLabs sẽ mã hóa dữ liệu này sang định dạng hex và thêm hậu tố ;encoding=hex. Nội dung có thể là văn bản tĩnh hoặc bao gồm các biến động. Giới hạn tối đa là 256 byte (UTF-8), được kiểm tra sau khi các biến động đã được thay thế bằng giá trị thực tế - tương đương với 256 ký tự đối với bảng mã ASCII, hoặc ít hơn nếu sử dụng các ký tự chiếm nhiều byte.
• protocol_discriminator: Một octet (byte) ở định dạng thập lục phân (hex), ví dụ: 04. Hãy thêm tham số này đối với các nền tảng tự động loại bỏ octet đầu tiên của dữ liệu truyền tải (payload); ngược lại, hãy bỏ qua nếu nền tảng đó giữ nguyên toàn bộ dữ liệu truyền tải.
• protocol_discriminator_mode: Chế độ "prefix" (mặc định) sẽ đặt octet này vào phía trước dữ liệu, tạo thành định dạng: 04<hex>;encoding=hex. Chế độ pd_parameter sẽ thêm nó dưới dạng một tham số riêng biệt, tạo thành định dạng: <hex>;pd=04;encoding=hex.

Talkdesk giữ nguyên giá trị dữ liệu truyền tải, vì vậy bạn không cần thêm protocol_discriminator. Genesys Cloud sẽ loại bỏ octet đầu tiên của dữ liệu truyền tải trừ khi có sự hiện diện của một discriminator, do đó bạn cần thêm protocol_discriminator. 

Giới hạn 256 byte được áp dụng sau khi các biến động đã được thay thế bằng giá trị thực tế. Chỉ nên truyền các định danh hoặc mã ngắn (ví dụ: ID tài khoản), không nên truyền văn bản tự do (như bản tóm tắt cuộc gọi đầy đủ) vì sẽ vượt quá giới hạn cho phép và dữ liệu đó sẽ bị loại bỏ trong quá trình chuyển tiếp.

Để nhận dữ liệu UUI trong các cuộc gọi SIP đến, bạn không cần thực hiện cấu hình bổ sung. Khi một yêu cầu INVITE gửi đến có chứa header User-to-User, giá trị của header này sẽ được hiển thị cho nhân viên xử lý thông qua các biến động {{sip_uui_raw}} và {{sip_uui_data}}. 

6. Cấu hình các chữ số sau khi quay số (tùy chọn)

Các chữ số sau khi quay số là các tín hiệu DTMF được truyền đi sau khi điện thoại kết nối với đích chuyển tiếp. Điều này hữu ích để nhập số máy nhánh hoặc điều hướng menu IVR (Interactive Voice Response) tự động.

Đối với mỗi quy tắc chuyển tiếp, bạn có thể chỉ định một chuỗi post_dial_digits chứa:

• Các chữ số (0-9): Tín hiệu DTMF tiêu chuẩn
• w: Độ trễ 0,5 giây
• W: Độ trễ 1 giây
• * và #: Tín hiệu DTMF đặc biệt

Ví dụ: ww1234 đợi 1 giây sau khi cuộc gọi kết nối, sau đó quay số máy nhánh 1234.

Các chữ số sau khi quay số chỉ khả dụng khi số điện thoại của agent (số bắt đầu chuyển tiếp) được nhập thông qua tích hợp Twilio gốc. Số đích có thể là bất kỳ số điện thoại nào.

Các chữ số sau khi quay số chỉ được hỗ trợ cho các loại chuyển tiếp hội nghị và chuyển tiếp ẩn danh. Chuyển tiếp SIP REFER không hỗ trợ các chữ số sau khi quay số.

Triển khai API

Bạn có thể cấu hình công cụ hệ thống transfer_to_number khi tạo hoặc cập nhật agent thông qua API. Công cụ này cho phép chỉ định thông báo cho cả client (người dùng được chuyển tiếp) và agent (người điều hành nhận cuộc gọi).

Python

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).

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient({
  apiKey: "YOUR_API_KEY",
});

await elevenlabs.conversationalAi.agents.create({
  conversationConfig: {
    agent: {
      firstMessage: "Hi, how can I help you today?",
      prompt: {
        prompt: "You are a helpful assistant.",
        builtInTools: {
          transferToNumber: {
            type: "system",
            name: "transfer_to_number",
            description: "Transfer the user to a human operator based on their request.", // Optional custom description
            params: {
              systemToolType: "transfer_to_number",
              transfers: [
                {
                  transferDestination: { type: "phone", phoneNumber: "+15551234567" },
                  condition: "When the user asks for billing support.",
                  transferType: "conference",
                  // Wait 1s, then dial extension 1234 (native Twilio only)
                  postDialDigits: { type: "static", value: "ww1234" },
                },
                {
                  transferDestination: { type: "phone", phoneNumber: "+15559876543" },
                  condition: "When the user asks to speak to a human.",
                  // Native Twilio only, preserves caller ID, no warm transfer message
                  transferType: "blind",
                },
                {
                  transferDestination: { type: "sip_uri", sipUri: "sip:support@example.com" },
                  condition: "When the user requests to file a formal complaint.",
                  transferType: "sip_refer",
                  customSipHeaders: [
                    { 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}}",
                    protocolDiscriminator: "04", // Genesys Cloud; omit for Talkdesk
                    protocolDiscriminatorMode: "prefix", // or "pd_parameter"
                  },
                },
              ],
            },
          },
        },
      },
    },
  },
});

// 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).