Webchat API
In diesem Artikel geht es um den Webchat aus technischer Sicht. Wer etwas über die API erfahren will, ist hier richtig. Nicht-Entwickler, die etwas über den Webchat und Messaging in GREYHOUND wissen wollen, bitte hier entlang.
Die Einstellungen des Webchat Widgets können über die Gateway API abgerufen und geändert werden. Auch ist es möglich, die Frontend-Dateien des Webchats auf einem eigenen Webserver zu hosten.
Das Messengerkonto für Webchats wird über ein öffentliche ID identifiziert. Im GREYHOUND Client kann diese ID in den Einstellungen des Messengerkontos aus dem Feld “Absender Adresse” übernommen werden. Bei Webchats gilt also die Absender-Adresse des Chats als öffentliche ID dieses Chats. Für alle Requests an die Gateway API wird zur Authentifizierung der API-Key des Messengerkontos verwendet, der ebenfalls in den Einstellungen des Kontos im GREYHOUND Client nachgesehen werden kann.
Chat-Einstellungen
Zum Abrufen der Chat-Einstellungen wird ein HTTP GET Request an die Gateway API gesendet:
GET https://messenger.greyhound-software.com/v2/api/connector/greyhound/chat/<id>/settings
Authorization: Bearer <API-Key des Messengerkontos>Zum Setzen der Chat-Einstellungen dient ein HTTP PUT (oder POST) Request:
PUT https://messenger.greyhound-software.com/v2/api/connector/greyhound/chat/<id>/settings
Content-Type: application/json
Authorization: Bearer <API-Key des Messengerkontos>
{
...
}Frontend-Dateien
Die Gateway API bietet die Möglichkeit, die Frontend-Dateien für den Webchat auf einem eigenen Webserver zu hosten, so dass diese zusammen mit den anderen Webinhalten vom eigenen Server ausgeliefert werden. Die eigentliche Kommunikation, also der Austausch der Chat-Nachrichten, findet nach wie vor über das Gateway statt, aber die Javascript-, Stylesheet- und Grafikdateien des Chat-Frontends können auch vom eigenen Webserver ausgeliefert werden.
Hierzu muss ein Webhook registriert werden, also eine Web-Adresse, an die das Gateway Änderungen an den Dateien mitteilen kann. Für jedes Chat-Messengerkonto kann nur jeweils ein Webhook registriert werden. Dazu wird ein HTTP PUT (oder POST) Request an das Gateway gesendet, der ein JSON Objekt mit Angaben zum Webserver und zum Webhook enthält. Der Request sieht wie folgt aus:
PUT https://messenger.greyhound-software.com/v2/api/connector/greyhound/chat/<id>/frontend
Content-Type: application/json
Authorization: Bearer <API-Key des Messengerkontos>
{
"frontend": {
"url": "https://URL-unter-der-die-Chat-Frontend-Dateien-erreichbar-sein-werden"
},
"webhook": {
"url": "https://URL-unter-der-Änderungen-per-HTTP-Request-gemeldet-werden-können",
"token": "Optionales-Auth-Token",
"username": "Optionaler-Basic-Auth-Username",
"password": "Optionales-Basic-Auth-Password",
"method": "Optionale-HTTP-Methode-für-Änderungs-Requests",
"timeout": "Optionaler-Timeout-in-Sekunden-für-Änderungs-Requests"
}
}
Der Parameter frontend.url muss dabei die URL enthalten, unter der die Chat Frontend-Dateien später erreichbar sein werden. D.h. die Dateinamen der Frontend-Dateien werden an diese URL angehängt.
An webhook.url sendet das Gateway Requests, wenn sich die Frontend-Dateien geändert haben – z.B. wenn die Einstellungen des Chats oder der Online-Status sich ändert. Standardmäßig sendet das Gateway HTTP PUT Requests, über den Parameter webhook.method kann jedoch auch “POST” angegeben werden, um stattdessen HTTP POST Requests zu erhalten. Der Standard-Timeout von 10 Sekunden kann über den Parameter webhook.timeout geändert werden, z.B. falls der Webhook länger braucht, um die Frontend-Dateien vom Gateway herunter zu laden und auf dem Webserver zu speichern.
Der Webhook sollte durch einen Authentifizierungsmechanismus abgesichert werden, damit nur das Gateway Requests an den Webhook senden und Änderungen mitteilen kann. Dazu kann entweder über webhook.token ein Bearer-Token übergeben werden, oder webhook.username und webhook.password für Basic-Authorization.
Als Rückgabe liefert das Gateway ein JSON Objekt mit Angaben zu den Frontend-Dateien des Chats. Dieses hat das selbe Format wie bei Requests, die das Gateway bei Änderungen an den Dateien an den Webhook sendet. Diese Requests sehen wie folgt aus:
PUT webhook-url
Content-Type: application/json
Accept: application/json
Authorization: ...
{
"event": "fileChange",
"files": [
{
"filename": "chat.js",
"type": "text/javascript",
"url": "https://messenger.greyhound-software.com/v2/api/connector/greyhound/chat/.../frontend/chat.js"
},
{
"filename": "img/chat-icon.svg",
"type": "image/svg+xml",
"url": "https://messenger.greyhound-software.com/v2/api/connector/greyhound/chat/.../frontend/img/chat-icon.svg"
}
]
}
Die Liste der geänderten Dateien enthält also für jede Datei ein Objekt. Die Eigenschaft filename gibt den Namen (und ggf. Unterordner) der Frontend-Datei an. Die Datei muss auf dem Webserver so abgelegt werden, dass sie unter der URL erreichbar ist, die beim Registrieren des Webhooks unter frontend.url angegeben wurde, plus den angegebenen filename. Die Eigenschaft type gibt den MIME-Type der Datei an und die Eigenschaft url die URL, über die die Datei vom Gateway herunter geladen werden kann. Zum Herunterladen muss ein HTTP GET Request an diese URL gesendet werden und ein Authorization: Bearer Header mit dem API-Key des Messengerkontos mitgesendet werden.
Der Webhook muss also alle Dateien, die er in der Antwort beim Registrieren des Webhooks erhält und die er in den Änderungs-Requests des Gateways erhält, jeweils herunter laden und auf dem Webserver ablegen. Hierbei ist zu beachten, dass die Dateien auch in Unterordnern liegen können (aktuell ist dies nur der Unterordner “img” für Grafikdateien). Die Dateien werden vom Gateway so vorbereitet, dass darin für alle eingebundenen oder nachgeladenen Frontend-Dateien die frontend.url verwendet wird, die beim Registrieren des Webhooks übergeben wurde.
Um den Chat über die so selbst gehosteten Frontend-Dateien auf der Webseite einzubinden, wird die Datei chat.js vom eigenen Webserver verwendet:
<script type="text/javascript" src="<frontend-url>/chat.js"></script>