Telefon-API-Referenz

Diese Referenz dokumentiert die tracker_api-Methoden, die für Telefon-Bots verfügbar sind. Diese Methoden ermöglichen es Ihnen, Anrufe zu steuern, STT/TTS zu konfigurieren, Aufnahmen zu verwalten und mehr.

Übersicht

Telefon-spezifische Methoden sind über das tracker_api-Objekt in Ihren Aktionsknoten und benutzerdefinierten Skripten verfügbar, wenn der Telefonkanal aktiviert ist.

from shared import RemoteLLMTrackerApi

async def run(tracker_api: RemoteLLMTrackerApi):
    # Telefonmethoden sind auf tracker_api verfügbar
    tracker_api.hangup()

Anrufsteuerung

hangup()

Beendet den Telefonanruf sofort.

tracker_api.hangup()

Parameter: Keine

Rückgabewert: Keine

Verhalten:

Löst ein HangupEvent im Telefonsystem aus
Der Anruf wird sofort beendet
Der signalhangup-Fluss wird danach ausgelöst

Beispiel:

async def run(tracker_api: RemoteLLMTrackerApi):
    await tracker_api.fixed_utter("Danke für Ihren Anruf. Auf Wiedersehen!")
    tracker_api.hangup()

forward_call()

Leitet den aktuellen Anruf an eine andere Telefonnummer weiter, indem ein neuer Anrufabschnitt verbunden wird. Der botario-Telefonserver bleibt in der Schleife und der Bot kann auf das Ergebnis (angenommen, besetzt, keine Antwort usw.) reagieren.

tracker_api.forward_call(
    forward_call_id: str,
    forward_call_ringing: int = 15,
    sip_headers: dict | None = None,
    sip_endpoint: str | None = None
)

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
`forward_call_id`	str	Ja	-	Telefonnummer, an die weitergeleitet werden soll
`forward_call_ringing`	int	Nein	15	Sekunden, die vor dem Timeout klingeln sollen
`sip_headers`	dict	Nein	Keine	Benutzerdefinierte SIP-Header für den weitergeleiteten Anruf
`sip_endpoint`	str	Nein	Keine	SIP-Endpunkt, der für die Weiterleitung verwendet werden soll. Standardmäßig der eingehende Endpunkt

Rückgabewert: Keine

Empfohlen: Verwenden Sie den Weiterleitungsknoten im Flusseditor anstelle des direkten Aufrufs von forward_call(). Der Weiterleitungsknoten behandelt die asynchrone Natur der Anrufweiterleitung automatisch.

Wichtig: Asynchrones Verhalten

Die Anrufweiterleitung wird asynchron vom PhoneServer verarbeitet. Wenn Sie forward_call() aufrufen:

Die Weiterleitungsanfrage wird an den PhoneServer gesendet
Der PhoneServer initiiert den weitergeleiteten Anruf
Der weitergeleitete Anruf wird abgeschlossen (angenommen, besetzt, keine Antwort usw.)
Der Wählstatus wird mit der nächsten Benutzereingabe vom PhoneServer zurückgegeben

Das bedeutet: Sie können den sys_phone_dialstatus-Slot nicht im selben Aktionsknoten lesen, der forward_call() aufruft. Der Wählstatus ist noch nicht verfügbar.

Verwendung von forward_call() in Aktionsknoten

Wenn Sie forward_call() anstelle des Weiterleitungsknotens verwenden müssen, benötigen Sie zwei separate Aktionsknoten:

Aktionsknoten 1 - Weiterleitung initiieren:

async def run(tracker_api: RemoteLLMTrackerApi):
    await tracker_api.fixed_utter("Ich verbinde Sie jetzt mit einem Support-Mitarbeiter.")
    
    tracker_api.forward_call(
        forward_call_id="+49123456789",
        forward_call_ringing=30,
        sip_headers={"X-Customer-ID": "12345"}
    )
    # Versuchen Sie NICHT, den Wählstatus hier zu lesen - er ist noch nicht verfügbar!

Aktionsknoten 2 - Ergebnis behandeln (verbunden nach Abschluss der Weiterleitung):

async def run(tracker_api: RemoteLLMTrackerApi):
    # Jetzt ist der Wählstatus verfügbar
    dial_status = tracker_api.get_slot("sys_phone_dialstatus")
    
    if dial_status == "ANSWER":
        await tracker_api.fixed_utter("Ich hoffe, das hat geholfen. Gibt es noch etwas anderes?")
    elif dial_status == "NOANSWER":
        await tracker_api.fixed_utter("Entschuldigung, es war niemand verfügbar. Möchten Sie eine Nachricht hinterlassen?")
    elif dial_status == "BUSY":
        await tracker_api.fixed_utter("Die Leitung ist besetzt. Möchten Sie es erneut versuchen?")
    else:
        await tracker_api.fixed_utter("Der Anruf konnte nicht verbunden werden. Wie kann ich sonst helfen?")

