Schnittstelle für eigene Widgets

Zwei Arten von eigenen Widgets können ihre Inhalte von Ihrem Server beziehen, wenn dort eine API-URL eingetragen ist: das Chat-Eingabefeld und der Referenz-Anbieter. Dieser Artikel beschreibt, was MEMOIO dabei an Ihren Server schickt und welche Antwort es erwartet. Beachten Sie, dass die beiden Typen unterschiedliche Antwortformate erwarten: JSON für das Eingabefeld, XML für Referenzen.

• MEMOIO ruft die API-URL per POST auf und überträgt die Parameter als application/x-www-form-urlencoded in UTF-8.
• Im Header Authorization überträgt MEMOIO einen Access-Token, der aus dem API-Key Ihres Unternehmens berechnet wird. Prüfen Sie ihn, um sicherzustellen, dass der Aufruf von MEMOIO stammt. Wie, beschreibt Authentifizierung.
• Ihr Server muss die Verbindung innerhalb von 2 Sekunden annehmen und innerhalb von 15 Sekunden antworten. Fehlgeschlagene Aufrufe wiederholt MEMOIO nicht.
• Antworten Sie mit dem Status 200.

Öffnet ein Nutzer im Eingabefeld die Liste der Widgets, so fragt MEMOIO Ihren Server nach Vorschlägen, und zwar bei jeder weiteren Eingabe erneut. Mitgeschickt werden:

• account – die ID des Nutzerkontos,
• accountName – der Name des Nutzers,
• accountEmail – seine E-Mail-Adresse.

Erwartet wird JSON in dieser Form:

{
    "suggestions": [
        {
            "label": "Neuer Auftrag",
            "description": "Legt einen Auftrag im ERP an",
            "url": "dialog:https://erp.example.com/auftrag/neu"
        }
    ]
}

label und description erscheinen in der Liste. Für url gelten dieselben Präfixe wie bei allen eigenen Widgets (siehe Was eine URL auslöst); Platzhalter werden hier nicht ersetzt.

Für jede Referenz mit dem Code Ihres Referenz-Anbieters, etwa auftrag:4711, fragt MEMOIO Ihren Server, wie sie angezeigt werden soll. Im Parameter reference steht der Teil nach dem Doppelpunkt, hier also 4711. MEMOIO speichert Referenzen in Großbuchstaben; unterscheiden Sie daher nicht zwischen Groß- und Kleinschreibung.

Erwartet wird XML in dieser Form:

<result>
    <label>Auftrag 4711 – Müller GmbH</label>
    <url>https://erp.example.com/auftrag/4711</url>
</result>

label ist der angezeigte Text. Die Adresse unter url öffnet sich in einem neuen Fenster, wenn der Nutzer auf den Pfeil neben der Referenz klickt; geben Sie sie daher vollständig und ohne Präfix an. Ohne url erscheint kein Pfeil. Bleibt label leer, so zeigt MEMOIO die Referenz unverändert an.

Ist beim Referenz-Anbieter „Bietet Autovervollständigung“ angehakt, so bietet MEMOIO ihn nach Eingabe von /referenzieren (englisch /ref) zur Auswahl an. Sobald ein Nutzer /referenzieren auftrag: eintippt, ruft MEMOIO Ihren Server mit dem Parameter query auf, der den bisher eingetippten Wert enthält. Dieser kann auch leer sein. Das geschieht unabhängig von diesem Haken; bieten Sie keine Vorschläge an, so genügt eine leere Liste als Antwort.

Erwartet wird XML mit einem suggestions-Element je Vorschlag:

<result>
    <suggestions>
        <label>Auftrag 4711 – Müller GmbH</label>
        <reference>4711</reference>
    </suggestions>
    <suggestions>
        <label>Auftrag 4712 – Schmidt AG</label>
        <reference>4712</reference>
    </suggestions>
</result>

Wählt der Nutzer einen Vorschlag, so wird die Referenz an der Unterhaltung hinterlegt, und zwar in Großbuchstaben als AUFTRAG:4711.