Integrationsdokumentation

Einbettung von Anhängern

Den Kundendienst-Widget auf Ihre Website einbetten – Sie benötigen nur einen Code.

Einbettungscode erhalten

Melden Sie sich im Händler-Backend an → Kanal-Einstellungen → Einbettungscode, und kopieren Sie Ihren persönlichen Einbettungscode:

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://Ihre Kundendienst-Domain/widget/loader.js" data-wk="Ihr widget_key"></script>

Fügen Sie diesen Code vor dem </body> auf jeder Seite Ihres Webauftritts ein. Der Widget wird als Chat-Blase in der rechten unteren Ecke des Bildschirms angezeigt, Besucher können darauf klicken, um den Chat zu starten.

Whitelist für Domains

Um Missbrauch zu verhindern, wird der Widget nur auf den Domains aktiviert, die Sie eingetragen haben. Gehen Sie in das Händler-Backend → Kanal-Einstellungen → Whitelist für Domains, und fügen Sie Ihre Website-Domains hinzu (mehrere Domains werden unterstützt). Domains, die nicht in der Liste stehen, führen beim Laden des Widgets zu einem stummen Fehler, ohne Ihre Seite zu beeinflussen.

widget_key zurücksetzen

Wenn Sie vermuten, dass der Key kompromittiert wurde, können Sie diesen in den Kanal-Einstellungen zurücksetzen. Nach dem Zurücksetzen wird der alte Key sofort ungültig, und Sie müssen den Einbettungscode auf Ihrer Website entsprechend aktualisieren.

Häufig gestellte Fragen

• Der Widget wird nicht angezeigt? Überprüfen Sie, ob die aktuelle Domain in der Whitelist steht, ob der widget_key mit dem Backend übereinstimmt und ob das Konto im Servicezeitraum ist.
• Verlangsamt das den Website-Betrieb? Der Loader ist kleiner als 1 KB und wird asynchron geladen, er blockiert die Darstellung Ihrer Seite nicht.

Mitgliedschaftsintegration identifizieren

Wenn der Besucher sich auf Ihrer Website einloggt, ruft das identify-Verfahren mit den Benutzerinformationen auf. Das Supportsystem ordnet dann diese Browser-Sitzung diesem Mitglied zu – der Supportmitarbeiter kann die Mitgliedsidentität direkt sehen, und auch bei Zugriff über mehrere Geräte wird der Besucher als eindeutiger Nutzer zusammengeführt.

Aufrufmethode

Rufen Sie dies in Ihrem Seiten-Code auf, nachdem bestätigt wurde, dass der Benutzer angemeldet ist:

$aicrs.identify({
  externalId: 'U10086',      // Pflichtfeld, die eindeutige Benutzeridentifikation in Ihrem System
  name: 'Frau Li',             // Optional, Anzeigename
  phone: '138****0000',      // Optional
  email: 'user@example.com', // Optional
  hash: 'im Backend berechneter HMAC-Hash',  // Pflichtfeld, zur Vermeidung von Fälschungen
  custom: { vip: 'gold' }     // Optional, zusätzliche Felder, sichtbar für Supportmitarbeiter
})

Signaturalgorithmus

Der hash muss im Backend Ihres Systems berechnet werden (das widget_secret darf nicht in Frontend-Code eingebettet sein):

hash = SHA256-HMAC(widget_secret, externalId) in Kleinbuchstaben als Hexadezimalstring

Das widget_secret finden Sie im Händler-Backend → Kanal-Einstellungen → Einbettungscode. Es wird gemeinsam mit dem widget_key zurückgesetzt.

Beispiel in Node.js:

const crypto = require('crypto')
const hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

Überprüfungsergebnis

Besucher mit erfolgreich überprüftem Hash werden im Support-Panel mit einem „Verifiziert“-Kennzeichen angezeigt; bei fehlgeschlagener Überprüfung wird der identify-Aufruf ignoriert, die Anonymität bleibt bestehen, und es wird keine Fehlermeldung ausgelöst, die Ihre Seite unterbricht.

Webhook- Ereignisübertragung

Wenn in Ihrem System wichtige Geschäftsereignisse auftreten, wird eine JSON-Nachricht an die von Ihnen konfigurierte Rückrufadresse gesendet, damit Sie Kundendatendaten in Ihr eigenes System synchronisieren können.

Konfiguration

Wählen Sie im Händler-Backend → Daten und System → Webhook aus: Geben Sie die Rückruf-URL (muss HTTPS sein) und den Signaturschlüssel secret ein, wählen Sie die zu abonnierenden Ereignistypen aus. Nach dem Speichern können Sie auf „Testereignis senden“ klicken, um eine sofortige Verbindung zu testen.

