Daktela V6 API: Entwicklung einer eigenen Agentenoberfläche¶

Mit der Daktela V6 API (Application Programming Interface) können Sie Funktionen des Daktela-Systems in Ihre App oder Ihr Widget integrieren. Die Daktela V6 API nutzt den REST-Standard und kommuniziert über die HTTP-Methode. Die Daten werden im JSON- oder JSONP-Format serialisiert (mehr dazu in unserer API-Dokumentation). In diesem Handbuch wird die JSON-Serialisierung verwendet.

Zugriffstoken¶

Um über die Daktela V6 API zu kommunizieren, benötigen Sie zunächst ein Zugriffstoken (Zeichenkette), das die Benutzeranfrage autorisiert. Sie finden das Zugriffstoken in den Benutzerdetails. Alternativ können Sie es beim Anmelden über eine API-Anfrage ermitteln (siehe unten). Das Zugriffstoken ist ein obligatorischer Bestandteil aller Anfragen (außer beim Anmelden) und muss folgendes Format haben: /api/v6/endpoint?accessToken={MY_ACCESS_TOKEN}Eine Anfrage ohne gültiges Zugriffstoken liefert die Antwort 401 Unauthorized zurück.

Pull Data¶

Über den Endpunkt /api/v6/appPullData können Sie mittels Long Polling beliebige Ereignisse erkennen. Neben den Daten enthält die Antwort auch das Attribut hash, das den aktuellen Zustand des Benutzers identifiziert. Die erste Anfrage wird mit leerem Attribut hash gesendet. Der Server gibt sofort alle Daten sowie den hash zurück. Damit das Long Polling korrekt funktioniert, muss jede weitere Anfrage den hash enthalten, der in der Antwort auf die vorherige Pull-Data-Anfrage zurückgegeben wurde. Tritt ein Ereignis ein, sendet der Server sofort erneut eine Antwort, die sowohl den hash als auch die Daten des jeweiligen Ereignisses enthält. Tritt kein Ereignis ein, sendet der Server nach 15 Sekunden eine Antwort, die nur den hash enthält (er muss erneut in der nächsten Pull-Data-Anfrage enthalten sein). Pull Data ist ein integraler Bestandteil der Echtzeitanwendung – es erkennt Aktivitäten und deren Ereignisse (z. B. eingehende Anrufe), Änderungen des Gerätezustands, Beginn und Ende von Pausen, An- und Abmeldungen bei Warteschlangen, Benachrichtigungen usw.

Info

Die Pull-Data-Antwort enthält nur nach der ersten Anfrage mit leerem Attribut hash sämtliche Daten. Alle weiteren Anfragen mit gültigem Hash liefern nur die Daten (JSON-Schlüssel und ihre Werte – Objekte oder Arrays) zurück, bei denen Änderungen aufgetreten sind. Das folgende Diagramm beschreibt ein Ereignis, bei dem ein eingehender Anruf zu klingeln beginnt. Die Pull-Data-Antwort enthält nur die Schlüssel activities (die eingehende Aktivität) und extension (Informationen über den aktuell angemeldeten Benutzer und seinen Zustand).

Bild Die Struktur von Pull Data ist wie folgt:

activities – offene/wartende Aktivitäten,
extension – Informationen über den Benutzer und seinen Zustand,
queues – die Warteschlangen, bei denen der Benutzer angemeldet ist,
missedChannels – die Anzahl der verpassten Aktivitäten,
announcements – Benachrichtigungen,
reloadUser – ein Schalter, der signalisiert, dass die statischen WhoIm-Daten neu geladen werden müssen (siehe unten).

WhoIm¶

Der Endpunkt /api/v6/whoim gibt statische Daten über den aktuell angemeldeten Benutzer zurück (gemäß dem Zugriffstoken). Die Anfragen erfolgen über die HTTP-Methode GET. Ist das Zugriffstoken ungültig, gibt der Endpunkt nur Informationen über die aktuelle Version des Daktela-V6-Systems zurück. WhoIm-Struktur:

user – der aktuell angemeldete Benutzer,
queues – die Warteschlangen, für die der Benutzer Rechte hat,
pauses – die Pausen, bei denen sich der Benutzer anmelden darf.

An- und Abmelden¶