Wie der Weiterleitungsknoten funktioniert

Der eingebaute Weiterleitungsknoten behandelt dies automatisch, indem er:

Das ForwardEvent an den PhoneServer sendet
Ein RequestUserInputEvent auslöst, um auf die Antwort des PhoneServers zu warten
Beim nächsten Gesprächswechsel (nach Abschluss der Weiterleitung) den Wählstatus liest und zum entsprechenden Zweig übergeht

Deshalb wird die Verwendung des Weiterleitungsknotens empfohlen - er kapselt dieses zweiphasige Muster ein.

Wählstatus-Ergebnisse:

Nachdem der weitergeleitete Anruf beendet ist, wird das Ergebnis im sys_phone_dialstatus-Slot gespeichert:

Status	Beschreibung
`ANSWER`	Anruf wurde erfolgreich angenommen
`BUSY`	Angerufene Partei war besetzt
`NOANSWER`	Angerufene Partei hat nicht geantwortet
`CHANUNAVAIL`	Endpunkt nicht erreichbar oder nicht registriert
`CONGESTION`	Kanal-/Schaltüberlastung
`CANCEL`	Anruf vor Annahme abgebrochen
`DONTCALL`	Ablehnung im Datenschutzmodus
`TORTURE`	Ablehnung im Datenschutzmodus (Folterskript)
`INVALIDARGS`	Ungültige Syntax in der Weiterleitungsanfrage

transfer_call()

Überträgt den aktuellen Anruf direkt an eine andere Telefonnummer über SIP REFER und beendet sofort das Gespräch. Im Gegensatz zu forward_call() hat der Bot keine Kenntnis darüber, ob die Übertragung erfolgreich war, und kann nicht auf das Ergebnis reagieren.

tracker_api.transfer_call(
    forward_call_id: str
)

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`forward_call_id`	str	Ja	Telefonnummer, an die der Anruf übertragen werden soll

Rückgabewert: Keine

Verhalten:

Sendet ein TransferEvent an das Telefonsystem über SIP REFER
Der Bot beendet sofort das Gespräch — es gibt keinen Wählstatus, keinen Rückruf und keine weiteren Gesprächswechsel
Verwenden Sie dies, wenn Sie den Anruf vollständig übergeben möchten, ohne in der Schleife zu bleiben

forward_call() vs transfer_call()

	`forward_call()`	`transfer_call()`
Mechanismus	Verbindet einen neuen Anrufabschnitt	SIP REFER
Bot bleibt in der Schleife	Ja	Nein
Wählstatus verfügbar	Ja (`sys_phone_dialstatus`)	Nein
Kann auf besetzt/keine Antwort reagieren	Ja	Nein

Beispiel:

async def run(tracker_api: RemoteLLMTrackerApi):
    await tracker_api.fixed_utter("Ich werde Sie jetzt weiterleiten. Auf Wiedersehen!")
    tracker_api.transfer_call(forward_call_id="+49123456789")

STT-Konfiguration

update_stt_config()

Aktualisiert die Konfiguration für Sprache-zu-Text während eines Anrufs dynamisch.

from botario_gpt_events.phone_events import (
    BotarioSTTConfigUpdatePayload,
    AzureSTTConfigUpdatePayload,
    GoogleSTTConfigUpdatePayload,
)

tracker_api.update_stt_config(
    update_payload: BotarioSTTConfigUpdatePayload | AzureSTTConfigUpdatePayload | GoogleSTTConfigUpdatePayload,
    provider_title: str | None = None
)

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`update_payload`	Payload-Klasse	Ja	Anbieter-spezifische Konfigurationsnutzlast
`provider_title`	str	Nein	Wechseln Sie zu einem anderen Anbieter nach dessen Titel

Wichtig: Anbieterkompatibilität

Der update_payload-Typ muss mit dem Anbietertyp übereinstimmen:

Anbietertyp	Erforderliche Payload-Klasse
botario	`BotarioSTTConfigUpdatePayload`
Azure	`AzureSTTConfigUpdatePayload`
Google	`GoogleSTTConfigUpdatePayload`

Wenn provider_title nicht angegeben ist:

Der derzeit aktive STT-Anbieter wird verwendet
Der Payload-Typ muss mit dem Typ des aktiven Anbieters übereinstimmen
Wenn Sie früher im Gespräch den Anbieter gewechselt haben und den falschen Payload-Typ verwenden, wird ein ValueError ausgelöst

Wenn provider_title angegeben ist:

Das System sucht nach einem aktivierten Anbieter mit diesem Titel
Der Payload-Typ muss mit dem Typ dieses Anbieters übereinstimmen
Wenn der Anbieter nicht gefunden wird, wird ein ValueError ausgelöst

Beispiel - Korrekte Verwendung mit aktivem Anbieter:

