Twilio Voice

Im Code

Deklariere die Verbindung in connectors/*.yaml. Das Deployment sucht phone_number unter den anruffähigen Rufnummern des Kontos, das der Kontozugang verbindet. Bei der Aktivierung wird der Agent verknüpft; er braucht in diesem Deployment voice_config. Setze jede Rufnummer in Anführungszeichen. Ohne sie liest YAML die Nummer als Ganzzahl und das Deployment scheitert.

type: twilio
connection: support-twilio
config:
  phone_number: "+4930123456"
  transfer_numbers:
    - "+4930123456789"
  allowed_callers:
    - "+4915112345678"
  fallback_number: "+4930987654321"
  max_wait_seconds: 60
  hold_audio_path: assets/hold.mp3
agents:
  - support-voice

Kontozugang

Ein Twilio-Kontozugang enthält die Zugangsdaten des Kontos und kann beliebig viele Verbindungen für Twilio Voice und Twilio Messaging im selben Konto und in derselben Region bedienen. Mit Account SID und Auth Token prüft connic das Konto, listet Rufnummern auf und setzt Webhooks. Mit dem Auth Token prüft connic außerdem die Signatur jeder Anfrage von Twilio.

Erzeugte Werte

connic erzeugt diesen Wert beim Anlegen der Verbindung und behält ihn bei Änderungen und Deployments. Er gehört nicht in YAML-Dateien; connic lint lehnt ihn ab.

Ausgehende Anrufe

Im Outbound-Modus ist jeder Run des verknüpften Agenten ein Anruf. Klicke im Connector Flow des Agenten auf Add outbound connector, wähle Twilio Voice und als Modus Outgoing calls. Die Runs startest du wie jeden anderen, etwa über einen Webhook-Connector oder aus einem anderen Agenten mit trigger_agent.

Sobald ein Run startet, ruft connic von der Nummer der Verbindung aus die Nummer im Feld to der Eingabe an, oder die voreingestellte Nummer der Verbindung, wenn die Eingabe keine enthält. Mit greeting spricht der Agent zuerst, sobald jemand abnimmt; ohne Begrüßung wartet er, bis sein Gegenüber spricht. Über den Anruf weiß er, was in der Eingabe des Runs steht. Durch Telefonmenüs kommt der Agent mit press_keys, und in einer Warteschleife kann er warten, bis sich jemand meldet. Runs über das max_concurrent_runs des Agenten hinaus warten, bevor connic wählt. So muss niemand, der abnimmt, auf den Agenten warten. Der Agent kann den Anruf wie einen eingehenden an eine Weiterleitungsnummer übergeben.

Der Run schlägt fehl, wenn innerhalb der Klingeldauer niemand abnimmt, besetzt ist oder der Anruf nicht zustande kommt. Die Fehlermeldung nennt den Grund. Nimmt eine Mailbox ab, hört der Agent ihre Ansage wie die einer Person. Schreib deshalb in den System-Prompt des Agenten, was er dann tun soll, etwa nach dem Signalton eine kurze Nachricht hinterlassen und auflegen.

type: twilio
mode: outbound
connection: support-twilio
config:
  phone_number: "+4930123456"
  ring_seconds: 40
agents:
  - reminder-calls

{
  "to": "+4915112345678",
  "customer": "Alex Beispiel",
  "reason": "Termin morgen um 10:00 bestätigen"
}

Erlaubte Anrufer

Mit erlaubten Anrufern weist connic Anrufe von allen anderen und von unterdrückten Nummern ab, bevor Twilio sie annimmt. Sie starten also keinen Run. Die Logs der Verbindung zeigen jeden abgewiesenen Anruf mit seiner Nummer. Anrufernummern lassen sich fälschen. Verlass dich zum Schutz sensibler Daten deshalb nicht allein auf diese Liste.

Wartende Anrufer

Jeder Anruf ist ein Run. Der Agent führt also so viele Anrufe gleichzeitig, wie max_concurrent_runs erlaubt. Alle weiteren Anrufer warten und kommen in der Reihenfolge an die Reihe, in der sie angerufen haben. Während sie warten, hören sie das Freizeichen oder die Warteschleifenmusik der Verbindung. Wer nach der maximalen Wartezeit noch wartet, landet bei der Ausweichnummer. Gibt es keine, endet der Anruf und sein Run schlägt fehl.

Fehlt die Datei für die Warteschleifenmusik oder lässt sie sich nicht abspielen, hören wartende Anrufer das Freizeichen, und die Logs der Verbindung nennen den Grund. Eine geänderte Datei hören Anrufer nach dem nächsten Deploy.

Weiterleitung und Ausweichnummer

Löst ein Tool des Agenten TransferCall mit einer der Weiterleitungsnummern der Verbindung aus, wählt Twilio diese Nummer. Meldet sich dort niemand, endet der Anruf. Kann ein angenommener eingehender Anruf nicht weiterlaufen, etwa weil der Run fehlschlägt oder der Anrufer die maximale Wartezeit erreicht hat, wählt Twilio stattdessen die Ausweichnummer. Ohne Ausweichnummer endet der Anruf. Die Ausweichnummer gilt nur im Sync-Modus und nicht für Weiterleitungen.

Anrufe, die connic nicht annimmt, etwa solange die Verbindung pausiert ist oder das Environment kein aktives Deployment hat, gehen an die Einstellung Primary handler fails der Rufnummer in Twilio. connic ändert sie nicht. Verweist sie auf TwiML, das eine Nummer von Mitarbeitenden wählt, werden auch diese Anrufe weitergeleitet.