Anhang B. Applikationen im Dialplan

Im Folgenden werden die Applikationen beschrieben, die im Dialplan (also in der /etc/asterisk/extensions.conf) verwendet werden können. Beachten Sie bitte, dass nur solche Applikationen in Ihrer Installation verfügbar sind, die in der /etc/asterisk/modules.conf im Abschnitt [modules] durch autoload=yes oder explizites load => app_applikationsname.so geladen wurden. Eine Liste aller in Ihrem Asterisk verfügbaren Applikationen können Sie mit dem CLI Befehl core show applications abrufen. Genaue Informationen zu einer bestimmten Applikation können Sie im CLI mit dem Befehl core application Applikationsname anzeigen.

[Tipp]Tipp

Die Befehle core application xyz und core applications existieren erst in der Asterisk Version 1.4. Sollten Sie ein Asterisk 1.2 betreuen, können Sie die gleichen Funktionen mit den Befehlen show application xyz und show applications abrufen. Die alten Befehle funktionen auch noch in der Version 1.4, sind aber deprecated.

Der Begriff „Applikationen“ (oder „Befehle“) darf nicht mit „Funktionen“ verwechselt werden, die ggf. innerhalb eines Befehlsaufrufs stehen. „Applikationen“ (applications) ist vielleicht irreführend, aber der gängige Ausdruck.

[Anmerkung]Anmerkung

Ein Hinweis am Rande: Die Konfigurationsdateien von Asterisk verwenden leider ein recht schwammiges Format (als INI bekannt), für das nie eine offizielle Grammatik veröffentlicht wurde. Der Parser geht auch nicht den üblichen Weg von lexikalischer Analyse, Tokenizing und syntaktischer Analyse. Aus diesem Grund steigt übrigens der Asterisk-Ableger OpenPBX auf die von Mac OS X bekannten, aber auch auf anderen Plattformen verfügbaren „Property Lists“ (.plist) als Format für Konfigurationsdateien um.

Hier sei nur gesagt, dass es aufgrund mangelnder Spezifikation nicht immer klar ist, an welcher Stelle z.B. Leerzeichen erlaubt sind oder wo Anführungszeichen erwartet werden. Meist werden mehrere Schreibweisen erkannt. Im Zweifelsfall hilft nur Ausprobieren, wenn eine Schreibweise in Ihrer Asterisk-Version nicht funktioniert. Sollten Sie Fehler entdecken, wird um Rückmeldung gebeten.

Es ist oft möglich, Parameter auszulassen. Wenn ausgelassene Parameter nicht am Ende stehen, müssen Sie trotzdem ein Komma angeben, um anzuzeigen, dass der Parameter leer ist (also der Default-Wert verwendet wird), z.B. so:

exten => s,1,Dial(IAX2/User:Passwort@beispiel.de/123,,tT)

Im Allgemeinen kann gesagt werden, dass Fehler beim Ausführen einer Applikation durch den Rückgabewert -1 ausgedrückt werden, Erfolg durch 0. Ein Rückgabewert von -1 bedeutet, dass Asterisk den Kanal auflegt und nicht weiter den Dialplan abarbeitet.

[Wichtig]Wichtig

Bitte beachten Sie, dass, abhängig von der eingesetzten Asterisk-Version die Parameter durch , (Komma) oder | (Pipe) getrennt werden. In diesem Buch wird hauptsächlich das , (Komma) benutzt.

Wer Asterisk schon länger kennt, wird sich vielleicht wundern, warum hier die eine oder andere Applikation nicht aufgeführt ist. Das hat den einfachen Grund, dass bereits in Asterisk 1.2 etliche Applikationen als „deprecated“ (= veraltet, soll nicht mehr verwendet werden) gekennzeichnet sind und in 1.4 nicht mehr existieren. Solche Befehle werden hier nicht mehr beschrieben, Sie finden die entsprechenden Funktionen in Anhang C, Funktionen im Dialplan. Die beigefügten Diffs der internen Hilfetexte sind immer vom neueren 1.4 zum älteren 1.2.

In den Beispielen wird oft die willkürlich gewählte Extension 123 und die Priorität 1 verwendet, was in der Praxis natürlich nicht immer sinnvoll ist.