# Wenn Ihr aktiver Anbieter Azure ist, verwenden Sie AzureSTTConfigUpdatePayload
tracker_api.update_stt_config(
    AzureSTTConfigUpdatePayload(language_code="de-DE")
)

# Dies würde einen ValueError auslösen, wenn der aktive Anbieter Azure ist:
# tracker_api.update_stt_config(
#     BotarioSTTConfigUpdatePayload(language="de")  # Falscher Payload-Typ!
# )

Beispiel - Wechsel zu einem bestimmten Anbieter:

# Wechseln Sie zu einem Anbieter namens "Mein Azure STT"
tracker_api.update_stt_config(
    AzureSTTConfigUpdatePayload(language_code="en-US"),
    provider_title="Mein Azure STT"
)

BotarioSTTConfigUpdatePayload

from botario_gpt_events.phone_events import BotarioSTTConfigUpdatePayload

tracker_api.update_stt_config(
    BotarioSTTConfigUpdatePayload(
        transcription_mode="alpha_num",  # "alpha_num" oder "default"
        language="de",
        silero_vad_min_score=0.5,        # VAD-Vertrauensschwelle (0.0-1.0)
        min_speech_len_in_s=0.3,         # Mindestsprachdauer
        start_listening_offset=0.5,       # Frühes Zuhören starten
        keep_audio_after_speech_in_s=0.75, # Wartezeit nach der Sprache
        hotwords="botario, IBAN",             # Komma-getrennte Hotwords zur Verstärkung
        hotword_boosting_tree_alpha=1.0,  # Verstärkungsaggression (Standard: 1.0)
        hotword_context_score=1.0         # Additiver Bonus für Hotwords (1.0-5.0)
    )
)

Beispiel - Wechsel in den alphanumerischen Modus:

async def capture_iban(tracker_api: RemoteLLMTrackerApi):
    # Wechsel in den alphanumerischen Modus zur IBAN-Erfassung
    tracker_api.update_stt_config(
        BotarioSTTConfigUpdatePayload(
            transcription_mode="alpha_num"
        )
    )
    
    await tracker_api.fixed_utter("Bitte buchstabieren Sie jetzt Ihre IBAN.")
    # Benutzereingaben werden für alphanumerische Sequenzen optimiert

Hotword-Verstärkung

Die Hotword-Verstärkung verbessert die Erkennung spezifischer Wörter oder Begriffe, die für Ihren Anwendungsfall wichtig sind. Dies ist nützlich, wenn das STT-Modell domänenspezifische Begriffe mit ähnlich klingenden allgemeinen Wörtern verwechseln könnte.

Parameter	Typ	Standard	Beschreibung
`hotwords`	str \| None	Keine	Komma-getrennte Liste von Wörtern zur Verstärkung (z.B. `'botario, IBAN'`). Groß-/Kleinschreibung beachten - jedes Wort sollte nur einmal in der erwarteten Schreibweise erscheinen
`hotword_boosting_tree_alpha`	float \| None	1.0	Skalierungsfaktor, der steuert, wie aggressiv das System der Hotword-Liste im Vergleich zum akustischen Modell vertraut
`hotword_context_score`	float \| None	1.0	Additiver Bonus für Tokens in der Hotword-Liste. Höhere Werte (1.0–5.0) lenken das Modell dazu, Hotwords gegenüber ähnlich klingenden Alternativen zu bevorzugen. Erhöhen, wenn Hotwords ignoriert werden, verringern, wenn sie fälschlicherweise erkannt werden

Wichtig: hotword_boosting_tree_alpha und hotword_context_score funktionieren nur mit transcription_mode='alpha_num'. Die Verwendung mit transcription_mode='default' führt zu einem ValueError.

Beispiel - Verstärkung der IBAN-Erkennung:

async def capture_iban(tracker_api: RemoteLLMTrackerApi):
    tracker_api.update_stt_config(
        BotarioSTTConfigUpdatePayload(
            transcription_mode="alpha_num",
            hotwords="IBAN",
            hotword_context_score=1.5,
            hotword_boosting_tree_alpha=1.0,
        )
    )

    await tracker_api.fixed_utter("Bitte buchstabieren Sie jetzt Ihre IBAN.")

Smart Turn und spekulative Transkription

Smart Turn ermöglicht die serverseitige End-of-Turn-Erkennung für botario STT. Anstatt nur auf das feste VAD-Stillefenster (keep_audio_after_speech_in_s) zu warten, kann der STT-Dienst während der Stille ein Smart Turn-Modell ausführen und früher entscheiden, ob der Anrufer mit dem Sprechen fertig ist. Dies reduziert die wahrgenommene Latenz in Telefongesprächen, während der reguläre VAD-Timeout als Fallback beibehalten wird.

