Zum Hauptinhalt springen

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.

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

Parameter:

ParameterTypErforderlichStandardBeschreibung
forward_call_idstrJa-Telefonnummer, an die weitergeleitet werden soll
forward_call_ringingintNein15Sekunden, die vor dem Timeout klingeln sollen
sip_headersdictNeinKeineBenutzerdefinierte 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:

  1. Die Weiterleitungsanfrage wird an den PhoneServer gesendet
  2. Der PhoneServer initiiert den weitergeleiteten Anruf
  3. Der weitergeleitete Anruf wird abgeschlossen (angenommen, besetzt, keine Antwort usw.)
  4. 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:

  1. Das ForwardEvent an den PhoneServer sendet
  2. Ein RequestUserInputEvent auslöst, um auf die Antwort des PhoneServers zu warten
  3. 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:

StatusBeschreibung
ANSWERAnruf wurde erfolgreich angenommen
BUSYAngerufene Partei war besetzt
NOANSWERAngerufene Partei hat nicht geantwortet
CHANUNAVAILEndpunkt nicht erreichbar oder nicht registriert
CONGESTIONKanal-/Schaltüberlastung
CANCELAnruf vor der Annahme abgebrochen
DONTCALLAblehnung im Datenschutzmodus
TORTUREAblehnung im Datenschutzmodus (Folterskript)
INVALIDARGSUngü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:

ParameterTypErforderlichBeschreibung
update_payloadPayload-KlasseJaAnbieter-spezifische Konfigurationsnutzlast
provider_titlestrNeinWechseln zu einem anderen Anbieter nach dessen Titel

Wichtig: Anbieterkompatibilität

Der update_payload-Typ muss mit dem Anbietertyp übereinstimmen:

AnbietertypErforderliche Payload-Klasse
botarioBotarioSTTConfigUpdatePayload
AzureAzureSTTConfigUpdatePayload
GoogleGoogleSTTConfigUpdatePayload

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

ParameterTypStandardBeschreibung
hotwordsstr | NoneKeineKommagetrennte 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_alphafloat | None1.0Skalierungsfaktor, der steuert, wie aggressiv das System der Hotword-Liste im Vergleich zum akustischen Modell vertraut
hotword_context_scorefloat | None1.0Additiver 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.")

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:

ParameterTypErforderlichBeschreibung
update_payloadPayload-KlasseJaAnbieter-spezifische Konfigurationsnutzlast
provider_titlestrNeinWechseln zu einem anderen Anbieter nach dessen Titel

Wichtig: Anbieterkompatibilität

Der update_payload-Typ muss mit dem Anbietertyp übereinstimmen:

AnbietertypErforderliche Payload-Klasse
botarioBotarioTTSConfigUpdatePayload
AzureAzureTTSConfigUpdatePayload
GoogleGoogleTTSConfigUpdatePayload
ElevenLabsElevenLabsTTSConfigUpdatePayload

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 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:

ParameterTypErforderlichStandardBeschreibung
enableboolNeinTrueTrue, 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:

ParameterTypErforderlichStandardBeschreibung
termination_symbolstrNein"#"Das Symbol, das der Benutzer eingeben muss, um anzuzeigen, dass seine Eingabe abgeschlossen ist
single_digit_modeboolNeinFalseWenn True, wird nur eine einzelne Ziffer erwartet und kein Abschlusssymbol ist erforderlich. Die Eingabe wird automatisch nach einer Ziffer abgeschlossen
time_outfloatNeinKeineSekunden, 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:

ParameterTypErforderlichStandardBeschreibung
sound_namestrJa-Abzuspielender Umgebungsgeräusch
volumeintNein0Lautstärkeanpassung (-10 bis 20)

Verfügbare Geräusche:

GeräuschBeschreibung
tastaturTastaturtippen
copy_machineKopiergerät-/Druckergeräusche
officeAllgemeine Büroatmosphäre
background_musicWartemusik

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:

ParameterTypErforderlichBeschreibung
contact_infoContactInfo oder dictJaZu 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