Doorverbinden naar nummer

Verbind gesprekken door naar externe telefoonnummers of SIP-URI’s op basis van gedefinieerde voorwaarden.

Overzicht

Met de systeemtool transfer_to_number kan een ElevenLabs-agent het lopende gesprek doorverbinden naar een opgegeven telefoonnummer of SIP-URI wanneer aan bepaalde voorwaarden is voldaan. Zo kunnen agents complexe problemen, specifieke verzoeken of situaties die menselijke tussenkomst vereisen doorgeven aan een live medewerker.

Deze functie ondersteunt doorverbinden via Twilio- en SIP-trunknummers. Wanneer de tool wordt geactiveerd, kan de agent een bericht voor de gebruiker geven tijdens het wachten en een apart bericht dat de situatie samenvat voor de menselijke medewerker die het gesprek ontvangt.

De systeemtool transfer_to_number is alleen beschikbaar voor telefoongesprekken en niet in de chatwidget.

Doorverbindtypen

Het systeem ondersteunt drie typen doorverbindingen:

Conferentiedoorverbinding: Standaardgedrag waarbij de bestemming wordt gebeld en de deelnemer aan een conferentieruimte wordt toegevoegd. Vervolgens wordt de AI-agent verwijderd, zodat alleen de beller en de doorverbonden deelnemer overblijven. Bij gebruik van de native Twilio-integratie wordt een warm doorverbindingsbericht (agent_message) voorgelezen aan de menselijke medewerker.
Blinde doorverbinding: Verbindt het gesprek rechtstreeks door naar de bestemming, zonder een warm doorverbindingsbericht voor de menselijke medewerker. De oorspronkelijke beller-ID blijft behouden. Alleen beschikbaar wanneer het telefoonnummer van de agent is geïmporteerd via de native Twilio-integratie.
SIP REFER-doorverbinding: Gebruikt het SIP REFER-protocol om gesprekken rechtstreeks door te verbinden naar de bestemming. Werkt met zowel telefoonnummers als SIP-URI’s, maar is alleen beschikbaar wanneer tijdens het gesprek het SIP-protocol wordt gebruikt en vereist dat je SIP Trunk doorverbinden via SIP REFER toestaat. Ondersteunt geen warme doorverbindingsberichten.

Warme doorverbindingsberichten (agent_message) zijn alleen beschikbaar wanneer het telefoonnummer van de agent is geïmporteerd via de native Twilio- integratie. Doorverbindingen via SIP ondersteunen geen warme doorverbindingsberichten.

Blinde doorverbindingen zijn alleen beschikbaar wanneer het telefoonnummer van de agent is geïmporteerd via de native Twilio-integratie en moeten momenteel worden geconfigureerd via de JSON-editor in de UI. Selecteer “Bewerken als JSON” in de configuratie van de doorverbindings- tool en stel "transfer_type": "blind" in voor de gewenste doorverbindingsregel.

Doel: Gesprekken naadloos doorverbinden met menselijke medewerkers wanneer AI-ondersteuning niet toereikend is.

Triggervoorwaarden: De LLM moet deze tool aanroepen wanneer:

Er complexe kwesties zijn die menselijk oordeel vereisen
De gebruiker expliciet om menselijke hulp vraagt
De AI voor het specifieke verzoek de grenzen van zijn mogelijkheden bereikt
Escalatieprotocollen worden geactiveerd

Parameters:

reason (string, optioneel): De reden voor de doorverbinding
transfer_number (string, vereist): Het telefoonnummer waarnaar wordt doorverbonden (moet overeenkomen met geconfigureerde nummers)
client_message (string, vereist): Bericht dat aan de klant wordt voorgelezen tijdens het wachten op de doorverbinding
agent_message (string, vereist): Bericht voor de menselijke medewerker die het gesprek ontvangt

Indeling van de functieaanroep:

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

Implementatie: Configureer telefoonnummers en voorwaarden voor doorverbinden. Definieer berichten voor zowel de klant als de menselijke medewerker die het gesprek ontvangt. Werkt met zowel Twilio als SIP trunking.