Spekulative Transkription ist der sanftere Weg derselben Funktion: Wenn Smart Turn vorhersagt, dass eine Äußerung abgeschlossen ist, aber das Vertrauen nicht hoch genug für eine sofortige Finalisierung ist, kann der STT-Dienst beginnen, das aktuelle Audiosegment im Hintergrund zu transkribieren. Wenn die normale VAD-Decke danach das Ende der Sprache bestätigt, kann das bereits laufende Transkript anstelle eines Neustarts wiederverwendet werden. Wenn der Anrufer weiter spricht, wird das spekulative Ergebnis verworfen.

Parameter	Typ	Standard	Beschreibung
`smart_turn_enabled`	bool \| None	Keine	Aktiviert oder deaktiviert Smart Turn für die aktuelle botario STT-Konfiguration. Wenn aktiviert, muss die STT-Bereitstellung Smart Turn-Unterstützung verfügbar haben.
`smart_turn_speculative_threshold`	float \| None	Keine	Minimale Smart Turn-Wahrscheinlichkeit für den Start der spekulativen Transkription. Dies sollte niedriger oder gleich `smart_turn_finalize_threshold` sein.
`smart_turn_finalize_threshold`	float \| None	Keine	Minimale Smart Turn-Wahrscheinlichkeit für die sofortige Finalisierung des aktuellen Sprachsegments vor dem regulären VAD-Stille-Timeout. 1.0 deaktiviert die Funktion.
`smart_turn_min_silence_s`	float \| None	Keine	Minimale Stille nach der Sprache, bevor Smart Turn abgefragt wird. Dies muss kleiner sein als `keep_audio_after_speech_in_s`, damit Smart Turn vor der regulären VAD-Finalisierung ausgeführt werden kann.

Wichtig: Smart Turn funktioniert nur mit botario STT-Bereitstellungen, die Smart Turn serverseitig aktiviert haben. Ungültiges Timing wird abgelehnt: smart_turn_min_silence_s muss kleiner sein als keep_audio_after_speech_in_s, und smart_turn_speculative_threshold darf nicht höher sein als smart_turn_finalize_threshold.

Beispiel - Aktivieren von Smart Turn für schnellere Turn-Endungen:

tracker_api.update_stt_config(
    BotarioSTTConfigUpdatePayload(
        smart_turn_enabled=True,
        keep_audio_after_speech_in_s=0.75,
        smart_turn_min_silence_s=0.2,
        smart_turn_speculative_threshold=0.5,
        smart_turn_finalize_threshold=0.7,
    )
)

AzureSTTConfigUpdatePayload

from botario_gpt_events.phone_events import AzureSTTConfigUpdatePayload

tracker_api.update_stt_config(
    AzureSTTConfigUpdatePayload(
        language_code="de-DE",           # oder Liste zur automatischen Erkennung: ["de-DE", "en-US"]
        profanity_filter="masked",       # "raw", "masked" oder "removed"
        enable_dictation=True,           # Besser für längere Sprache
        region="germanywestcentral",
        semantic_segmentation=True,      # Bessere Satzstruktur
        keep_audio_after_speech_in_s=1.0
    )
)

GoogleSTTConfigUpdatePayload

from botario_gpt_events.phone_events import GoogleSTTConfigUpdatePayload

tracker_api.update_stt_config(
    GoogleSTTConfigUpdatePayload(
        language_code="de-DE",
        profanity_filter=True,
        enable_automatic_punctuation=True,
        enable_spoken_punctuation=True,
        model="telephony"  # "phone_call", "telephony", "telephony_short", "command_and_search"
    )
)

TTS-Konfiguration

update_tts_config()

Aktualisiert die Konfiguration für Text-zu-Sprache während eines Anrufs dynamisch.

from botario_gpt_events.api_config.tts_api_config import (
    BotarioTTSConfigUpdatePayload,
    AzureTTSConfigUpdatePayload,
    GoogleTTSConfigUpdatePayload,
    ElevenLabsTTSConfigUpdatePayload,
)

tracker_api.update_tts_config(
    update_payload: BotarioTTSConfigUpdatePayload | AzureTTSConfigUpdatePayload | GoogleTTSConfigUpdatePayload | ElevenLabsTTSConfigUpdatePayload,
    provider_title: str | None = None
)

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`update_payload`	Payload-Klasse	Ja	Anbieter-spezifische Konfigurationsnutzlast
`provider_title`	str	Nein	Wechseln Sie zu einem anderen Anbieter nach dessen Titel

Wichtig: Anbieterkompatibilität

Der update_payload-Typ muss mit dem Anbietertyp übereinstimmen:

Anbietertyp	Erforderliche Payload-Klasse
botario	`BotarioTTSConfigUpdatePayload`
Azure	`AzureTTSConfigUpdatePayload`
Google	`GoogleTTSConfigUpdatePayload`
ElevenLabs	`ElevenLabsTTSConfigUpdatePayload`