Viele Applikationen vor Asterisk 1.2 sprangen bei einem Fehler zur Priorität n+101, wenn vorhanden (wobei n die aktuelle Priorität bezeichnet). Dieses alte Verhalten („priority jumping“) lässt sich bei einigen Befehlen durch die Option j (jump) erreichen oder indem man in der extensions.conf im Abschnitt [general] den Parameter priorityjumping=yes setzt. Dieses Verhalten ist aber „deprecated“. Die neuere Methode ist das Abfragen der gesetzten Channelvariablen.

Um eine leichtere Verwendung als Nachschlagewerk zu ermöglichen, sind die Applikationen in alphabetischer Reihenfolge aufgeführt. Da sie sich aber auch sinnvoll gruppieren lassen, finden Sie hier einen entsprechenden Index:

Anruf-Verwaltung (abheben, durchstellen, auflegen, ...)

Abschnitt 9, „Answer() - Abheben
Abschnitt 14, „Busy() - Besetztzeichen signalisieren
Abschnitt 17, „ChanIsAvail() - Prüfen, ob ein Channel verfügbar ist
Abschnitt 18, „ChannelRedirect() - Kanal auf eine andere Extension umleiten
Abschnitt 20, „Congestion() - Stau signalisieren
Abschnitt 27, „Dial() - Einen Anruf durchstellen / mit einem Channel verbinden
Abschnitt 30, „DISA() - DISA (Direct Inward System Access)
Abschnitt 44, „FollowMe() - „Folge-Mir“-Funktionalität
Abschnitt 52, „Hangup() - Auflegen
Abschnitt 75, „Page() - Rundruf
Abschnitt 76, „Park() - Gespräch parken
Abschnitt 83, „Pickup() - Heranholen eines Anrufs
Abschnitt 98, „RetryDial() - Dial() mit „Wahlwiederholung
Abschnitt 100, „Ringing() - Klingeln signalisieren

Flusskontrolle und Timeouts

Abschnitt 21, „ContinueWhile() - Zum Anfang einer While-Schleife springen
Abschnitt 34, „EndWhile() - Ende einer While-Schleife
Abschnitt 35, „Exec() - Ausführen einer Applikation
Abschnitt 36, „ExecIf() - Bedingtes Ausführen einer Applikation
Abschnitt 37, „ExecIfTime() - Zeitabhängiges Ausführen einer Applikation
Abschnitt 38, „ExitWhile() - Eine While-Schleife abbrechen
Abschnitt 47, „Gosub() - Zu einer Unterroutine springen
Abschnitt 48, „GosubIf() - Bedingtes Gosub()
Abschnitt 49, „Goto() - Zu einer Priorität, Extension oder anderem Context springen
Abschnitt 50, „GotoIf() - Bedingtes Goto()
Abschnitt 51, „GotoIfTime() - Bedingtes Gosub() je nach Datum/Uhrzeit
Abschnitt 90, „Random() - Zufällig im Dial-Plan springen
Abschnitt 99, „Return() - Aus einem Gosub() oder GosubIf() zurückkehren
Abschnitt 125, „TryExec() - Versuch der Ausführung einer Applikation
Abschnitt 139, „While() - Anfang einer While-Schleife

Macros

Abschnitt 58, „Macro() - Macro aufrufen
Abschnitt 59, „MacroExclusive() - Macro zu einem Zeitpunkt nur einmal aufrufen
Abschnitt 60, „MacroExit() - Macro abbrechen
Abschnitt 61, „MacroIf() - Ein Macro bedingt ausführen

Anrufer-Kennung (Caller-ID, Name, ...)

Abschnitt 15, „CallingPres() - „Caller Presentation“ verändern
Abschnitt 56, „LookupBlacklist() - Caller-ID in Blacklist nachschlagen
Abschnitt 57, „LookupCIDName() - Caller-ID-Name in Datenbank nachschlagen
Abschnitt 86, „PrivacyManager() - Eingabe einer Telefonnummer verlangen falls ohne Caller-ID
Abschnitt 112, „SetCallerPres() - Caller-ID setzen, unanhängig vom Channel
Abschnitt 120, „SoftHangup() - Auflegen verlangen
Abschnitt 140, „Zapateller() - Werbeanrufe blockieren

Gesprächsprotokolle (CDRs)

