An Nummer weiterleiten | ElevenLabs Documentation

Übersicht

Das Systemtool transfer_to_number ermöglicht einem ElevenLabs-Agenten, den laufenden Anruf an eine bestimmte Telefonnummer oder SIP-URI weiterzuleiten, wenn bestimmte Bedingungen erfüllt sind. So können Agenten komplexe Anliegen, spezifische Anfragen oder Situationen, die menschliches Eingreifen erfordern, an einen Live-Mitarbeiter übergeben.

Diese Funktion unterstützt Weiterleitungen über Twilio- und SIP-Trunk-Nummern. Bei Auslösung kann der Agent dem Nutzer eine Nachricht während der Wartezeit sowie eine separate Nachricht mit einer Zusammenfassung der Situation für den menschlichen Mitarbeiter geben, der den Anruf entgegennimmt.

Das Systemtool transfer_to_number ist nur für Telefonanrufe verfügbar und nicht im Chat-Widget.

Weiterleitungstypen

Das System unterstützt drei Arten von Weiterleitungen:

Konferenzweiterleitung: Standardverhalten: Das Ziel wird angerufen und der Teilnehmer zu einem Konferenzraum hinzugefügt. Anschließend wird der KI-Agent entfernt, sodass nur der Anrufer und der weitergeleitete Teilnehmer verbleiben. Bei Verwendung der nativen Twilio-Integration wird eine Warm-Transfer-Nachricht (agent_message) unterstützt, die dem menschlichen Mitarbeiter vorgelesen wird.
Blinde Weiterleitung: Leitet den Anruf direkt an das Ziel weiter, ohne eine Warm-Transfer-Nachricht an den menschlichen Mitarbeiter. Die ursprüngliche Anrufer-ID bleibt erhalten. Nur verfügbar, wenn die Telefonnummer des Agenten über die native Twilio-Integration importiert wurde.
SIP-REFER-Weiterleitung: Verwendet das SIP-REFER-Protokoll, um Anrufe direkt an das Ziel weiterzuleiten. Funktioniert mit Telefonnummern und SIP-URIs, ist jedoch nur verfügbar, wenn während des Gesprächs das SIP-Protokoll verwendet wird und Ihr SIP-Trunk die Weiterleitung über SIP REFER erlaubt. Unterstützt keine Warm-Transfer-Nachrichten.

Warm-Transfer-Nachrichten (agent_message) sind nur verfügbar, wenn die Telefonnummer des Agenten über die native Twilio- Integration importiert wurde. SIP-basierte Weiterleitungen unterstützen keine Warm-Transfer-Nachrichten.

Blinde Weiterleitungen sind nur verfügbar, wenn die Telefonnummer des Agenten über die native Twilio-Integration importiert wurde, und müssen derzeit über den JSON-Editor in der UI konfiguriert werden. Wählen Sie in der Konfiguration des Weiterleitungstools „Als JSON bearbeiten“ und setzen Sie "transfer_type": "blind" für die gewünschte Weiterleitungsregel.

Zweck: Unterhaltungen nahtlos an menschliche Mitarbeiter übergeben, wenn KI-Unterstützung nicht ausreicht.

Auslösebedingungen: Das LLM sollte dieses Tool aufrufen, wenn:

komplexe Probleme menschliches Urteilsvermögen erfordern
der Nutzer ausdrücklich menschliche Unterstützung anfordert
die KI bei der spezifischen Anfrage an die Grenzen ihrer Fähigkeiten stößt
Eskalationsprotokolle ausgelöst werden

Parameter:

reason (string, optional): Der Grund für die Übergabe
transfer_number (string, erforderlich): Die Telefonnummer für die Weiterleitung (muss mit den konfigurierten Nummern übereinstimmen)
client_message (string, erforderlich): Nachricht, die dem Kunden während der Wartezeit auf die Weiterleitung vorgelesen wird
agent_message (string, erforderlich): Nachricht für den menschlichen Mitarbeiter, der den Anruf entgegennimmt

Format des Funktionsaufrufs:

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

Implementierung: Konfigurieren Sie Telefonnummern und Bedingungen für Weiterleitungen. Definieren Sie Nachrichten für Kunden und für den menschlichen Mitarbeiter, der den Anruf entgegennimmt. Funktioniert mit Twilio und SIP-Trunking.

