Przekierowanie na numer

Omówienie

Narzędzie systemowe transfer_to_number pozwala agentowi ElevenLabs przekierować trwające połączenie na wskazany numer telefonu lub identyfikator URI SIP po spełnieniu określonych warunków. Dzięki temu agenci mogą przekazywać złożone sprawy, konkretne prośby lub sytuacje wymagające interwencji człowieka konsultantowi na żywo.

Funkcja obsługuje przekierowania przez numery telefoniczne. Po uruchomieniu agent może wyświetlić użytkownikowi wiadomość podczas oczekiwania oraz osobną wiadomość podsumowującą sytuację dla konsultanta odbierającego połączenie.

Reguły przekierowania

• Reguła przekierowania określa, kiedy agent ma przekierować połączenie i jak każdy dostawca telefonii je realizuje.

• Każda reguła ma jeden warunek i jedną konfigurację na dostawcę.

• Narzędzie można skonfigurować z wieloma regułami przekierowania.

• Podczas połączenia agent widzi tylko reguły dla dostawcy, u którego działa połączenie.

• Warunek: zwykły tekst obsługujący zmienne dynamiczne, opisujący, kiedy użyć tej metody przekierowania, np. „Dzwoniący pyta o rozliczenia”.

• Konfiguracja dostawcy to lista z maksymalnie jednym wpisem na dostawcę. Jeśli reguła nie ma wpisu dla dostawcy, nie istnieje dla połączeń tego dostawcy.

Typy przekierowań

• Konferencja: domyślne działanie, które dzwoni pod wskazany numer i umieszcza dzwoniącego oraz konsultanta w pokoju konferencyjnym.
• SIP REFER: używa protokołu SIP REFER, by przekierować połączenia bezpośrednio do celu. Działa zarówno z numerami telefonów, jak i identyfikatorami URI SIP, ale jest dostępne tylko podczas używania protokołu SIP w rozmowie i wymaga, by twój SIP Trunk zezwalał na przekierowanie przez SIP REFER.

Strategie przekierowania

• Zimne: przekierowuje połączenie bez podsumowania sytuacji dla konsultanta odbierającego połączenie.
• Ciepłe: przekierowuje połączenie wraz z podsumowaniem sytuacji dla konsultanta odbierającego połączenie.

Dostępne opcje przekierowania według dostawcy

SIP

• Zimna konferencja: (sip_cold_conference_transfer) Odbiorca zostaje dodany do połączenia bez komunikatu
  • Obsługuje tylko numery telefonów
• SIP REFER: (sip_cold_refer_transfer) Połączenie zostaje przekazane do celu przez SIP REFER bez komunikatu
  • Obsługuje zarówno numery telefonów, jak i identyfikatory URI SIP
  • Niestandardowe nagłówki SIP, zmienne statyczne lub dynamiczne
  • UUI (User-to-User Information) do przekazywania kontekstu, np. identyfikatora CRM
  • Odtwarzaj sygnał dzwonienia (domyślnie włączone): dzwoniący słyszy sygnał podczas realizacji przekierowania. Wyłącz tę opcję, a usłyszy ciszę.

Twilio

• Zimne: (twilio_cold_blind_transfer) Odbiorca zostaje dodany do połączenia bez komunikatu
  • Obsługuje tylko numery telefonów
  • Cyfry po połączeniu: tony DTMF wysyłane po nawiązaniu połączenia
• Ciepłe: (twilio_warm_conference_transfer) Odbiorca słyszy podsumowanie agenta, a potem zostaje połączony
  • Obsługuje tylko numery telefonów
  • Cyfry po połączeniu: tony DTMF wysyłane po nawiązaniu połączenia

Exotel

• Zimne: (exotel_warm_transfer) Odbiorca zostaje dodany do połączenia bez komunikatu
  • Obsługuje tylko numery telefonów
• Ciepłe: (twilio_warm_conference_transfer) Odbiorca słyszy podsumowanie agenta, a potem zostaje połączony
  • Obsługuje tylko numery telefonów

