Über die Bot-API kann ein Fremdsystem automatisch in alle Unterhaltungen eines Unternehmens mit eingebunden werden. Hierbei wird der Bot über Befehle angesprochen, die mit einem Doppelpunkt beginnen. Beispiel:
:auftraege 4711
Ein so eingegebener Befehl erscheint in der Unterhaltung.
Beginnt der Befehl dagegen mit /:, so wird er unsichtbar ausgeführt und nicht in der Unterhaltung angezeigt.
Voraussetzung ist, dass die Funktion „Bots“ für Ihr Unternehmen freigeschaltet ist. Die Anbindung erfolgt durch Angabe einer über das Internet erreichbaren URL im Unternehmensprofil unter API-Integration im Feld Bot-URL. Im Feld Bot-Name legen Sie fest, unter welchem Namen die Antworten des Bots angezeigt werden.
MEMOIO ruft die Bot-URL per POST auf.
Zur Authentifizierung überträgt MEMOIO einen
Access-Token im Header Authorization.
Der Token wird aus dem API-Key Ihres Unternehmens berechnet; Ihr Bot prüft ihn, indem er dieselbe Berechnung ausführt.
So ist sichergestellt, dass die Anfrage tatsächlich von MEMOIO stammt.
Damit dieses Verfahren sicher ist, sollte die Anbindung über SSL (HTTPS) erfolgen.
Damit der Bot entsprechend reagieren kann, werden die folgenden Parameter mitgegeben:
| Parameter | Beschreibung |
|---|---|
| command | Enthält den Befehl, der direkt hinter dem Doppelpunkt eingegeben wurde. |
| params | Enthält weitere Parameter, die mit einem Leerzeichen von dem Befehl abgetrennt sind. |
| silent | Gibt an, ob der Befehl unsichtbar (true) aufgerufen wurde, oder ob der Befehl in der Unterhaltung angezeigt wird (false). |
| conversation | Enthält die ID der Unterhaltung. |
| topic | Enthält das Thema der Unterhaltung. |
| references | Enthält die Referenzen, die das Unternehmen des Bots an der Unterhaltung hinterlegt hat, falls vorhanden. Sind mehrere Werte vorhanden, werden diese kommagetrennt übergeben. |
| tags | Enthält die Tags, die das Unternehmen des Bots an der Unterhaltung hinterlegt hat, falls vorhanden, und zwar so, wie MEMOIO sie speichert: bei angelegten Tags deren ID, bei freien Tags den Namen mit vorangestelltem #. Sind mehrere Werte vorhanden, werden diese kommagetrennt übergeben. |
| caller | Enthält die E-Mail-Adresse des Aufrufers des Befehls. Sie wird nur übergeben, wenn sie bestätigt ist. |
| internalUser | Enthält die E-Mail-Adresse desjenigen der ersten beiden Teilnehmer, der zum Unternehmen des Bots gehört. Sie wird nur übergeben, wenn sie bestätigt ist. |
| externalUser | Enthält die E-Mail-Adresse desjenigen der ersten beiden Teilnehmer, der nicht zum Unternehmen des Bots gehört. Sie wird nur übergeben, wenn sie bestätigt ist. |
| participants | Enthält die bestätigten E-Mail-Adressen aller Teilnehmer, kommagetrennt. |
| senderIP | Enthält die IP-Adresse, von der aus der Befehl gesendet wurde. Ihr kann ein Schrägstrich / vorangestellt sein. |
Der Text der Antwort wird direkt als Nachricht des Bots in die Unterhaltung eingefügt. Hierbei kann kein HTML, aber die von MEMOIO unterstützte Auszeichnungssprache verwendet werden. Ist der Bot nicht erreichbar oder antwortet er mit einem Fehler, so weist MEMOIO darauf hin: bei einem sichtbaren Befehl in der Unterhaltung, bei einem unsichtbaren nur gegenüber dem Aufrufer.
Über die folgenden Header der Antwort kann der Bot die Unterhaltung zusätzlich verändern:
| Header | Beschreibung |
|---|---|
| X-References | Eine oder mehrere Referenzen (kommagetrennt). Sie ersetzen die Referenzen, die das Unternehmen des Bots bisher an der Unterhaltung hinterlegt hat. Soll eine Referenz erhalten bleiben, muss sie erneut angegeben werden. |
| X-Tags | Ein oder mehrere Tags (kommagetrennt), die der Unterhaltung hinzugefügt werden. Hat das Unternehmen des Bots Tags angelegt, werden nur diese übernommen; unbekannte Namen werden ignoriert. |
| X-Visibility |
Steuert, wie die Antwort angezeigt wird:
|
Ist der Header X-Visibility gesetzt, so kann die Antwort statt reinem Text auch XML enthalten.
Dazu sendet der Bot den Content-Type text/xml.
Der Hinweis erhält dann eine Schaltfläche, die eine Aktion auslöst:
<result>
<message>Der Auftrag wurde angelegt.</message>
<action_label>Auftrag öffnen</action_label>
<action>http:https://erp.example.com/auftraege/4711</action>
</result> | Element | Beschreibung |
|---|---|
| message | Enthält den Text des Hinweises. |
| action_label | Enthält die Beschriftung der Schaltfläche. |
| action |
Enthält die Aktion, die ein Klick auf die Schaltfläche auslöst.
Mit http: vor einer URL öffnet sich diese in einem neuen Fenster,
mit page: als Widget in MEMOIO
und mit dialog: als Dialog in MEMOIO.
Bei open-widget wird diese Adresse direkt geöffnet.
|
Die Schaltfläche erscheint nur, wenn sowohl action als auch action_label angegeben sind.
Beginnt eine Eingabe mit : oder /:, so fragt MEMOIO den Bot nach Vorschlägen für die Autovervollständigung.
Dazu ruft MEMOIO die Bot-URL mit dem Befehl autocomplete im Parameter command auf.
Neben den Angaben zur Unterhaltung (siehe oben) werden folgende Parameter übergeben:
| Parameter | Beschreibung |
|---|---|
| input | Enthält das Wort, das gerade eingegeben wird. Solange noch der Befehl eingegeben wird, ist dies der Befehl selbst. |
| firstWord | Enthält das erste Wort der Eingabe, also den Befehl. |
| atFirstWord | Gibt an, ob gerade noch das erste Wort eingegeben wird (true) oder bereits die Parameter (false). |
| allParameters | Enthält alles, was hinter dem ersten Wort eingegeben wurde, bei sehr langen Eingaben gekürzt. |
Als Antwort wird XML erwartet, das für jeden Vorschlag ein Element completion enthält:
<completions>
<completion>
<type>SEND</type>
<completion>:auftraege </completion>
<label>:auftraege</label>
<description>Zeigt die offenen Aufträge an</description>
<icon>https://erp.example.com/icon.png</icon>
</completion>
</completions> | Element | Beschreibung |
|---|---|
| type | SUGGEST übernimmt den Vorschlag in das Eingabefeld, SEND sendet ihn sofort und WIDGET öffnet die in completion angegebene Adresse als Widget. |
| completion | Enthält den vorgeschlagenen Text oder bei WIDGET die Adresse des Widgets, etwa page:https://…. |
| label | Enthält die Beschriftung des Vorschlags. |
| description | Enthält eine optionale Beschreibung des Vorschlags. |
| icon | Enthält die URL eines kleinen Bildes, das neben dem Vorschlag angezeigt wird. |
Haben mehrere beteiligte Unternehmen einen Bot, so prüft MEMOIO die folgenden Bots in dieser Reihenfolge und ruft den ersten vorhandenen auf:
- Den Bot des Unternehmens, dem der Channel gehört, über den die Unterhaltung gestartet wurde.
- Den Bot des Unternehmens, zu dem der Aufrufer des Befehls gehört.
- Den Bot des Unternehmens des zweiten Teilnehmers, also desjenigen, der beim Start der Unterhaltung angesprochen wurde.
Ein Unternehmen hat nur dann einen Bot, wenn die Funktion „Bots“ freigeschaltet und sowohl eine Bot-URL als auch ein API-Key hinterlegt ist. Wird kein Bot gefunden, so weist MEMOIO in der Unterhaltung darauf hin.