Wenn provider_title nicht angegeben ist:

Der derzeit aktive TTS-Anbieter wird verwendet
Der Payload-Typ muss mit dem Typ des aktiven Anbieters übereinstimmen
Wenn Sie früher im Gespräch den Anbieter gewechselt haben und den falschen Payload-Typ verwenden, wird ein ValueError ausgelöst

Wenn provider_title angegeben ist:

Das System sucht nach einem aktivierten Anbieter mit diesem Titel
Der Payload-Typ muss mit dem Typ dieses Anbieters übereinstimmen
Wenn der Anbieter nicht gefunden wird, wird ein ValueError ausgelöst

Beispiel - Korrekte Verwendung mit aktivem Anbieter:

# Wenn Ihr aktiver Anbieter Google ist, verwenden Sie GoogleTTSConfigUpdatePayload
tracker_api.update_tts_config(
    GoogleTTSConfigUpdatePayload(speaking_rate=0.9)
)

# Dies würde einen ValueError auslösen, wenn der aktive Anbieter Google ist:
# tracker_api.update_tts_config(
#     AzureTTSConfigUpdatePayload(speaking_rate=0.9)  # Falscher Payload-Typ!
# )

Beispiel - Wechsel zu einem bestimmten Anbieter:

# Wechseln Sie zu einem Anbieter namens "Meine ElevenLabs-Stimme"
tracker_api.update_tts_config(
    ElevenLabsTTSConfigUpdatePayload(
        voice="custom_voice_id",
        stability=0.8
    ),
    provider_title="Meine ElevenLabs-Stimme"
)

AzureTTSConfigUpdatePayload

from botario_gpt_events.api_config.tts_api_config import AzureTTSConfigUpdatePayload

tracker_api.update_tts_config(
    AzureTTSConfigUpdatePayload(
        language_code="de-DE",
        voice="de-DE-KatjaNeural",
        speaking_rate=0.9,    # 0.25-4.0
        pitch=0.0             # -20.0 bis 20.0
    )
)

GoogleTTSConfigUpdatePayload

from botario_gpt_events.api_config.tts_api_config import GoogleTTSConfigUpdatePayload

tracker_api.update_tts_config(
    GoogleTTSConfigUpdatePayload(
        language_code="de-DE",
        voice="de-DE-Chirp3-HD-Puck",
        speaking_rate=1.0,    # 0.25-2.0
        gender="FEMALE"       # "MALE", "FEMALE", "NEUTRAL"
    )
)

ElevenLabsTTSConfigUpdatePayload

from botario_gpt_events.api_config.tts_api_config import ElevenLabsTTSConfigUpdatePayload

tracker_api.update_tts_config(
    ElevenLabsTTSConfigUpdatePayload(
        voice="voice_id_here",
        speaking_rate=1.0,         # 0.7-1.2
        similarity_boost=0.7,      # 0.0-1.0
        stability=0.7,             # 0.0-1.0
        model="eleven_turbo_v2_5"
    )
)

Beispiel - Anpassung für ältere Anrufer:

async def adjust_for_accessibility(tracker_api: RemoteLLMTrackerApi):
    # Verlangsamen Sie die Sprache für ein besseres Verständnis
    tracker_api.update_tts_config(
        GoogleTTSConfigUpdatePayload(
            speaking_rate=0.8,
            gender="NEUTRAL"
        )
    )

Aufnahme-Steuerung

enable_recording()

Aktiviert oder deaktiviert die Anrufaufzeichnung.

tracker_api.enable_recording(enable: bool = True)

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
`enable`	bool	Nein	True	True, um zu aktivieren, False, um zu deaktivieren

Anforderungen:

Die Aufzeichnung des Telefonkanals muss auf "Bei Anforderung" oder "Immer" eingestellt sein
Wenn auf "Nie" eingestellt, hat diese Methode keine Wirkung

Beispiel:

async def start_recording_with_consent(tracker_api: RemoteLLMTrackerApi):
    await tracker_api.fixed_utter(
        "Dieser Anruf kann zu Qualitätszwecken aufgezeichnet werden. "
        "Stimmen Sie der Aufzeichnung zu?"
    )
    
    # ... Benutzerantwort erhalten ...
    
    if user_consented:
        tracker_api.enable_recording(enable=True)
        await tracker_api.fixed_utter("Danke. Die Aufnahme hat begonnen.")
    else:
        await tracker_api.fixed_utter("Verstanden. Dieser Anruf wird nicht aufgezeichnet.")

DTMF-Eingabe

enable_dtmf()

Aktiviert die DTMF (Tonwahl)-Eingabe des Benutzers für genau eine Runde. Dies ist nützlich, wenn Sie möchten, dass Benutzer mit Ihrem Bot über ihre Telefontastatur interagieren, z.B. zum Navigieren durch Menüs, Eingeben von PINs oder Auswählen von Optionen. Der DTMF-Modus wird automatisch deaktiviert, nachdem die Benutzereingabe empfangen wurde, sodass Sie ihn erneut aktivieren müssen, wenn Sie weitere Ziffern erfassen möchten.