Der Endpunkt /api/v6/login dient zum Anmelden. Es ist der einzige Endpunkt, der kein Zugriffstoken erfordert. Eine Anmeldung über die API mit OAuth von Drittanbietern (z. B. Google) ist derzeit nicht möglich. Zum Anmelden muss eine HTTP-POST-Anfrage an den Endpunkt mit folgender Nutzlast gesendet werden: {“username”: “testuser123”, “password”: “SecretPassword”}Username (Zeichenkette) enthält die Kennung (name) des Benutzers, password (Zeichenkette) enthält das Passwort. Das Zugriffstoken des Benutzers ist Teil der Antwort und kann je nach den verwendeten Parametern weitere Daten enthalten. Wenn Sie das Attribut only_token (boolean) mit dem Wert true zur Nutzlast hinzufügen, gibt die API nur das Zugriffstoken zurück und es wird kein Cookie gesetzt. Nach erfolgreicher Anmeldung wird empfohlen, das Long Polling zum Pull-Data-Endpunkt zu starten, über den Sie auf alle wichtigen Daten zugreifen können. Zum Abmelden senden Sie eine HTTP-GET-Anfrage an den Endpunkt /api/v6/logout.

Bereit melden / Nicht bereit melden¶

Sofern der Benutzer die statische Anmeldung nicht aktiviert hat, muss er sich nach dem Anmelden bereit melden (in den Zustand Idle wechseln). Diese Information ist im Attribut state (Zeichenkette) des Objekts extension in Pull Data enthalten. Gilt state = Session, ist ein Bereitmelden erforderlich. Der Endpunkt /api/v6/usersSession dient zum Bereitmelden. Senden Sie eine HTTP-POST-Anfrage mit der Nutzlast {“setReady”:``true``}Die Antwort gibt 200 OK zurück. Ist das Gerät des Benutzers dynamisch, müssen Sie außerdem die Nummer (name) des Geräts senden, mit dem sich der Benutzer verbinden möchte. Z. B. {“setReady”:``true``, “extension”: “``305``”, model:``"sipDevices"``}``oder``{“setReady”:``true``, “extension”: “``721322422``”, model:``"externalNumbers"``} Der folgende Endpunkt gibt eine Liste der verfügbaren Geräte zurück: /api/v6/getAvailableExtensions?onlyCC=``trueUm sich nicht bereit zu melden (in den Zustand Session zu wechseln), senden Sie erneut eine HTTP-POST-Anfrage an den Endpunkt /api/v6/usersSession, diesmal mit der Nutzlast {“setReady”:``false``}Beispiele aus der Daktela-Web-App:

state = Session

Bild - state = Idle

Bild

Gerät hinzufügen/entfernen¶