Ziele für Weiterleitungen

Die Weiterleitung an menschliche Mitarbeiter unterstützt externe Telefonnummern über SIP-Trunking und Twilio-Telefonnummern.

Weiterleitung an menschliche Mitarbeiter aktivieren

Die Weiterleitung an menschliche Mitarbeiter wird mit dem Systemtool transfer_to_number konfiguriert.

Weiterleitungstool hinzufügen

Aktivieren Sie die Weiterleitung an menschliche Mitarbeiter, indem Sie in der Konfiguration Ihres Agenten auf dem Tab Agent das Systemtool transfer_to_number auswählen. Wählen Sie beim Hinzufügen eines Tools „An Menschen weiterleiten“.

Tool für Weiterleitung an Menschen hinzufügen — Tool „An Menschen weiterleiten“ auswählen

Toolbeschreibung konfigurieren (optional)

Sie können eine benutzerdefinierte Beschreibung angeben, um das LLM bei der Entscheidung zu leiten, wann eine Weiterleitung ausgelöst werden soll. Wenn Sie das Feld leer lassen, wird eine Standardbeschreibung verwendet, die die definierten Weiterleitungsregeln umfasst.

Beschreibung des Tools für die Weiterleitung an Menschen — Beschreibung des Weiterleitungstools konfigurieren

Weiterleitungsregeln definieren

Konfigurieren Sie die spezifischen Regeln für Weiterleitungen an Telefonnummern oder SIP-URIs. Geben Sie für jede Regel Folgendes an:

Weiterleitungstyp: Wählen Sie zwischen den Weiterleitungsmethoden Konferenz (Standard), Blind oder SIP REFER
Nummerntyp: Wählen Sie Telefon für reguläre Telefonnummern oder SIP-URI für SIP-Adressen
Telefonnummer/SIP-URI: Das Ziel im passenden Format:
- Telefonnummern: E.164-Format (z. B. +12125551234)
- SIP-URIs: SIP-Format (z. B. sip:1234567890@example.com)
Bedingung: Eine Beschreibung in natürlicher Sprache der Umstände, unter denen die Weiterleitung erfolgen soll (z. B. „Der Nutzer bittet ausdrücklich darum, mit einem Menschen zu sprechen“, „Der Nutzer muss sensible Kontoinformationen aktualisieren“).

Das LLM verwendet diese Bedingungen zusammen mit der Toolbeschreibung, um zu entscheiden, wann und an welches Ziel weitergeleitet wird.

SIP-REFER-Weiterleitungen erfordern während des Gesprächs das SIP-Protokoll, und Ihr SIP-Trunk muss die Weiterleitung über SIP REFER erlauben. Nur SIP REFER unterstützt Weiterleitungen an eine SIP-URI.

Blinde Weiterleitungen sind nur verfügbar, wenn die Telefonnummer des Agenten über die native Twilio-Integration importiert wurde, und müssen über den JSON-Editor konfiguriert werden. Die ursprüngliche Anrufer-ID bleibt erhalten, es wird jedoch keine Warm-Transfer-Nachricht an den menschlichen Mitarbeiter gesendet.

Konfiguration der Regeln für die Weiterleitung an Menschen — Weiterleitungsregeln mit Telefonnummer und Bedingung definieren

Stellen Sie sicher, dass Ziele korrekt formatiert sind:

Telefonnummern: E.164-Format und mit einem korrekt konfigurierten Konto verknüpft
SIP-URIs: Gültiges SIP-Format (sip:user@domain oder sips:user@domain)

Benutzerdefinierte SIP-REFER-Header konfigurieren (optional)

Bei SIP-REFER-Weiterleitungen können Sie benutzerdefinierte SIP-Header einschließen, um zusätzliche Informationen an das empfangende System zu übermitteln.

Geben Sie für jeden benutzerdefinierten Header Folgendes an:

Header-Name: Der Name des SIP-Headers (z. B. X-Customer-ID, X-Priority)
Header-Wert: Der Header-Wert, der statischer Text sein oder dynamische Variablen enthalten kann

Benutzerdefinierte SIP-REFER-Header werden nur bei SIP-REFER-Weiterleitungen eingeschlossen. Konferenzweiterleitungen unterstützen keine benutzerdefinierten Header.