Wenn DTMF aktiviert ist, bleibt die Spracherkennung (STT) parallel aktiv - beide Kanäle hören gleichzeitig zu. Die Eingaben werden jedoch nie kombiniert: Welcher Kanal zuerst ein Ergebnis liefert, gewinnt. Wenn DTMF-Ziffern erkannt werden, werden sie als Eingabe verwendet und das Sprachresultat wird vollständig verworfen. Wenn die Spracherkennung vor dem Eintreffen einer DTMF-Eingabe abgeschlossen ist, wird die transkribierte Sprache als Ergebnis verwendet.

await tracker_api.enable_dtmf(
    termination_symbol: str = "#",
    single_digit_mode: bool = False,
    time_out: float | None = None
)

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
`termination_symbol`	str	Nein	"#"	Das Symbol, das der Benutzer eingeben muss, um anzuzeigen, dass seine Eingabe abgeschlossen ist
`single_digit_mode`	bool	Nein	False	Wenn True, wird nur eine einzelne Ziffer erwartet und kein Abschlusssymbol ist erforderlich. Die Eingabe wird automatisch nach einer Ziffer abgeschlossen
`time_out`	float	Nein	Keine	Sekunden, die nach der letzten empfangenen Ziffer auf weitere Ziffern gewartet werden. 0 bedeutet kein Timeout. Vorsicht vor möglichen Deadlock-Situationen bei unbegrenzter Ziffernlänge und keinem Timeout

Warnung: Die Verwendung unbegrenzter Zifferneingaben ohne Timeout kann zu einem Deadlock führen. Setzen Sie immer mindestens einen Timeout-Wert.

Beispiel - Menünavigation (Einzelziffer):

async def phone_menu(tracker_api: RemoteLLMTrackerApi):
    await tracker_api.enable_dtmf(single_digit_mode=True, time_out=10)
    
    await tracker_api.fixed_utter(
        "Drücken Sie 1 für Vertrieb, 2 für Support oder 3, um mit einem Agenten zu sprechen."
    )
    
    # Die DTMF-Eingabe des Benutzers wird als Text erfasst

Umgebungsgeräusche

enable_ambience_channel()

Aktiviert Hintergrundgeräusche während des Anrufs.

await tracker_api.enable_ambience_channel(
    sound_name: Literal["tastatur", "copy_machine", "office", "background_music"],
    volume: int = 0
)

Parameter:

Parameter	Typ	Erforderlich	Standard	Beschreibung
`sound_name`	str	Ja	-	Abzuspielendes Umgebungsgeräusch
`volume`	int	Nein	0	Lautstärkeanpassung (-10 bis 20)

Verfügbare Geräusche:

Geräusch	Beschreibung
`tastatur`	Tastaturtippen
`copy_machine`	Kopierer-/Druckergeräusche
`office`	Allgemeine Büroatmosphäre
`background_music`	Wartemusik

disable_ambience_channel()

Deaktiviert ein bestimmtes Umgebungsgeräusch.

await tracker_api.disable_ambience_channel(
    sound_name: Literal["tastatur", "copy_machine", "office", "background_music"]
)

Beispiel - Wartemusik:

async def put_on_hold(tracker_api: RemoteLLMTrackerApi):
    await tracker_api.fixed_utter("Bitte warten Sie, während ich das nachschaue.")
    await tracker_api.enable_ambience_channel("background_music", volume=5)
    
    # ... Nachschlagen durchführen ...
    
    await tracker_api.disable_ambience_channel("background_music")
    await tracker_api.fixed_utter("Danke fürs Warten. Ich habe Ihre Informationen gefunden.")

Beispiel - Büroatmosphäre:

async def create_office_feel(tracker_api: RemoteLLMTrackerApi):
    # Erstellen Sie Hintergrund-Bürogeräusche für ein menschlicheres Gefühl
    await tracker_api.enable_ambience_channel("office", volume=-5)
    await tracker_api.enable_ambience_channel("tastatur", volume=-8)

Kontaktinformationen

get_contact_info()

Ruft Kontaktinformationen ab, die mit dem Anrufer verbunden sind.

contact = tracker_api.get_contact_info()

Rückgabewert: ContactInfo | None

class ContactInfo:
    category: str | None  # Kontaktkategorie
    number: str           # Telefonnummer
    meta: str | None      # Zusätzliche Metadaten

Beispiel:

async def greet_caller(tracker_api: RemoteLLMTrackerApi):
    contact = tracker_api.get_contact_info()
    
    if contact and contact.category == "VIP":
        await tracker_api.fixed_utter(
            f"Willkommen zurück! Ich sehe, dass Sie von {contact.number} anrufen."
        )
    else:
        await tracker_api.fixed_utter("Willkommen! Wie kann ich Ihnen heute helfen?")

