KonfiguracjaNarzędziaNarzędzia systemowe

Przekierowanie na numer

Przekierowuj połączenia na zewnętrzne numery telefonów lub identyfikatory URI SIP na podstawie określonych warunków.

Omówienie

Narzędzie systemowe transfer_to_number pozwala agentowi ElevenLabs przekazać trwające połączenie na wskazany numer telefonu lub URI SIP, gdy zostaną spełnione określone warunki. Dzięki temu agenci mogą przekazywać złożone problemy, konkretne prośby lub sytuacje wymagające interwencji człowieka operatorowi na żywo.

Ta funkcja obsługuje przekierowania przez numery Twilio i SIP trunk. Po uruchomieniu agent może przekazać użytkownikowi wiadomość na czas oczekiwania oraz osobną wiadomość podsumowującą sytuację dla operatora odbierającego połączenie.

Narzędzie systemowe transfer_to_number jest dostępne tylko dla połączeń telefonicznych, a nie w widżecie czatu.

Typy przekierowań

System obsługuje trzy typy przekierowań:

  • Przekierowanie konferencyjne: Domyślne zachowanie — wywołuje numer docelowy i dodaje uczestnika do pokoju konferencyjnego, a następnie usuwa agenta AI, tak aby pozostali tylko dzwoniący i przekierowany uczestnik. Przy korzystaniu z natywnej integracji Twilio obsługuje wiadomość ciepłego przekierowania (agent_message) odczytywaną operatorowi.
  • Przekierowanie bez zapowiedzi: Przekazuje połączenie bezpośrednio do celu bez wiadomości ciepłego przekierowania dla operatora. Zachowuje oryginalny identyfikator dzwoniącego. Dostępne tylko wtedy, gdy numer telefonu agenta został zaimportowany przez natywną integrację Twilio.
  • Przekierowanie SIP REFER: Używa protokołu SIP REFER, aby przekazać połączenia bezpośrednio do celu. Działa zarówno z numerami telefonów, jak i URI SIP, ale jest dostępne tylko przy użyciu protokołu SIP podczas rozmowy i wymaga, aby twój SIP Trunk zezwalał na przekierowanie przez SIP REFER. Nie obsługuje wiadomości ciepłego przekierowania.

Wiadomości ciepłego przekierowania (agent_message) są dostępne tylko wtedy, gdy numer telefonu agenta został zaimportowany przez natywną integrację Twilio . Przekierowania oparte na SIP nie obsługują wiadomości ciepłego przekierowania.

Przekierowania bez zapowiedzi 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 przekierowania wybierz „Edytuj jako JSON” i ustaw "transfer_type": "blind" dla wybranej reguły przekierowania.

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 przekierować połączenie

Przekierowanie do człowieka obsługuje przekazywanie połączeń na zewnętrzne numery telefonów przez SIP trunking i numery telefonów Twilio.

Włączanie przekierowania do człowieka

Przekierowanie do człowieka konfiguruje się za pomocą narzędzia systemowego transfer_to_number.

1

Dodaj narzędzie przekierowania

Włącz przekierowanie 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”.

Dodaj narzędzie przekierowania do człowieka
Wybierz narzędzie „Transfer to Human”
2

Skonfiguruj opis narzędzia (opcjonalnie)

Możesz dodać własny opis, który wskaże LLM, kiedy uruchomić przekierowanie. Jeśli pozostawisz pole puste, użyty zostanie domyślny opis obejmujący zdefiniowane reguły przekierowania.

Opis narzędzia przekierowania do człowieka
Skonfiguruj opis narzędzia przekierowania
3

Zdefiniuj reguły przekierowania

Skonfiguruj konkretne reguły przekierowywania na numery telefonów lub URI SIP. Dla każdej reguły określ:

  • Typ przekierowania: Wybierz metodę konferencyjną (domyślna), bez zapowiedzi lub SIP REFER
  • Typ numeru: Wybierz Telefon dla zwykłych numerów telefonów lub URI SIP dla adresów SIP
  • Numer telefonu/URI SIP: Cel w odpowiednim formacie:
  • Warunek: Opis w języku naturalnym okoliczności, w których ma nastąpić przekierowanie (np. „Użytkownik wyraźnie prosi o rozmowę z człowiekiem”, „Użytkownik musi zaktualizować poufne dane konta”).

LLM użyje tych warunków wraz z opisem narzędzia, aby zdecydować, kiedy i do którego celu przekierować połączenie.

Przekierowania SIP REFER wymagają protokołu SIP podczas rozmowy, a twój SIP Trunk musi zezwalać na przekierowanie przez SIP REFER. Tylko SIP REFER obsługuje przekierowanie na URI SIP.

Przekierowania bez zapowiedzi 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 jest zachowany, ale operator nie otrzymuje wiadomości ciepłego przekierowania.

Konfiguracja reguł przekierowania do człowieka
Zdefiniuj reguły przekierowania z numerem telefonu i warunkiem

Upewnij się, że cele mają poprawny format:

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

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

Przy przekierowaniach 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ć tekstem statycznym lub zawierać zmienne dynamiczne

Własne nagłówki SIP REFER są dołączane tylko do przekierowań SIP REFER. Przekierowania 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 User-to-User Information (UUI) (opcjonalnie)

Przekierowania SIP REFER mogą zawierać User-to-User Information (UUI), niewielki ładunek przekazywany 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 przy przekierowaniach SIP REFER do URI SIP; cele będące numerami telefonów (tel:) go nie przenoszą.

Skonfiguruj UUI dla każdej reguły przekierowania 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ć tekst statyczny lub zawierać zmienne dynamiczne. Maksymalnie 256 bajtów (UTF-8), egzekwowane po podstawieniu 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 ładunku; pomiń dla platform, które przekazują ładunek bez zmian.
  • protocol_discriminator_mode: prefix (domyślnie) dodaje oktet na początku, dając 04<hex>;encoding=hex. pd_parameter dodaje go jako osobny parametr, dając <hex>;pd=04;encoding=hex.

Talkdesk przekazuje wartość bez zmian, więc pomiń wyróżnik protokołu. Genesys Cloud usuwa pierwszy oktet ładunku, chyba że wyróżnik 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 ID konta, a nie swobodny tekst, np. pełne podsumowanie rozmowy, które przekracza limit i jest pomijane przy przekierowaniu.

Aby otrzymywać UUI w 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.

6

Skonfiguruj cyfry wybierane po połączeniu (opcjonalnie)

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

Dla każdej reguły przekierowania 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 przekierowanie) został zaimportowany przez natywną integrację Twilio. Numer docelowy może być dowolnym numerem telefonu.

Cyfry wybierane po połączeniu są obsługiwane tylko dla typów przekierowania konferencyjnego i bez zapowiedzi. Przekierowania SIP REFER nie obsługują cyfr wybieranych po połączeniu.

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 (użytkownika przekierowywanego), jak i agenta (operatora odbierającego połączenie).

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