Die Systemheader X-Conversation-ID und X-Caller-ID werden automatisch von ElevenLabs eingeschlossen und überschreiben alle benutzerdefinierten Header mit denselben Namen, unabhängig von Groß- und Kleinschreibung.

User-to-User Information (UUI) konfigurieren (optional)

SIP-REFER-Weiterleitungen können User-to-User Information (UUI) übertragen, eine kleine Nutzlast, die im Parameter User-to-User des Headers Refer-To an die empfangende Plattform (z. B. Talkdesk oder Genesys Cloud) übermittelt wird. UUI wird nur bei SIP-REFER-Weiterleitungen an ein SIP-URI-Ziel gesendet; Ziele mit Telefonnummern (tel:) übertragen sie nicht.

Konfigurieren Sie UUI pro Weiterleitungsregel mit dem Objekt uui:

data: Die zu sendende Nutzlast als Klartext. ElevenLabs hex-kodiert sie und fügt ;encoding=hex an. Sie kann statischer Text sein oder dynamische Variablen enthalten. Maximal 256 Byte (UTF-8), geprüft nach dem Ersetzen dynamischer Variablen — bei reinem ASCII sind das 256 Zeichen, bei Mehrbyte-Zeichen weniger.
protocol_discriminator: Ein einzelnes Hex-Oktett, z. B. 04. Verwenden Sie es für Plattformen, die das erste Oktett der Nutzlast entfernen; lassen Sie es weg für Plattformen, die die Nutzlast unverändert weitergeben.
protocol_discriminator_mode: prefix (Standard) stellt das Oktett voran und erzeugt 04<hex>;encoding=hex. pd_parameter fügt es als separaten Parameter hinzu und erzeugt <hex>;pd=04;encoding=hex.

Talkdesk gibt den Wert unverändert weiter, lassen Sie den Protokolldiskriminator daher weg. Genesys Cloud entfernt das erste Oktett der Nutzlast, sofern kein Diskriminator vorhanden ist. Verwenden Sie daher protocol_discriminator. Siehe Genesys-UUI-Datenformate.

Das Limit von 256 Byte gilt nach dem Ersetzen dynamischer Variablen. Übergeben Sie Kennungen oder kurze Codes wie eine Konto-ID, keinen Freitext wie eine vollständige Anrufzusammenfassung. Diese überschreitet das Limit und wird bei der Weiterleitung verworfen.

Für den Empfang von UUI bei eingehenden SIP-Anrufen ist keine Konfiguration erforderlich. Wenn ein eingehendes INVITE einen Header User-to-User enthält, wird sein Wert dem Agenten als dynamische Variablen {{sip_uui_raw}} und {{sip_uui_data}} bereitgestellt. Siehe die SIP-Referenz.

Nachwahlziffern konfigurieren (optional)

Nachwahlziffern sind DTMF-Töne, die nach dem Verbindungsaufbau zum Weiterleitungsziel übertragen werden. Das ist hilfreich, um Durchwahlen einzugeben oder IVR-Menüs (Interactive Voice Response) automatisch zu navigieren.

Für jede Weiterleitungsregel können Sie einen String post_dial_digits mit Folgendem angeben:

Ziffern (0-9): Standard-DTMF-Töne
w: Verzögerung von 0,5 Sekunden
W: Verzögerung von 1 Sekunde
* und #: Spezielle DTMF-Töne

Beispielsweise wartet ww1234 nach dem Verbindungsaufbau 1 Sekunde und wählt dann die Durchwahl 1234.

Nachwahlziffern sind nur verfügbar, wenn die Telefonnummer des Agenten (die Nummer, die die Weiterleitung initiiert) über die native Twilio-Integration importiert wurde. Die Zielnummer kann jede Telefonnummer sein.

Nachwahlziffern werden nur für die Weiterleitungstypen Konferenz und Blind unterstützt. SIP-REFER-Weiterleitungen unterstützen keine Nachwahlziffern.

API-Implementierung

Sie können das Systemtool transfer_to_number beim Erstellen oder Aktualisieren eines Agenten über die API konfigurieren (Agent erstellen, Agent aktualisieren). Mit dem Tool können Nachrichten sowohl für den Client (den weitergeleiteten Nutzer) als auch für den Agenten (den menschlichen Mitarbeiter, der den Anruf entgegennimmt) angegeben werden.

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