Ein Endpunkt nimmt Meldungen aus anderen Systemen entgegen und stellt sie als Nachricht in einen Chatraum Ihres Unternehmens, etwa Warnungen einer Überwachung oder Hinweise aus einem Bestellsystem. Jeder Endpunkt ist über eine eigene URL und eine eigene E-Mail-Adresse erreichbar. Die Richtung ist dabei immer dieselbe: MEMOIO empfängt, ruft selbst aber kein anderes System auf.
- Für Ihr Unternehmen ist das Merkmal „MEMOIO Hooks“ gebucht. Zum Buchen wenden Sie sich an Ihren Ansprechpartner oder an den Support unter info@scireum.de / +49 711 205 004 - 10 / Live-Support.
- Ihr Konto besitzt das Recht „Unternehmen verwalten“.
Die Endpunkte finden Sie dann im Menü „Verwalten“ unter „Endpunkte“. Aus der Chat-Oberfläche gelangen Sie dorthin über „Einstellungen“ am linken Rand und „Weitere Einstellungen“.
- „Endpunkte“, dann „Neuer Endpunkt“.
- Name: erscheint nur in Ihrer Liste der Endpunkte, nicht in den Nachrichten.
- Unterhaltung (Chatraum): der Chatraum, in den die Nachrichten gehen. Zur Auswahl stehen Chaträume Ihres Unternehmens; vertrauliche nur, wenn Sie selbst daran teilnehmen.
- Nachricht: optionale Vorlage für die Nachricht, siehe unten.
- Speichern.
Danach zeigt der Endpunkt seine Hook ID und unter „Zugang“ die URL und die E-Mail-Adresse.
Die Nachrichten erscheinen unter dem Namen Ihres Unternehmens. Ist im Unternehmensprofil unter „API-Integration“ ein „Bot-Name“ eingetragen (siehe Bot-API), erscheinen sie unter diesem. Da das Ziel ein Chat ist, löscht MEMOIO alte Nachrichten nach einiger Zeit automatisch.
Ohne Vorlage wird der übermittelte Text unverändert eingefügt. Eine Vorlage bettet ihn in eigenen Text ein, mit ${text} als Platzhalter:
Neue Störung gemeldet: ${text} Bei Aufrufen mit Parametern oder JSON steht jeder übermittelte Parameter als ${name} zur Verfügung. Bei E-Mails stehen ${topic} (Betreff), ${body} (Text), ${sender} (Absenderadresse) und ${senderName} (Absendername) bereit. Fehlt ein Parameter, bleibt seine Stelle leer.
Eckige Klammern bilden in der Vorlage einen Block, der nur erscheint, wenn mindestens ein Platzhalter darin gefüllt ist. So entfällt etwa [Kunde: ${kunde}] ganz, wenn kein Parameter kunde übermittelt wurde. Eckige Klammern als gewöhnlicher Text sind in der Vorlage deshalb nicht möglich.
Die URL hat die Form:
https://memoio.test.scireum.com/endpoint/hook/<Hook ID>
Wie MEMOIO den Aufruf liest, richtet sich nach dem Header Content-Type.
Parameter (ohne passenden Content-Type): Der Text steht im Parameter text oder message, als Query-Parameter oder als Formularfeld.
curl "https://memoio.test.scireum.com/endpoint/hook/<Hook ID>?text=Server%20nicht%20erreichbar"
Antwort: {"success": true, "error": false} oder bei einem Fehler {"success": false, "error": true, "message": "…"}.
JSON (Content-Type: application/json): Der Text steht im Feld text oder message. Zusätzlich wird ein Feld attachments gelesen, eine Liste von Objekten, deren text, message oder fallback jeweils als eigene Zeile angehängt wird. Damit lassen sich viele Werkzeuge anbinden, die für eingehende Webhooks im Format von Slack gebaut sind.
curl -H "Content-Type: application/json" \
-d '{"text": "Deployment abgeschlossen"}' \
"https://memoio.test.scireum.com/endpoint/hook/<Hook ID>" Antwort im Format von Slack: bei Erfolg {"ok": true, "channel": "…", "ts": …, "message": {…}}, sonst {"ok": false, "error": "…"}.
XML (Content-Type: text/xml): Der Text steht im Element text oder message unterhalb des Wurzelelements. Andere XML-Typen wie application/xml erkennt MEMOIO nicht; solche Aufrufe liest es wie Aufrufe mit Parametern. Weitere Parameter stehen der Vorlage hier nicht zur Verfügung. Die Antwort enthält dieselben Angaben wie bei Parametern, als XML.
Eine E-Mail an die Adresse des Endpunkts wird ebenfalls eingefügt. Die Adresse hat die Form:
endpoint-<Hook ID>@memoio.test.scireum.com
Als Text dient der Betreff; den Inhalt der E-Mail erhalten Sie nur über ${body} in einer Vorlage. E-Mails ohne Betreff werden abgewiesen, ebenso E-Mails von der Adresse eines gesperrten MEMOIO-Kontos.
| Ursache | Parameter, XML | JSON |
|---|---|---|
| Hook ID unbekannt oder Endpunkt deaktiviert | Unknown endpoint. | access_denied |
| Chatraum nicht mehr vorhanden | Unknown conversation configured in endpoint. | channel_not_found |
| Kein Text und keine Vorlage | Message not sent. | no_text |
Diese Fehler werden mit HTTP-Status 200 gemeldet; prüfen Sie daher success bzw. ok in der Antwort. Andere Fehler, etwa ein ungültiger Aufruf, liefern bei Parametern und XML den Status 400.
Die Zahl der Aufrufe ist je Endpunkt begrenzt, zusätzlich je Unternehmen gemeinsam mit den übrigen Schnittstellenaufrufen. Wird eine Grenze überschritten, weist MEMOIO weitere Aufrufe eine Zeit lang ab.
Ein Endpunkt verlangt keine weitere Anmeldung: Wer die URL oder die E-Mail-Adresse kennt, kann Nachrichten in den Chatraum stellen. Behandeln Sie beide daher wie ein Passwort und rufen Sie die URL nur über HTTPS auf.
- Deaktivieren (über das Menü des Endpunkts oder das Feld „Aktiviert“): Der Endpunkt verwirft alle eingehenden Nachrichten, URL und Adresse bleiben aber gleich. Geeignet für eine Pause.
- Löschen und neu anlegen: Der neue Endpunkt erhält eine neue Hook ID und damit eine neue URL und Adresse. Das ist der Weg, wenn die Zugangsdaten in falsche Hände geraten sind.