save_contact_info()

Speichert oder aktualisiert Kontaktinformationen für den Anrufer.

from shared.tracker.phone import ContactInfo

tracker_api.save_contact_info(
    contact_info: ContactInfo | dict
)

Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`contact_info`	ContactInfo oder dict	Ja	Zu speichernde Kontaktdaten

Beispiel:

async def save_caller_info(tracker_api: RemoteLLMTrackerApi):
    from shared.tracker.phone import ContactInfo
    
    caller_number = tracker_api.get_slot("sys_phone_caller_id")
    
    tracker_api.save_contact_info(
        ContactInfo(
            number=caller_number,
            category="Kunde",
            meta="Registriert am 2024-01-15"
        )
    )

Telefonstatistik-API

Rufen Sie aggregierte Statistiken pro Anruf für einen Bot über einen Zeitraum ab. Dies ist ein REST-Endpunkt (im Gegensatz zu den obigen tracker_api-Methoden) und verwendet dasselbe Authentifizierungsschema wie Ausgehende Anrufe.

API-Endpunkt

GET /api/bots/{botId}/phone-statistics

Anfrage-Header

x-api-key: {your-api-key}

Erfordert einen API-Schlüssel mit dem Scope Read und der Rolle Channel Manager (siehe API-Schlüssel).

Abfrageparameter

Parameter	Typ	Erforderlich	Beschreibung
`start`	String (Datum)	Nein	Beginn des Zeitraums, in UTC interpretiert und auf den Tagesanfang normalisiert. Standard ist der Beginn des aktuellen Monats.
`end`	String (Datum)	Nein	Ende des Zeitraums, in UTC interpretiert und auf das Tagesende normalisiert. Standard ist das Ende des aktuellen Monats.

Statistiken werden periodisch zusammengefasst, daher erscheinen sehr aktuelle Anrufe möglicherweise nicht sofort.

Antwort

{
  "totals": {
    "totalCalls": 128,
    "totalDuration": 20480,
    "avgDuration": 160,
    "totalTimeWithBot": 15360,
    "totalTimeWithHuman": 5120,
    "totalTtsDurationInS": 4300,
    "totalSttDurationInS": 3100,
    "totalTimeWaitingForHandover": 640,
    "forwardedCalls": 42,
    "successfulForwardedCalls": 38,
    "acceptedWithinServiceLevel20s": 30,
    "containmentRate": 0.66,
    "transferRate": 0.33,
    "avgTimeWithBot": 120,
    "avgTimeWithHuman": 40,
    "avgHandoverWaitTime": 15
  },
  "byHangup": [
    { "_id": "assistant", "count": 85 },
    { "_id": "user", "count": 40 },
    { "_id": "error", "count": 3 }
  ],
  "byProvider": [
    { "_id": "sip_endpoint_a", "totalCalls": 90, "totalDuration": 14400 }
  ],
  "daily": [
    { "date": "2026-07-01", "totalCalls": 12, "totalDuration": 1920, "totalTimeWithBot": 1440 }
  ],
  "handoverWaitDistribution": { "0_5s": 20, "5_10s": 10, "10_15s": 5, "15_20s": 3, "20_25s": 2, "30s_plus": 2 },
  "dropOutWaitDistribution": { "0_5s": 1, "5_10s": 0, "10_15s": 1, "15_20s": 0, "20_25s": 0, "30s_plus": 0 }
}

Feld	Typ	Beschreibung
`totals`	Objekt \| null	Aggregierte Summen für den Zeitraum. `null`, wenn im Zeitraum keine Anrufe vorliegen.
`byHangup`	Array	Anrufe pro Auflegegrund. `_id` ist `assistant` (Bot hat den Anruf beendet), `user` (Anrufer hat aufgelegt) oder `error` (abnormale Beendigung).
`byProvider`	Array	Aufschlüsselung pro SIP-Endpunkt / Anbieter (`totalCalls`, `totalDuration`). `_id` ist `unknown`, wenn kein Anbieter erfasst wurde.
`daily`	Array	Ein Eintrag pro Tag im Zeitraum (mit Nullwerten für Tage ohne Anrufe aufgefüllt).
`handoverWaitDistribution`	Objekt	Anzahl weitergeleiteter Anrufe, gruppiert danach, wie lange der Anrufer wartete, bis ein Mensch antwortete.
`dropOutWaitDistribution`	Objekt	Anzahl der Anrufe, bei denen der Anrufer während des Wartens abgebrochen hat, gruppiert nach Wartezeit.

Buckets der Verteilungen: 0_5s, 5_10s, 10_15s, 15_20s, 20_25s, 30s_plus. Alle Dauern sind in Sekunden angegeben.