Anforderungsformat

Jeder Push ist eine POST-Anforderung:

POST Ihre Rückruf-URL
Content-Type: application/json
X-AICRS-Event: Ereignistyp
X-AICRS-Signature: HMAC-SHA256(secret, Anfragetext) in hexadezimaler Kleinbuchform

Struktur des Anfragetexts:

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "Objekt-Snapshot": "..." }
}

Ereignistypen

Signaturverifikation und Wiederholung

Nach Empfang des Pushes berechnen Sie bitte mit dem secret den HMAC-SHA256 des ursprünglichen Anfragetexts und vergleichen Sie ihn mit X-AICRS-Signature. Wenn sie nicht übereinstimmen, ist die Anfrage ungültig.

Wenn Ihr API 2xx zurückgibt, wird es als erfolgreich betrachtet. Bei Fehlern wird die Anfrage mit den Intervallen 1 Minute / 5 Minuten / 15 Minuten insgesamt 3 Mal wiederholt. Wenn es immer noch fehlschlägt, wird der Status auf fehlgeschlagen gesetzt. Sie können die Ursache der Fehlernachricht in der Lieferprotokollansicht des Hintergrunds überprüfen und manuell beheben.

Offene API

Der Open API kann verwendet werden, um Kundendienst-Daten aus Ihrem System zu lesen, Tickets zu erstellen und nach Händlern zu isolieren.

Authentifizierung

Händler-Backend → Daten und System, um einen API-Schlüssel zu generieren (ähnlich ak_, der Klartext wird nur einmal beim Erstellen angezeigt, bitte bewahren Sie ihn sicher auf; alte Schlüssel werden nach einem Neustart sofort ungültig).

Alle Anfragen enthalten den Anfrage-Header:

Authorization: Bearer ak_YourKey

Rate Limiting

Jeder Schlüssel erlaubt maximal 120 Anfragen pro 60 Sekunden. Bei Überschreitung wird 429 zurückgegeben.

Schnittstellenliste

Beispiel:

curl -H "Authorization: Bearer ak_xxx" \
  "https://Ihre-Kundendienst-Domain/api/open/v1/conversations?page=1"

Hinweise

• Alle Antworten sind im JSON-Format, die Listen-Schnittstellen unterstützen den Pagination-Parameter page.
• Die aktuelle Version unterstützt nicht, Nachrichten an Besucher per API zu senden.
• Der API wird zusammen mit der Deaktivierung des Händlers oder bei Dienstausfall ebenfalls ausgesetzt.

Fehlercode-Übersicht

Alle Schnittstellenantworten bei Fehlern sind einheitlich im JSON-Format:

{ "code": "Fehlercode", "message": "Chinesische Hinweise" }

Zuordnung von HTTP-Statuscodes zu code:

Handlungsempfehlungen:

• 401/403: Prüfen Sie, ob der Key gültig ist und der Kontodienst aktiv ist.
• 429: Wiederholen Sie den Versuch nach Retry-After oder entsprechend der Backoff-Strategie.
• 5xx: Bei idempotenten Schnittstellen ist ein erneuter Versuch sicher; bei nicht idempotenten Operationen prüfen Sie zuerst den Status, bevor Sie erneut versuchen.

CRM-Offene Schnittstellen

Die Lesung und Schreiboperationen für Kunden- und Geschäftschancendaten erfolgen über die Open API (/api/open/v1, Bearer ak_-Schlüssel, im Händler-Backend unter "Daten und System → API" generiert).

Kunde

Die Deduplizierungsregel ist identisch mit der im Backend: external_id > Mobilnummer > E-Mail, bei Treffer wird der bestehende Kunde zusammengeführt anstelle der Erstellung eines doppelten Eintrags.

Rate-Limiting: 120 Anfragen pro Schlüssel pro 60 Sekunden, bei Überschreitung wird 429 zurückgegeben.

Kundenevents übertragen

Kundelebenszyklus-Events werden über den bestehenden Webhook-Kanal gesendet (Händler-Backend "Daten und Systeme → Webhook" abonnieren), die Signatur- und Wiederholungsmechanismen entsprechen denen der Nachrichten-Events (X-AICRS-Signature HMAC-SHA256, exponentielle Wiederholung).

Nutzlast-Format: {"event":"customer.created","data":{...Kundenobjekt...},"ts":1690000000}. Nach Empfang wird mit einem 2xx-Status bestätigt; bei Nicht-2xx-Status oder Timeout erfolgt eine Wiederholung gemäß dem Backoff-Verfahren.