Szczegóły dodatkowej konfiguracji

Cyfry po połączeniu

• Tony DTMF wysyłane po nawiązaniu połączenia, np. w1W234
• Każde w oznacza pauzę 0,5 s
• Każde W oznacza pauzę 1 s

Niestandardowe nagłówki SIP

Dodatkowe nagłówki SIP wysyłane z przekierowaniem, dzięki którym system odbierający (PBX, contact center) otrzymuje twoje dane, np. X-Customer-ID: 12345.

• Gdzie: tylko SIP trunk i SIP REFER.
• Limity:
  • Maks. 20 nagłówków na przekierowanie.
  • Nazwa: do 64 znaków. Tylko litery, cyfry i pojedyncze łączniki.

UUI (User-to-User Information)

Skonfiguruj UUI dla każdej reguły przekierowania za pomocą obiektu uui:

• data: Dane do wysłania jako zwykły tekst. ElevenLabs koduje je szesnastkowo i dodaje ;encoding=hex. Mogą to być statyczny tekst lub zmienne dynamiczne. Maksymalnie 256 bajtów (UTF-8), limit jest sprawdzany po zastąpieniu zmiennych dynamicznych — dla zwykłego ASCII to 256 znaków, mniej dla znaków wielobajtowych.
• protocol_discriminator: Pojedynczy oktet szesnastkowy, na przykład 04. Dodaj go dla platform, które usuwają pierwszy oktet danych; pomiń go dla platform, które przekazują dane bez zmian.
• protocol_discriminator_mode: prefix (domyślnie) dodaje oktet na początku, tworząc 04<hex>;encoding=hex. pd_parameter dodaje go jako osobny parametr, tworząc <hex>;pd=04;encoding=hex.

Aby odbierać UUI przy przychodzących połączeniach SIP, nie musisz nic konfigurować. Gdy przychodzący INVITE zawiera nagłówek User-to-User, jego wartość jest udostępniana agentowi jako zmienne dynamiczne {{sip_uui_raw}} i {{sip_uui_data}}. Zobacz dokumentację SIP.

Włączanie przekierowania do konsultanta

Implementacja API

Narzędzie systemowe transfer_to_number możesz skonfigurować podczas tworzenia lub aktualizowania agenta przez API (Utwórz agenta, Zaktualizuj agenta). Narzędzie pozwala określić wiadomości zarówno dla klienta (przekierowywanego użytkownika), jak i agenta (konsultanta odbierającego połączenie).