Nummers waarnaar kan worden doorverbonden

Menselijke doorverbinding ondersteunt het doorverbinden naar externe telefoonnummers via zowel SIP-trunking als Twilio-telefoonnummers.

Menselijke doorverbinding inschakelen

Menselijke doorverbinding wordt geconfigureerd met de systeemtool transfer_to_number.

De doorverbindingstool toevoegen

Schakel menselijke doorverbinding in door de systeemtool transfer_to_number te selecteren in de configuratie van je agent op het tabblad Agent. Kies “Doorverbinden met medewerker” wanneer je een tool toevoegt.

Tool voor menselijke doorverbinding toevoegen — Tool 'Doorverbinden met medewerker' selecteren

Toolbeschrijving configureren (optioneel)

Je kunt een aangepaste beschrijving opgeven om de LLM te sturen bij het bepalen wanneer een doorverbinding moet worden geactiveerd. Als je dit leeg laat, wordt een standaardbeschrijving gebruikt die de gedefinieerde doorverbindingsregels omvat.

Beschrijving van tool voor menselijke doorverbinding — Beschrijving van de doorverbindingstool configureren

Doorverbindingsregels definiëren

Configureer de specifieke regels voor doorverbinden naar telefoonnummers of SIP-URI’s. Geef voor elke regel het volgende op:

Doorverbindtype: Kies tussen de doorverbindingsmethoden Conferentie (standaard), Blind of SIP REFER
Nummertype: Selecteer Telefoon voor gewone telefoonnummers of SIP-URI voor SIP-adressen
Telefoonnummer/SIP-URI: De doelbestemming in de juiste indeling:
- Telefoonnummers: E.164-indeling (bijv. +12125551234)
- SIP-URI’s: SIP-indeling (bijv. sip:1234567890@example.com)
Voorwaarde: Een beschrijving in natuurlijke taal van de omstandigheden waaronder de doorverbinding moet plaatsvinden (bijv. “Gebruiker vraagt expliciet om met een medewerker te spreken”, “Gebruiker moet gevoelige accountgegevens bijwerken”).

De LLM gebruikt deze voorwaarden samen met de toolbeschrijving om te bepalen wanneer en naar welke bestemming moet worden doorverbonden.

SIP REFER-doorverbindingen vereisen het SIP-protocol tijdens het gesprek en je SIP Trunk moet doorverbinden via SIP REFER toestaan. Alleen SIP REFER ondersteunt doorverbinden naar een SIP-URI.

Blinde doorverbindingen zijn alleen beschikbaar wanneer het telefoonnummer van de agent is geïmporteerd via de native Twilio-integratie en moeten via de JSON-editor worden geconfigureerd. De oorspronkelijke beller-ID blijft behouden, maar er wordt geen warm doorverbindingsbericht naar de menselijke medewerker gestuurd.

Configuratie van regels voor menselijke doorverbinding — Doorverbindingsregels met telefoonnummer en voorwaarde definiëren

Zorg dat bestemmingen de juiste indeling hebben:

Telefoonnummers: E.164-indeling en gekoppeld aan een juist geconfigureerd account
SIP-URI’s: Geldige SIP-indeling (sip:user@domain of sips:user@domain)

Aangepaste SIP REFER-headers configureren (optioneel)

Bij SIP REFER-doorverbindingen kun je aangepaste SIP-headers opnemen om aanvullende informatie door te geven aan het ontvangende systeem.

Geef voor elke aangepaste header het volgende op:

Headernaam: De naam van de SIP-header (bijv. X-Customer-ID, X-Priority)
Headerwaarde: De headerwaarde, die statische tekst kan zijn of dynamische variabelen kan bevatten

Aangepaste SIP REFER-headers worden alleen opgenomen bij SIP REFER-doorverbindingen. Conferentiedoorverbindingen ondersteunen geen aangepaste headers.