Abschnitt 10, „AppendCDRUserField() - Einen Wert an das CDR-User-Feld anhängen
Abschnitt 45, „ForkCDR() - Den CDR in zwei getrennte Einträge aufspalten
Abschnitt 73, „NoCDR() - CDR für diesen Anruf deaktivieren
Abschnitt 97, „ResetCDR() - CDR-Eintrag zurücksetzen
Abschnitt 111, „SetAMAFlags() - AMA-Flags setzen
Abschnitt 113, „SetCDRUserField() - CDR-User-Feld setzen

Voicemail

Abschnitt 29, „Directory() - Dial-by-Name-Telefonbuch anbieten
Abschnitt 62, „MailboxExists() - Prüft, ob Mailbox existiert
Abschnitt 132, „VoiceMail() - Anrufbeantworter
Abschnitt 133, „VoiceMailMain() - Anrufbeantworter abhören
Abschnitt 131, „VMAuthenticate() - User anhand der voicemail.conf authentifizieren

Konferenzen

Abschnitt 63, „MeetMe() - MeetMe-Konferenz
Abschnitt 64, „MeetMeAdmin() - MeetMe-Konferenz verwalten
Abschnitt 65, „MeetMeCount() - Anzahl der Teilnehmer einer MeetMe-Konferenz

Variablen verändern

Abschnitt 54, „ImportVar() - Variable von einem Channel importieren
Abschnitt 91, „Read() - Eine Variable (Ziffern) vom User einlesen
Abschnitt 92, „ReadFile() - Eine Datei in eine Variable einlesen
Abschnitt 93, „RealTime() - Variablen aus dem Realtime-System einlesen
Abschnitt 94, „RealTimeUpdate() - Variablen im Realtime-System verändern
Abschnitt 110, „Set() - Eine Channel-Variable setzen
Abschnitt 114, „SetGlobalVar() - Eine globale Variable setzen

Musik-/Sprachausgabe

Abschnitt 12, „Background() - Im Hintergrund eine Sound-Datei spielen
Abschnitt 13, „BackgroundDetect() - Background() mit Spracherkennung
Abschnitt 22, „ControlPlayback() - Playback() mit Vor-/Zurückspulen und Abbrechen
Abschnitt 23, „DateTime() - Datum/Uhrzeit ansagen
Abschnitt 33, „Echo() - Audio-Eingabe wiedergeben
Abschnitt 42, „Festival() - Text mit dem Festival-Synthesizer sprechen
Abschnitt 66, „Milliwatt() - Einen konstanten 1000-Hz-Ton mit 0 dbm erzeugen
Abschnitt 70, „MP3Player() - MP3-Datei oder -Stream spielen
Abschnitt 71, „MusicOnHold() - Wartemusik spielen
Abschnitt 72, „NBScat() - NBS-Stream abspielen
Abschnitt 84, „Playback() - Eine Sound-Datei spielen
Abschnitt 85, „Playtones() - Töne spielen
Abschnitt 87, „Progress() - Audio vor dem Abheben spielen
Abschnitt 101, „SayAlpha() - Buchstabieren (alphanumerisch)
Abschnitt 102, „SayDigits() - Ziffern ansagen
Abschnitt 103, „SayNumber() - Nummer ansagen
Abschnitt 104, „SayPhonetic() - Buchstabieren
Abschnitt 105, „SayUnixTime() - Datum/Uhrzeit ansagen
Abschnitt 115, „SetMusicOnHold() - Wartemusik festlegen
Abschnitt 122, „StopPlaytones() - Playtones() beenden

Aufzeichnen

Abschnitt 5, „AgentMonitorOutgoing() - Ausgehende Anrufe eines Agenten aufzeichnen
Abschnitt 16, „ChangeMonitor() - Die Datei für Monitor() verändern
Abschnitt 19, „ChanSpy() - Ein Gespräch mithören
Abschnitt 27, „Dial() - Mit der Option w oder W im Gespräch aufzeichnen
Abschnitt 28, „Dictate() - Diktat aufnehmen und wiedergeben
Abschnitt 39, „ExtenSpy() - Ein Gespräch mithören
Abschnitt 67, „MixMonitor() - Ähnlich Monitor(), aber nur eine Datei
Abschnitt 68, „Monitor() - Ein Gespräch mitschneiden
Abschnitt 79, „PauseMonitor() - Mitschneiden pausieren
Abschnitt 95, „Record() - Eingehendes Audio mitschneiden
Abschnitt 121, „StopMonitor() - Monitor() beenden
Abschnitt 127, „UnpauseMonitor() - Pausierung des Mitschnitts aufheben
Abschnitt 141, „ZapBarge() - Einen ZAP-Channel belauschen
Abschnitt 143, „ZapScan() - Zwecks Mithören durch ZAP-Kanäle schalten

