Anhang B. Applikationen im Dialplan

Anhang B. Applikationen im Dialplan
Zurück		Weiter

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

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

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

Zurück		Weiter
2. Installation Asterisk 1.4.x auf Knoppix 5.1	Zum Anfang \| InhV	2. `ADSIProg()`

Asterisk Schulung

27.10. - 28.10.2008 in Koblenz

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

Asterisk-Tag.org 2008

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

Das Asterisk Buch von Stefan Wintermeyer