from elevenlabs import AgentConfig, ConversationalConfig, ElevenLabs
elevenlabs = ElevenLabs(api_key="YOUR_API_KEY")
billing_destination = {"type": "phone", "destination": "+15551234567"}
human_destination = {"type": "phone", "destination": "+15559876543"}
# Each rule lists one config per telephony provider. A call only sees the rules
# that have a config for its provider (twilio, sip_trunk or exotel).
transfer_rules = [
    {
        "condition": "When the user asks for billing support.",
        "provider_configs": [
            {
                "type": "twilio",
                "config": {
                    "type": "twilio_warm_conference_transfer",
                    "transfer_destination": billing_destination,
                    # Wait 1s, then dial extension 1234 (Twilio only)
                    "post_dial_digits": {"type": "static", "value": "ww1234"},
                },
            },
            {
                "type": "sip_trunk",
                "config": {
                    "type": "sip_cold_conference_transfer",
                    "transfer_destination": billing_destination,
                },
            },
            {
                "type": "exotel",
                "config": {
                    "type": "exotel_warm_transfer",
                    "transfer_destination": billing_destination,
                },
            },
        ],
    },
    {
        "condition": "When the user asks to speak to a human.",
        "provider_configs": [
            {
                "type": "twilio",
                "config": {
                    # Preserves caller ID, no warm transfer message
                    "type": "twilio_cold_blind_transfer",
                    "transfer_destination": human_destination,
                },
            },
            {
                "type": "exotel",
                "config": {
                    "type": "exotel_cold_blind_transfer",
                    "transfer_destination": human_destination,
                },
            },
        ],
    },
    {
        "condition": "When the user requests to file a formal complaint.",
        "provider_configs": [
            {
                "type": "sip_trunk",
                "config": {
                    "type": "sip_cold_refer_transfer",
                    "transfer_destination": {"type": "sip_uri", "destination": "sip:support@example.com"},
                    "custom_sip_headers": [
                        {"type": "static", "key": "X-Department", "value": "complaints"},
                        {"type": "static", "key": "X-Priority", "value": "high"},
                        # "dynamic" takes the dynamic variable's name, without {{ }}
                        {"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",
                        "description": "Transfer the user to a human operator based on their request.",
                        "params": {
                            "system_tool_type": "transfer_to_number",
                            # Still required, and must be empty when transfer_rules is set
                            "transfers": [],
                            "transfer_rules": transfer_rules,
                        },
                    }
                },
            },
        ),
    ),
)

Dokumentacja API

Starsza konfiguracja

Dokumentacja starszych transferów

Typy transferów

System obsługuje trzy typy transferów:

• Transfer konferencyjny: Domyślne działanie polega na połączeniu z numerem docelowym i dodaniu uczestnika do pokoju konferencyjnego, a następnie usunięciu agenta AI, tak aby pozostali tylko dzwoniący i przekazany uczestnik. W przypadku korzystania z natywnej integracji Twilio obsługuje komunikat zapowiedzi transferu (agent_message) odczytywany operatorowi.
• Transfer bezpośredni: Przekazuje połączenie bezpośrednio do numeru docelowego bez komunikatu zapowiedzi transferu dla operatora. Zachowuje oryginalny identyfikator dzwoniącego. Dostępny tylko wtedy, gdy numer telefonu agenta został zaimportowany przez natywną integrację Twilio.
• Transfer SIP REFER: Używa protokołu SIP REFER, aby przekazać połączenie bezpośrednio do miejsca docelowego. Działa zarówno z numerami telefonów, jak i identyfikatorami URI SIP, ale jest dostępny tylko wtedy, gdy podczas rozmowy używany jest protokół SIP i wymaga, by Twój SIP Trunk zezwalał na transfer przez SIP REFER. Nie obsługuje komunikatów zapowiedzi transferu.

Komunikaty zapowiedzi transferu (agent_message) są dostępne tylko wtedy, gdy numer telefonu agenta został zaimportowany przez natywną integrację Twilio. Transfery oparte na SIP nie obsługują komunikatów zapowiedzi transferu.

Transfery bezpośrednie są dostępne tylko wtedy, gdy numer telefonu agenta został zaimportowany przez natywną integrację Twilio i obecnie trzeba je skonfigurować w edytorze JSON w interfejsie. W konfiguracji narzędzia transferu wybierz „Edytuj jako JSON” i ustaw "transfer_type": "blind" dla wybranej reguły transferu.

Cel: Płynne przekazywanie rozmów konsultantom, gdy pomoc AI nie wystarcza.

Warunki wywołania: LLM powinien wywołać to narzędzie, gdy:

• Występują złożone problemy wymagające ludzkiego osądu
• Użytkownik wyraźnie prosi o pomoc człowieka
• AI osiąga granice swoich możliwości w przypadku konkretnej prośby
• Zostają uruchomione procedury eskalacji

Parametry:

• reason (string, opcjonalny): Powód przekazania
• transfer_number (string, wymagany): Numer telefonu, na który należy przekazać rozmowę (musi odpowiadać skonfigurowanym numerom)
• client_message (string, wymagany): Wiadomość odczytywana klientowi podczas oczekiwania na przekazanie
• agent_message (string, wymagany): Wiadomość dla konsultanta przejmującego rozmowę

Format wywołania funkcji:

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

Implementacja: Skonfiguruj numery telefonów i warunki przekazywania. Zdefiniuj wiadomości dla klienta i konsultanta przejmującego rozmowę. Działa zarówno z Twilio, jak i trunkingiem SIP.

Numery, na które można przekazywać połączenia

Transfer do człowieka pozwala przekazywać połączenia na zewnętrzne numery telefonów, korzystając zarówno z SIP trunkingu, jak i numerów telefonów Twilio.

Włączanie transferu do człowieka

Transfer do człowieka konfigurujesz za pomocą narzędzia systemowego transfer_to_number.

1

Dodaj narzędzie transferu

Włącz transfer do człowieka, wybierając narzędzie systemowe transfer_to_number w konfiguracji agenta na karcie Agent. Podczas dodawania narzędzia wybierz „Transfer to Human”.

2

Skonfiguruj opis narzędzia (opcjonalnie)

Możesz podać własny opis, aby wskazać LLM, kiedy ma uruchomić transfer. Jeśli pozostawisz to pole puste, użyjemy domyślnego opisu obejmującego zdefiniowane reguły transferu.

3

Zdefiniuj reguły transferu

Skonfiguruj konkretne reguły przekazywania połączeń na numery telefonów lub identyfikatory URI SIP. Dla każdej reguły określ:

• Typ transferu: Wybierz transfer konferencyjny (domyślny), bezpośredni lub SIP REFER
• Typ numeru: Wybierz Phone dla zwykłych numerów telefonów lub SIP URI dla adresów SIP
• Numer telefonu/SIP URI: Docelowy adres w odpowiednim formacie:
  • Numery telefonów: format E.164 (np. +12125551234)
  • Identyfikatory URI SIP: format SIP (np. sip:1234567890@example.com)
• Warunek: Opis sytuacji w języku naturalnym, w której powinien nastąpić transfer (np. „Użytkownik wyraźnie prosi o rozmowę z człowiekiem”, „Użytkownik musi zaktualizować poufne informacje o koncie”).

LLM użyje tych warunków wraz z opisem narzędzia, aby zdecydować, kiedy i dokąd przekazać połączenie.

Transfery SIP REFER wymagają użycia protokołu SIP podczas rozmowy, a Twój SIP Trunk musi zezwalać na transfer przez SIP REFER. Tylko SIP REFER obsługuje transfer na identyfikator URI SIP.

Transfery bezpośrednie są dostępne tylko wtedy, gdy numer telefonu agenta został zaimportowany przez natywną integrację Twilio, i trzeba je skonfigurować w edytorze JSON. Oryginalny identyfikator dzwoniącego zostaje zachowany, ale operator nie otrzymuje komunikatu zapowiedzi transferu.

Upewnij się, że miejsca docelowe mają prawidłowy format:

• Numery telefonów: format E.164 i powiązanie z prawidłowo skonfigurowanym kontem
• Identyfikatory URI SIP: prawidłowy format SIP (sip:user@domain lub sips:user@domain)

4

Skonfiguruj własne nagłówki SIP REFER (opcjonalnie)

W przypadku transferów SIP REFER możesz dodać własne nagłówki SIP, aby przekazać dodatkowe informacje do systemu odbierającego.

Dla każdego własnego nagłówka określ:

• Nazwa nagłówka: Nazwa nagłówka SIP (np. X-Customer-ID, X-Priority)
• Wartość nagłówka: Wartość nagłówka, która może być statycznym tekstem lub zawierać zmienne dynamiczne

Własne nagłówki SIP REFER są dołączane tylko do transferów SIP REFER. Transfery konferencyjne nie obsługują własnych nagłówków.

Nagłówki systemowe X-Conversation-ID i X-Caller-ID są automatycznie dodawane przez ElevenLabs i zastępują własne nagłówki o tych samych nazwach (bez rozróżniania wielkości liter).

5

Skonfiguruj informacje User-to-User (UUI) (opcjonalnie)

Transfery SIP REFER mogą przenosić informacje User-to-User (UUI), czyli niewielki ładunek dostarczany do platformy odbierającej (na przykład Talkdesk lub Genesys Cloud) w parametrze User-to-User nagłówka Refer-To. UUI jest wysyłane tylko w przypadku transferów SIP REFER do miejsca docelowego SIP URI; miejsca docelowe będące numerami telefonów (tel:) go nie przenoszą.

Skonfiguruj UUI dla każdej reguły transferu za pomocą obiektu uui:

• data: Ładunek do wysłania jako zwykły tekst. ElevenLabs koduje go szesnastkowo i dodaje ;encoding=hex. Może to być statyczny tekst lub tekst zawierający zmienne dynamiczne. Maksymalnie 256 bajtów (UTF-8), sprawdzane po podstawieniu zmiennych dynamicznych — dla zwykłego ASCII to 256 znaków, a dla znaków wielobajtowych mniej.
• protocol_discriminator: Pojedynczy oktet szesnastkowy, na przykład 04. Dodaj go dla platform, które usuwają pierwszy oktet ładunku; pomiń dla platform przekazujących ładunek bez zmian.
• protocol_discriminator_mode: prefix (domyślnie) dodaje oktet na początku, tworząc 04<hex>;encoding=hex. pd_parameter dodaje go jako osobny parametr, tworząc <hex>;pd=04;encoding=hex.

Talkdesk przekazuje wartość bez zmian, więc pomiń rozróżniacz protokołu. Genesys Cloud usuwa pierwszy oktet ładunku, chyba że rozróżniacz jest obecny, więc dodaj protocol_discriminator. Zobacz formaty danych UUI Genesys.

Limit 256 bajtów obowiązuje po podstawieniu zmiennych dynamicznych. Przekazuj identyfikatory lub krótkie kody, takie jak identyfikator konta, a nie dowolny tekst, np. pełne podsumowanie rozmowy, które przekracza limit i zostaje pominięte w transferze.

Aby odbierać UUI przy przychodzących połączeniach SIP, nie musisz nic konfigurować. Gdy przychodzące żądanie INVITE zawiera nagłówek User-to-User, jego wartość jest dostępna dla agenta jako zmienne dynamiczne {{sip_uui_raw}} i {{sip_uui_data}}. Zobacz dokumentację SIP.

6

Skonfiguruj cyfry wybierane po połączeniu (opcjonalnie)

Cyfry wybierane po połączeniu to tony DTMF przekazywane po połączeniu z miejscem docelowym transferu. Przydają się do automatycznego wprowadzania numerów wewnętrznych lub poruszania się po menu IVR (Interactive Voice Response).

Dla każdej reguły transferu możesz określić ciąg post_dial_digits zawierający:

• Cyfry (0-9): Standardowe tony DTMF
• w: Opóźnienie 0,5 sekundy
• W: Opóźnienie 1 sekundy
• * i #: Specjalne tony DTMF

Na przykład ww1234 czeka 1 sekundę po połączeniu, a następnie wybiera numer wewnętrzny 1234.

Cyfry wybierane po połączeniu są dostępne tylko wtedy, gdy numer telefonu agenta (numer inicjujący transfer) został zaimportowany przez natywną integrację Twilio. Numer docelowy może być dowolnym numerem telefonu.

Cyfry wybierane po połączeniu są obsługiwane tylko dla transferów konferencyjnych i bezpośrednich. Transfery SIP REFER nie obsługują cyfr wybieranych po połączeniu.

Implementacja API

Możesz skonfigurować narzędzie systemowe transfer_to_number podczas tworzenia lub aktualizowania agenta przez API (Utwórz agenta, Zaktualizuj agenta). Narzędzie pozwala określić komunikaty zarówno dla klienta (użytkownika, którego połączenie jest przekazywane), jak i agenta (operatora odbierającego połączenie).

PythonJavaScript

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