Die NFON Portal-API muss man verstehen um Sie zu nutzen. Leider ist die API-Dokumentation nicht so detailliert und oft muss man testen, wo und wie sich ein API-Request auswirkt. Am Beispiel der Rufumleitung (en: Call Forwarding) möchte ich euch die Nutzung der Portal-API erläutern.
Die fünf wichtigsten Optionen:
- Rufumleitunfgs-Profil
- Rufumleitung immer (default)
- Rufumleitung bei besetzt (busy)
- Rufumleitung nach Zeit (no answer)
- Rufumleitung wenn kein Endgerät registriert ist (not registered)
Der Nutzer kann jederzeit alle Optionen der Rufumleitung selbst einstellen. Der NFON-Administrator kann zwar Einstellungen vorgeben, aber der Nutzer kann jederzeit über dias IP-Phone, über Funktionscodes oder über die Cloudya App Suite alle Einstellungen ändern. Fehlbedienungen sind also vorprogrammiert, z.B.:
- Rufumleitung zu falschen Zielen oder Rufnummern
- Keine “Offline-Rufumleitung” falls kein Endgerät registriert ist
- Rufumleitungen im Kreis
Inhaltsverzeichnis
Profil
Die Rufumleitungsprofile sind sinnvoll für bestimmte Situationen, z.B. Besprechung, Homeoffice, Urlaub… Der Nutzer kann jederzeit neue Rufumleitungsprofile anlegen und aktivieren. Der NFON-Admin kann zwar den Nutzer unterstützen, hat aber die keinen Einfluß auf die Profile.
Als Programmierer muss man also zunächst das aktive (Rufumleitungs-) Pofil ermitteln um im nächsten Schritt die gewünschten Änderungen vornehmen.
Die folgenden Codes nutze ich in apihelper.de und nutze eine vereinfachte Schreibweise der typischen json-Baumstruktur mit folgenden Akbürzungen:
- Kxxxx = ID der NFON-Anlage (Kundennummer, K‑Anlage)
- nnn = ID der Nebenstelle (interne Rufnummer, Extension)
- p = Rufumleitungsprofil (0–9)
Der Code enthält den API-Request und die Antwort der Portal-API
GET-Request:
href = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles
Response:
items.0.href = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles/0
items.0.data.active = true
items.0.data.immutable = true
items.1.href = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles/1
items.1.data.active = false
items.1.data.immutable = falseErläuterung: Nebenstelle nnn der K‑Anlage Kxxxx nutzt zwei Rufumleitungsprofile (0, 1) wobei Profil 0 aktiv ist. Profil 0 ist nicht löschbar (en: immutable), da es das Standardprofil ist.
Wenn der Nutzer das optionale (löschbare) Profil 1 aktiviert, sieht die Antwort etwas anders aus:
GET-Request:
href = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles
Response:
items.0.href = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles/0
items.0.data.active = false
items.0.data.immutable true
items.1.href = api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles/1
items.1.data.active = true
items.1.data.immutable = false Erläuterung: Nebenstelle nnn der K‑Anlage Kxxxx nutzt zwei Rufumleitungsprofile (0, 1) wobei das optionale Profil 1 aktiv ist.
Default
Alle Anrufe werden umgeleitet. Details folgen…
Busy
Rufumleitung bei besetzt. sofern die Option “Anklopfen” (en: Busy-on-Busy) nicht aktiviert wurde. Details folgen…
No Answer
Rufumleitung nach Zeit, wenn der Anruf z.B. nach 20 Sekunden nicht beantwortet wurde. Details folgen…
Not Registered
Rufumleitung, wenn an der Nebenstelle kein Endgerät (IP-Phone, a/b‑Adapter, 3rd-Party SIP-Device oder Cloudya App Suite) registriert bzw. angemeldet ist.
Man kann diese Option aktivieren oder deaktivieren. Wenn diese Option deaktiviert und kein Endgerät registriert ist, dann kann die NFON Cloud-Telefonanlage den Anruf nicht “zustellen”. Es “klingelt” kein Endgerät und der Anrufer hört u.U. kein Rufzeichen (engl.: Ringback Tone, RBT). Das ist für den Anrufer irritierend. Es ist also sinnvoll, diese Option zu aktivieren.
Nachdem man über die API das aktive (Rufumleitungs-) Profil (p) ermittelt hat, kann man die Einstellungen zu den vier (Rufumleitungs-) Optionen auslesen oder setzen. Für die Option “Nicht registriert” muss das Flag “notRegisteredCallForwardActive” aktiv (=true) sein:
GET-Request:
href = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles/p/rules Response:
items.0.links.notRegisteredCallForward = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles/p/rules/ANY/NOT_REGISTERED
items.0.data.notRegisteredCallForwardActive = trueDetails zum (Rufumleitungs-) Ziel muss man über einen weiteren Request auslesen. Das folgende Beispiel zeigt die Rufumleitung auf die VM-Box von Nebenstelle 25 (Weber, W.):
GET-Request:
href = /api/customers/Kxxxx/targets/phone-extensions/nnn/callforward-profiles/p/rules/ANY/NOT_REGISTERED
Response:
data.name = "Weber, W."
data.type = "VOICEMAIL"
data.extensionNumber = "25"