Um ein Gerät hinzuzufügen oder zu entfernen, verwenden Sie den Endpunkt /api/v6/usersSession. Eine HTTP-POST-Anfrage mit der Nutzlast {“extension”: “``310``”}meldet den Benutzer beim Gerät 310 an. Eine HTTP-POST-Anfrage mit der Nutzlast {“extension”: {“name”: “``310``”, “logout”:``true``}meldet den Benutzer vom selben Gerät ab.

Pause beginnen und beenden¶

Wenn state (Zeichenkette) im Objekt extension in Pull Data auf den Wert Paused gesetzt ist, befindet sich der Benutzer in einer Pause. Ist dies der Fall, werden im Objekt extension in Pull Data auch die Attribute id_pause (object? – die Pause, in der er sich befindet) und on_pause (datetime? – das Datum und die Uhrzeit, zu der die Pause begonnen wurde) gesetzt. Befindet sich der Benutzer nicht in einer Pause, sind diese Attribute null. Sie können eine Pause über eine HTTP-POST-Anfrage an den Endpunkt /api/v6/usersSession mit der Nutzlast beginnen {“pause”: “mypause”}wobei "mypause" die Kennung (name) der Pause ist. Eine Pause können Sie auf ähnliche Weise beenden. Passen Sie die Nutzlast einfach an zu {“pause”:``null``} Beispiele aus der Daktela-Web-App:

state = Idle

Bild - state = Paused

Bild

Gerät aktiv/inaktiv¶

Ob der Benutzer über ein erreichbares Gerät verfügt, erfahren Sie über das Attribut exten_status (Zeichenkette) des Objekts extension in der Pull-Data-Antwort. Ist das Gerät erreichbar, lautet exten_status Idle, ist es nicht erreichbar, lautet es Unavailable. Beispiele aus der Daktela-Web-App:

exten_status = Idle

Bild - exten_status = Unavailable

Bild

An- und Abmelden bei Warteschlangen¶

Sie können sich über den Endpunkt /api/v6/usersSession bei Warteschlangen an- und abmelden. Eine HTTP-POST-Anfrage mit der Nutzlast {“queues”: [{“name”: “``1234``”, “login”:``true``, “penalty”: “``0``”}]}meldet den Benutzer bei der Warteschlange mit dem Namen 1234 an. Eine HTTP-POST-Anfrage mit der Nutzlast {“queues”: [{“name”: “``1234``”, “login”:``false``}]}meldet den Benutzer von derselben Warteschlange ab. Eine Liste der verfügbaren Warteschlangen können Sie über den WhoIm-Endpunkt oder aus dem Profil des Benutzers laden. Um die Liste aus dem Benutzerprofil zu laden, senden Sie eine HTTP-GET-Anfrage an den Endpunkt /api/v6/profiles/{name}/queues (wobei name die Kennung (name) des Benutzerprofils ist). Die Kennung des Benutzerprofils erhalten Sie aus dem Benutzer-Objekt, das z. B. im Attribut id_agent des Objekts extension in Pull Data gespeichert ist. Aus den geladenen Warteschlangen müssen Sie dann diejenigen herausfiltern, die aktiv sind und bei denen sich der Benutzer anmelden kann. Verwenden Sie dazu die Attribute deactivated (boolean) und _rdata (object) aus dem Warteschlangen-Objekt. Deactivated gibt an, ob die Warteschlange deaktiviert wurde oder nicht. Das Objekt _rdata enthält (unter anderem) das Attribut login (Zeichenkette) – ist sein Wert leer, kann sich der Benutzer nicht bei der Warteschlange anmelden (die weiteren möglichen Werte sind auto, manual und fix).

Eingehende Aktivität¶

Wie oben beschrieben, können Sie über das Long Polling von Pull Data beliebige PBX-Ereignisse abrufen. Dazu gehört eine eingehende Aktivität – in diesem Beispiel ein eingehender Anruf. Bei einer eingehenden Aktivität finden Sie diese im Array activities der Pull-Data-Antwort. Das Aktivitätsobjekt enthält zahlreiche Attribute, darunter:

type (Zeichenkette) – Aktivitätstyp (call, email, chat usw.)
action (Zeichenkette) – aktueller Aktivitätszustand (waiting, open, postponed, closed),
item (object?) – Objekt mit den Daten des jeweiligen Aktivitätstyps (siehe ActivitiesCall, ActivitiesEmail, ActivitiesWeb, ActivitiesSms, ActivitiesFbm, ActivitiesWap, ActivitiesVbr), (Hinweis: nullable),
user (object?) – der Benutzer, dem die Aktivität zugewiesen wurde (oder null, wenn die Aktivität keinem Benutzer zugewiesen wurde). Während eine eingehende Aktivität verteilt wird (oder wenn es keinen Benutzer gibt, an den die Aktivität verteilt werden kann), ist das Attribut action leer (d. h. action = ""). Die Aktivität klingelt beim aktuellen Benutzer, wenn action = WAIT und user = aktuell angemeldeter Benutzer. Wenn das Attribut action leer oder WAIT ist und das Attribut user null ist, klingelt die eingehende Aktivität nicht beim Benutzer (sie kann jedoch weiterhin aus den wartenden Aktivitäten heraus angenommen werden – die Glocke). Beispiele aus der Daktela-Web-App:
action = WAIT und user = currentUser.

Bild - action = “” oder (action = “WAIT” und user = null)

Bild

Sie können eine eingehende Aktivität über eine HTTP-PUT-Anfrage an den Endpunkt der jeweiligen Aktivität (/api/v6/activities/{name}, wobei name die Kennung der Aktivität ist) mit der Nutzlast annehmen {“action”: “OPEN”, “_exten”: “``305``”}_exten (Zeichenkette) bestimmt das Gerät (dessen Kennung – name), das die Aktivität bearbeitet. Verfügt der Benutzer über genau ein Gerät oder ist der Aktivitätstyp kein Anruf (z. B. ein Chat), können Sie das Attribut _exten aus der Nutzlast weglassen. Bei Erfolg gibt der Server eine Antwort 200 OK zurück sowie die Antwort auf die Pull-Data-Polling-Anfrage, die nun action = OPEN in der jeweiligen Aktivität enthält. Eine eingehende Aktivität können Sie auf ähnliche Weise ablehnen – über eine HTTP-PUT-Anfrage an den Endpunkt /api/v6/activities/{name} mit der Nutzlast {“reject”:``true``}

Eine ausgehende Anrufaktivität erstellen¶

Um einen Anruf zu wählen, senden Sie eine HTTP-POST-Anfrage an den Endpunkt /api/v6/activities mit der Nutzlast {“type“: “CALL“, “number“: “``111222333``“}wobei number die Nummer ist, die Sie wählen möchten. Der Benutzer muss bei einer Warteschlange für ausgehende Anrufe angemeldet sein.

Einen Anruf beenden und eine Aktivität schließen¶

Den Zustand eines Anrufs erfahren Sie über die Anrufkanäle. Das in Pull Data zurückgegebene Aktivitätsobjekt enthält das Objekt item (siehe oben), in dem die Daten des jeweiligen Aktivitätstyps gespeichert sind. Handelt es sich bei der Aktivität um einen Anruf, ist im Attribut item das Objekt ActivitiesCall gespeichert. Eine Liste der Anrufkanäle ist im Array channels dieses Objekts gespeichert (Hinweis: nullable). Der Anrufkanal des aktuellen Benutzers hat das Objekt des aktuellen Benutzers im Attribut user gespeichert (d. h. es ist ein Kanal, in dem user = currentUser). Hat das Attribut state des Anrufkanals einen anderen Wert als Closed, läuft der Anruf noch. Um den Anruf zu beenden, senden Sie eine HTTP-PUT-Anfrage an den Endpunkt /api/v6/activities/{name} mit der Nutzlast {“hangup”: {“channel“:``null``}}wobei das Attribut channel (string?) der Kanal ist, der beendet werden soll – ist sein Wert null, wird der Kanal des aktuellen Benutzers beendet. Sie können eine Aktivität (jeden Typs, nicht nur einen Anruf) über eine HTTP-PUT-Anfrage an den Endpunkt /api/v6/activities/{name} mit der Nutzlast schließen {“action”: “CLOSE“}Befindet sich die zu schließende Aktivität in einer Warteschlange, die Status hat, müssen Sie diese als Array mit den einzelnen Statuskennungen (Attribut name) in Ihre Nutzlast aufnehmen. Z. B. schließt die Nutzlast {“action”: “CLOSE“, “statuses“: [“status1”, “status2”]}gesendet in einer Anfrage an den oben genannten Endpunkt die Aktivität und setzt deren Status (mit den Kennungen (name) status1 und status2).

Umgang mit Fehlern, die von der Daktela V6 API zurückgegeben werden¶

Wenn Sie eine ungültige Anfrage senden, gibt die Daktela API eine Antwort 400 Bad Request zurück. Der Antworttext enthält standardmäßig das Attribut error. Ist die Antwort ein Statuscode 2xx, ist das Attribut error auf null gesetzt. Ist die Antwort dagegen ein Statuscode 400, enthält das Attribut error die Fehlermeldung (lokalisiert gemäß dem Header Accept-Language). Wenn Sie beispielsweise versuchen, ein Gerät (siehe oben – HTTP-POST-Anfrage an den Endpunkt /api/v6/usersSession) von einem Benutzer zu entfernen, der bei einer Anrufwarteschlange angemeldet ist, wird eine Antwort mit dem Statuscode 400 mit folgendem Text zurückgegeben {``"result"``:``false``,``"error"``: [``"User is logged in to queues which require at least one device"``]}Auf diese Weise können Sie den Benutzern die von der Daktela V6 API zurückgegebenen Fehlermeldungen anzeigen.

Warning

Das Attribut error kann ein Array von Zeichenketten oder ein Objekt enthalten. Das Fehlerobjekt kann mehrere Ebenen haben (z. B. die Fehlermeldung beim Speichern eines Tickets).