Felder von `totals`

Feld	Beschreibung
`totalCalls` / `totalDuration` / `avgDuration`	Anzahl der Anrufe, summierte Dauer und durchschnittliche Dauer
`totalTimeWithBot` / `avgTimeWithBot`	Gesamte und durchschnittliche Zeit, die Anrufer mit dem Bot verbracht haben
`totalTimeWithHuman` / `avgTimeWithHuman`	Gesamte und durchschnittliche Zeit, die Anrufer mit einem menschlichen Agenten verbracht haben
`totalTtsDurationInS` / `totalSttDurationInS`	Summierte TTS-Audiodauer und STT-Inferenzzeit über alle Äußerungen
`totalTimeWaitingForHandover` / `avgHandoverWaitTime`	Gesamte und durchschnittliche Wartezeit der Anrufer auf die Übergabe
`forwardedCalls` / `successfulForwardedCalls`	Anrufe mit Übergabewartezeit und solche, die tatsächlich einen Menschen erreicht haben
`acceptedWithinServiceLevel20s`	Erfolgreiche Weiterleitungen, die innerhalb von 20 Sekunden angenommen wurden
`containmentRate`	Anteil der Anrufe, die der Bot vollständig bearbeitet hat (`assistant`-Auflegungen ÷ Gesamtanrufe)
`transferRate`	Anteil der Anrufe, die der Anrufer beendet hat (`user`-Auflegungen ÷ Gesamtanrufe)

Beispielanfrage (cURL)

curl -X GET "https://your-instance.com/api/bots/507f191e810c19729de860ea/phone-statistics?start=2026-07-01&end=2026-07-31" \
  -H "x-api-key: 507f1f77bcf86cd799439011.a3b2c1d4-e5f6-7890-abcd-ef1234567890"

Fehlerbehandlung

Status	Bedeutung
`403 Forbidden`	Fehlender/ungültiger API-Schlüssel, fehlender Read-Scope oder der Schlüssel hat nicht die Rolle Channel Manager (`Forbidden. Required roles: channel-manager`). Ein an einen Bot gebundener Schlüssel liefert ebenfalls 403, wenn `{botId}` nicht mit dem gebundenen Bot übereinstimmt.

Übersicht​

Anrufsteuerung​

hangup()​

forward_call()​

Wichtig: Asynchrones Verhalten​

Verwendung von forward_call() in Aktionsknoten​

Wie der Weiterleitungsknoten funktioniert​

transfer_call()​

forward_call() vs transfer_call()​

STT-Konfiguration​

update_stt_config()​

Wichtig: Anbieterkompatibilität​

BotarioSTTConfigUpdatePayload​

Hotword-Verstärkung​

Smart Turn und spekulative Transkription​

AzureSTTConfigUpdatePayload​

GoogleSTTConfigUpdatePayload​

TTS-Konfiguration​

update_tts_config()​

Wichtig: Anbieterkompatibilität​

AzureTTSConfigUpdatePayload​

GoogleTTSConfigUpdatePayload​

ElevenLabsTTSConfigUpdatePayload​

Aufnahme-Steuerung​

enable_recording()​

DTMF-Eingabe​

enable_dtmf()​

Umgebungsgeräusche​

enable_ambience_channel()​

disable_ambience_channel()​

Kontaktinformationen​

get_contact_info()​

save_contact_info()​

Telefonstatistik-API​

API-Endpunkt​

Anfrage-Header​

Abfrageparameter​

Antwort​

Felder von totals​

Beispielanfrage (cURL)​

Fehlerbehandlung​

Verwandte Dokumentation​

Übersicht

Anrufsteuerung

hangup()

forward_call()

Wichtig: Asynchrones Verhalten

Verwendung von forward_call() in Aktionsknoten

Wie der Weiterleitungsknoten funktioniert

transfer_call()

forward_call() vs transfer_call()

STT-Konfiguration

update_stt_config()

Wichtig: Anbieterkompatibilität

BotarioSTTConfigUpdatePayload

Hotword-Verstärkung

Smart Turn und spekulative Transkription

AzureSTTConfigUpdatePayload

GoogleSTTConfigUpdatePayload

TTS-Konfiguration

update_tts_config()

Wichtig: Anbieterkompatibilität

AzureTTSConfigUpdatePayload

GoogleTTSConfigUpdatePayload

ElevenLabsTTSConfigUpdatePayload

Aufnahme-Steuerung

enable_recording()

DTMF-Eingabe

enable_dtmf()

Umgebungsgeräusche

enable_ambience_channel()

disable_ambience_channel()

Kontaktinformationen

get_contact_info()

save_contact_info()

Telefonstatistik-API

API-Endpunkt

Anfrage-Header

Abfrageparameter

Antwort

Felder von `totals`

Beispielanfrage (cURL)

Fehlerbehandlung

Verwandte Dokumentation