Systeemheaders X-Conversation-ID en X-Caller-ID worden automatisch toegevoegd door ElevenLabs en overschrijven aangepaste headers met dezelfde namen (hoofdletterongevoelig).

User-to-User Information (UUI) configureren (optioneel)

SIP REFER-doorverbindingen kunnen User-to-User Information (UUI) bevatten, een kleine payload die aan het ontvangende platform (bijvoorbeeld Talkdesk of Genesys Cloud) wordt geleverd in de parameter User-to-User van de header Refer-To. UUI wordt alleen verzonden bij SIP REFER-doorverbindingen naar een SIP-URI-bestemming; bestemmingen met een telefoonnummer (tel:) bevatten deze informatie niet.

Configureer UUI per doorverbindingsregel met het object uui:

data: De te verzenden payload, als platte tekst. ElevenLabs codeert deze hexadecimaal en voegt ;encoding=hex toe. Kan statische tekst zijn of dynamische variabelen bevatten. Maximaal 256 bytes (UTF-8), afgedwongen nadat dynamische variabelen zijn vervangen — voor gewone ASCII zijn dat 256 tekens, minder voor tekens van meerdere bytes.
protocol_discriminator: Eén hexadecimaal octet, bijvoorbeeld 04. Voeg dit toe voor platforms die het eerste octet van de payload verwijderen; laat het weg voor platforms die de payload ongewijzigd doorgeven.
protocol_discriminator_mode: prefix (standaard) plaatst het octet vooraan, wat resulteert in 04<hex>;encoding=hex. pd_parameter voegt dit toe als afzonderlijke parameter, wat resulteert in <hex>;pd=04;encoding=hex.

Talkdesk geeft de waarde ongewijzigd door, dus laat de protocol discriminator weg. Genesys Cloud verwijdert het eerste octet van de payload tenzij er een discriminator aanwezig is, dus voeg een protocol_discriminator toe. Zie Genesys UUI-dataformaten.

De limiet van 256 bytes geldt nadat dynamische variabelen zijn vervangen. Geef ID’s of korte codes door, zoals een account-ID, geen vrije tekst zoals een volledige samenvatting van een gesprek; die overschrijdt de limiet en wordt niet meegenomen in de doorverbinding.

Voor het ontvangen van UUI bij inkomende SIP-gesprekken is geen configuratie nodig. Wanneer een inkomende INVITE een header User-to-User bevat, wordt de waarde ervan beschikbaar gesteld aan de agent als de dynamische variabelen {{sip_uui_raw}} en {{sip_uui_data}}. Zie de SIP-referentie.

Nabeltonen configureren (optioneel)

Nabeltonen zijn DTMF-tonen die worden doorgestuurd nadat de telefoon verbinding heeft gemaakt met de doorverbindingsbestemming. Dit is handig om automatisch extensies in te voeren of IVR-menu’s (Interactive Voice Response) te doorlopen.

Voor elke doorverbindingsregel kun je een string post_dial_digits opgeven die het volgende bevat:

Cijfers (0-9): Standaard DTMF-tonen
w: Vertraging van 0,5 seconde
W: Vertraging van 1 seconde
* en #: Speciale DTMF-tonen

ww1234 wacht bijvoorbeeld 1 seconde nadat het gesprek is verbonden en kiest vervolgens extensie 1234.

Nabeltonen zijn alleen beschikbaar wanneer het telefoonnummer van de agent (het nummer dat de doorverbinding start) is geïmporteerd via de native Twilio-integratie. Het bestemmingsnummer kan elk telefoonnummer zijn.

Nabeltonen worden alleen ondersteund voor de doorverbindtypen conferentie en blind. SIP REFER-doorverbindingen ondersteunen geen nabeltonen.

API-implementatie

Je kunt de systeemtool transfer_to_number configureren wanneer je via de API een agent maakt of bijwerkt (Agent maken, Agent bijwerken). Met de tool kun je berichten opgeven voor zowel de client (gebruiker die wordt doorverbonden) als de agent (menselijke medewerker die het gesprek ontvangt).

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