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
HangupEventim 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.
tracker_api.forward_call(
forward_call_id: str,
forward_call_ringing: int = 15,
sip_headers: dict | 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 |
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, nachdem die Weiterleitung abgeschlossen ist):
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 integrierte Weiterleitungsknoten behandelt dies automatisch, indem er:
- Das
ForwardEventan den PhoneServer sendet - Ein
RequestUserInputEventauslöst, um auf die Antwort des PhoneServers zu warten - Beim nächsten Gesprächswechsel (nachdem die Weiterleitung abgeschlossen ist) 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 der Annahme abgebrochen |
DONTCALL | Ablehnung im Datenschutzmodus |
TORTURE | Ablehnung im Datenschutzmodus (Folterskript) |
INVALIDARGS | Ungültige Syntax in der Weiterleitungsanfrage |
STT-Konfiguration
update_stt_config()
Aktualisiert die Konfiguration der Spracherkennung (Speech-to-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 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 |
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
ValueErrorausgelö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
ValueErrorausgelö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 zu einem Anbieter namens "My Azure STT"
tracker_api.update_stt_config(
AzureSTTConfigUpdatePayload(language_code="en-US"),
provider_title="My 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", # Kommagetrennte 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-Boosting
Hotword-Boosting 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 | Kommagetrennte 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_alphaundhotword_context_scorefunktionieren nur mittranscription_mode='alpha_num'. Die Verwendung mittranscription_mode='default'führt zu einemValueError.
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.")
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 der Text-to-Speech-Ausgabe 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 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 |
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
ValueErrorausgelö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
ValueErrorausgelö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 zu einem Anbieter namens "My ElevenLabs Voice"
tracker_api.update_tts_config(
ElevenLabsTTSConfigUpdatePayload(
voice="custom_voice_id",
stability=0.8
),
provider_title="My ElevenLabs Voice"
)
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 der Sprache für bessere Verständlichkeit
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 Bedarf" 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 Aufzeichnung 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. um Menüs zu navigieren, PINs einzugeben oder Optionen auszuwählen. Der DTMF-Modus wird nach der Benutzereingabe automatisch deaktiviert, sodass Sie ihn erneut aktivieren müssen, wenn Sie weitere Ziffern erfassen möchten. Während der DTMF-Eingabe ist die Spracherkennung deaktiviert - Benutzer müssen nur ihre Tastatur verwenden.
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 mit unbegrenzter Ziffernlänge und ohne 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 | - | Abzuspielender Umgebungsgeräusch |
volume | int | Nein | 0 | Lautstärkeanpassung (-10 bis 20) |
Verfügbare Geräusche:
| Geräusch | Beschreibung |
|---|---|
tastatur | Tastaturtippen |
copy_machine | Kopiergerät-/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 bleiben Sie in der Leitung, während ich das überprüfe.")
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, dass Sie gewartet haben. Ich habe Ihre Informationen gefunden.")
Beispiel - Büroatmosphäre:
async def create_office_feel(tracker_api: RemoteLLMTrackerApi):
# Erstellen Sie Hintergrundgeräusche für eine menschlichere Atmosphäre
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 verknüpft 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="Customer",
meta="Registriert am 2024-01-15"
)
)
Verwandte Dokumentation
- Spracherkennungskonfiguration - UI-Konfiguration für STT
- Text-to-Speech-Konfiguration - UI-Konfiguration für TTS
- Telefonereignisse - Ereignisflusskonfiguration
- Ausgehende Anrufe - API zum Initiieren von Anrufen
- Skripte - Benutzerdefinierte Skripte und Aktionen