Datenbank-Zugriffe

Abschnitt 24, „DBdel() - Einen Datenbankeintrag löschen
Abschnitt 25, „DBdeltree() - Einen Datenbank-Zweig löschen

Allgemeines

Abschnitt 11, „Authenticate() - Einen User authentifizieren
Abschnitt 106, „SendDTMF() - DTMF-Töne senden
Abschnitt 107, „SendImage() - Ein Bild senden
Abschnitt 108, „SendText() - Einen Text senden
Abschnitt 109, „SendURL() - Eine URL senden
Abschnitt 124, „Transfer() - Anruf weiterleiten
Abschnitt 131, „VMAuthenticate() - User anhand der voicemail.conf authentifizieren
Abschnitt 134, „Wait() - Eine bestimmte Zeit warten
Abschnitt 135, „WaitExten() - Auf Eingabe einer Extension warten
Abschnitt 136, „WaitForRing() - Auf Klingeln warten
Abschnitt 137, „WaitForSilence() - Auf Stille warten
Abschnitt 138, „WaitMusicOnHold() - Warten mit Musik

Externe Skripte

Abschnitt 6, „AGI() - Eine AGI-Anwendung ausführen
Abschnitt 26, „DeadAGI() - AGI() auf einem aufgelegten Channel
Abschnitt 31, „DumpChan() - Informationen über einen Kanal auf dem CLI ausgeben
Abschnitt 32, „EAGI() - Siehe AGI()
Abschnitt 40, „ExternalIVR() - Einen externen IVR-Generator ausführen
Abschnitt 41, „FastAGI() - AGI() auf einem entfernten Rechner
Abschnitt 55, „Log() - Eine Nachricht in einem bestimmten Verbosity-Level loggen
Abschnitt 58, „Macro() - Ein Makro ausführen
Abschnitt 74, „NoOp() - Nichts tun. Schreibt Debugging-Informationen
Abschnitt 81, „Perl() - res_perl ist wie mod_perl für Apache, aber für Asterisk
Abschnitt 82, „PHP() - res_php ist wie mod_php für Apache, aber für Asterisk
Abschnitt 91, „Read() - Eine Variable (Ziffern) vom User einlesen
Abschnitt 123, „System() - Einen Shell-Befehl ausführen
Abschnitt 126, „TrySystem() - Wie System(), gibt aber immer 0 zurück
Abschnitt 129, „UserEvent() - Dem Manager-Interface ein Event schicken
Abschnitt 130, „Verbose() - Eine Nachricht in einem bestimmten Verbosity-Level loggen

SIP

Abschnitt 118, „SIPdtmfMode() - DTMF-Modus während SIP-Verbindung ändern
Abschnitt 117, „SIPAddHeader() - Einem ausgehenden Anruf einen SIP-Header hinzufügen

ZAP

Abschnitt 43, „Flash() - Einen Switchhook-Flash auf einem ZAP-Trunk senden
Abschnitt 141, „ZapBarge() - Einen ZAP-Channel belauschen
Abschnitt 142, „ZapRAS() - RAS (Remote Access Server) auf einem ZAP-ISDN-Channel bereitstellen
Abschnitt 143, „ZapScan() - Zwecks Mithören durch ZAP-Kanäle schalten

Warteschlangen, Call-Center

Abschnitt 1, „AddQueueMember() - Interface dynamisch in Warteschleife einreihen
Abschnitt 3, „AgentCallbackLogin() - Call-Center-Agenten einloggen (mit Rückruf)
Abschnitt 4, „AgentLogin() - Call-Center-Agenten einloggen
Abschnitt 5, „AgentMonitorOutgoing() - Ausgehende Anrufe eines Agenten aufzeichen
Abschnitt 77, „ParkAndAnnounce() - Anruf parken und ankündigen
Abschnitt 78, „ParkedCall() - Einen geparkten Anruf annehmen
Abschnitt 80, „PauseQueueMember() - Einen Agenten pausieren
Abschnitt 88, „Queue() - Eingehenden Anruf in Warteschleife einreihen
Abschnitt 89, „QueueLog() - Beliebigen Eintrag im Queue-Log schreiben
Abschnitt 96, „RemoveQueueMember() - Interface aus Warteschleife entfernen
Abschnitt 128, „UnpauseQueueMember() - Einen pausierenden Agenten wieder aktivieren

ADSI

Abschnitt 2, „ADSIProg() - Ein ADSI-Skript in ein Telefon laden
Abschnitt 46, „GetCPEID() - ADSI-CPE-ID abfragen

Verschiedenes

Abschnitt 8, „AMD() - Einen Anrufbeantworter erkennen
Abschnitt 7, „AlarmReceiver() - Einen Contact-ID-Alarm-Empfänger von Ademco emulieren
Abschnitt 53, „IAX2Provision() - Versorgt ein IAXy
Abschnitt 69, „Morsecode() - Sendet einen Text als Morsezeichen
Abschnitt 116, „SetTransferCapability() - ISDN-Transfer-Capability setzen
Abschnitt 119, „SMS() - Sendet oder empfängt SMS-Nachrichten

1. AddQueueMember()

Reiht Interfaces dynamisch in eine Anruf-Warteschleife ein.

AddQueueMember(Warteschleife[,Interface[,Malus[|,Optionen]]])

Reiht das angegebene Interface dynamisch als Agent in eine vorhandene Warteschleife (Queue) ein, die in queues.conf definiert wurde. Die Malus-Punkte beeinflussen ggf. die Position bei der Abarbeitung. Agenten mit niedrigerem Malus werden vor Einträgen mit höherem Malus aufgerufen.

Falls das angegebene Interface bereits in die Warteschlange eingereiht ist und eine n+101 Priorität existiert (n ist die aktuelle Priorität), wird die Abarbeitung bei dieser Priorität fortgesetzt, andernfalls wird ein Fehler (d.h. -1) zurückgeliefert. (Je nach Asterisk-Version muss für das Springen zu n+101 die Option j (jump) angegeben werden.)

Wird AddQueueMember() ohne den Interface-Parameter aufgerufen, findet das vom Teilnehmer zu diesem Zeitpunkt benutzte Interface Verwendung.

In manchen Asterisk-Versionen kann man statt der Pipe-Zeichen (|) auch Kommas verwenden.

Die Applikation setzt auch die Channelvariable ${AQMSTATUS} auf ADDED (hinzugefügt), MEMBERALREADY (ist bereits Mitglied) oder NOSUCHQUEUE (Warteschlange nicht vorhanden).

; SIP/3000 zur "supportschlange" hinzufügen:
exten => 123,1,AddQueueMember(supportschlange,SIP/3000)

; das aktuelle Interface mit Malus 2 hinzufügen:
exten => 123,1,AddQueueMember(supportschlange,,2)
[Anmerkung]Anmerkung

Interner Hilfetext zu dieser Applikation in Asterisk 1.4: 

  -= Info about application 'AddQueueMember' =- 

[Synopsis]
Dynamically adds queue members

[Description]
   AddQueueMember(queuename[|interface[|penalty[|options]]]):
Dynamically adds interface to an existing queue.
If the interface is already in the queue and there exists an n+101 priority
then it will then jump to this priority.  Otherwise it will return an error
The option string may contain zero or more of the following characters:
       'j' -- jump to +101 priority when appropriate.
  This application sets the following channel variable upon completion:
     AQMSTATUS    The status of the attempt to add a queue member as a 
                     text string, one of
           ADDED | MEMBERALREADY | NOSUCHQUEUE 
Example: AddQueueMember(techsupport|SIP/3000)

Differenz zum internen Hilfetext in Asterisk 1.2: 

- keine -

Siehe auch. Abschnitt 88, „Queue(), Abschnitt 96, „RemoveQueueMember(), queues.conf


Asterisk Schulung

2.1 Beta-Version!

2.1 Beta-Version des Asterisk Buches. Die 1.0 stabile Version ist ebenfalls online. Bitte melden Sie Fehler und Feedback per E-Mail an den Autor.

YouTube Screencasts

Kostenlose Asterisk Screencasts mit jeweils 10 minütigen Erklärungen zu Spezial-Themen.

Shameless Plug

noch-ne-auto-seite.de

Das gedruckte Buch

Werbung

Asterisk-Tag.org 2008

Auf der Asterisk-Tag.org Webseite finden Sie die Folien und Videos der Vorträge.