Einrichtungsanleitung

Schnellstart

1. Kopieren Sie in der Konsole unter Einstellungen → Installation Ihren Website-Schlüssel (beginnt mit cd_).
2. Fügen Sie den Code oben auf dieser Seite in alle Seiten Ihrer Website ein, direkt vor dem Tag </body>. Ersetzen Sie IHR_WEBSITE_SCHLUESSEL durch Ihren Schlüssel.
3. Laden Sie die Seite neu; unten in der Ecke erscheint der Chat-Button. Solange Sie in der Konsole online sind, können Besucher Ihnen schreiben.

Der Code verlangsamt Ihre Seite nicht: Der Loader ist klein und wird zwischengespeichert, das Widget lädt separat und versioniert. Ist unser Server nicht erreichbar, erscheint ein einfacher Button zu der Adresse, die Sie unter Einstellungen → Allgemein → Ersatz-Kontaktlink eintragen.

WordPress

Für die Installation ohne Code laden Sie das Plugin herunter. Es fügt das Widget ein und meldet auf Wunsch angemeldete Mitglieder mit signierter Identität an.

WordPress-Plugin herunterladen

1. Laden Sie die ZIP-Datei in der WordPress-Verwaltung unter Plugins → Neues Plugin hinzufügen → Plugin hochladen hoch und aktivieren Sie es.
2. Fügen Sie Ihren Website-Schlüssel auf der Seite Einstellungen → Layvchat ein.
3. Optional: Aktivieren Sie Mitgliedsidentität und geben Sie den Signaturschlüssel ein (in der Konsole: Einstellungen → Besucher-ID → Geheimschlüssel anzeigen).

Kompatibel mit Cache-Plugins: Die Mitgliedsidentität wird nicht ins HTML der Seite geschrieben, sondern für jeden Besucher mit einer eigenen, nicht zwischengespeicherten Anfrage geholt. Der Signaturschlüssel bleibt auf dem Server Ihrer Website.

Das Widget per Code steuern

Der Installationscode fügt der Seite das Objekt window.layvchat hinzu. Befehle sind sofort nach dem Laden nutzbar: Ist das Widget noch nicht bereit, werden Aufrufe zurückgestellt und ausgeführt, sobald es bereit ist. Jeder Befehl hat auch einen türkischen Namen (z. B. open = ac); beide funktionieren.

Befehle

// Button „Zu diesem Produkt fragen“
document.querySelector('#produkt-frage').addEventListener('click', function () {
  window.layvchat.prefill('Hallo, ich hätte gern mehr Infos zum „Lederrucksack“.')
})

// Angemeldetes Mitglied und Warenkorb für den Agenten anzeigen
window.layvchat.setVisitor({ ad: 'Anna Schmidt', eposta: '[email protected]' })
window.layvchat.setAttributes({ 'Warenkorb': '129,90 €', 'Mitgliedschaft': 'Gold' })

Daten aus setVisitor und setAttributes kommen aus dem Browser und sind nicht signiert; die Konsole zeigt sie als nicht verifiziert. Um ein Mitgliedskonto sicher zu identifizieren, nutzen Sie die Besucheridentität.

Ereignisse

window.layvchat.on('chatStarted', function () {
  gtag('event', 'live_chat_gestartet')        // Analyse
})
window.layvchat.on('message', function (m) {
  if (m.kim === 'ajan') console.log(m.ajan + ': ' + m.metin)
})

// Dieselben Ereignisse werden auch auf window ausgelöst (englische und türkische Namen)
window.addEventListener('layvchat:unread', function (e) { badge(e.detail.n) })

Läuft Ihr Code vor dem Installationscode, legen Sie Aufrufe in die Warteschlange:

(window.layvchatKuyruk = window.layvchatKuyruk || []).push(['open'], ['setAttributes', { 'Seite': 'Kasse' }])

CSS-Variablen

Position und Ebene des Buttons lassen sich mit dem CSS Ihrer Website überschreiben; das Fenster richtet sich am Button aus. Nützlich, wenn das Widget mit einem Cookie-Banner oder einer mobilen Navigationsleiste kollidiert.

@media (max-width: 768px) {
  :root { --layvchat-alt: 84px; }   /* über der mobilen Navigationsleiste bleiben */
}

Haben Sie vorher Tawk.to oder Comm100 genutzt, öffnen auch Ihre bestehenden Aufrufe Tawk_API.maximize() und Comm100API.do('livechat.button.click') das Layvchat-Fenster; Ihre Buttons müssen Sie nicht ändern.

Besucheridentität

Wenn Sie auf Ihrer Website angemeldete Besucher identifizieren, sehen Ihre Agenten verifiziert (blauer Haken), mit welchem Mitglied sie chatten. Bei verifizierten Besuchern kann das Vor-Chat-Formular entfallen, und bei aktiver Website-Integration erscheint die Kundenkarte.

Die Identität wird durch eine Signatur auf dem Server Ihrer Website nachgewiesen; so kann niemand im Browser ein anderes Mitglied vortäuschen. Den Signaturschlüssel erhalten Sie in der Konsole unter Einstellungen → Besucher-ID → Geheimschlüssel anzeigen; bewahren Sie ihn nur auf Ihrem Server auf.

Signatur

imza = HMAC-SHA256(geheimnis, id + "|" + username + "|" + zaman)   → Hex in Kleinbuchstaben (64 Zeichen)

Drei Wege, die Identität an das Widget zu übergeben

1. In die Seite schreiben. Wenn Sie Seiten auf dem Server erzeugen, fügen Sie dies vor dem Installationscode ein. Nicht mit Seiten-Cache verwenden: Die Signatur eines Mitglieds könnte anderen Besuchern ausgeliefert werden.

<script>
  window.layvchatKimlik = { id: "123", username: "aschmidt", zaman: 1760000000, imza: "…" }
</script>

2. An- und Abmeldung melden. Geeignet für Single-Page-Apps (React, Vue …). Da eine Signatur 2 Stunden gilt, rufen Sie es auf lange geöffneten Seiten mit neuer Signatur erneut auf.

window.layvchat.identify({ id: "123", username: "aschmidt", zaman: 1760000000, imza: "…" })
window.layvchat.identify(null)   // nach der Abmeldung

3. Identitätsendpunkt. Tragen Sie in der Konsole unter Einstellungen → Besucher-ID → Identitätsendpunkt eine relative Adresse Ihrer Website ein, die die signierte Identität zurückgibt (z. B. /layvchat/identity). Das Widget liest sie vom selben Ursprung mit Cookies und aktualisiert sie beim Laden, alle 15 Sekunden, bei Rückkehr in den Tab und bei Navigation innerhalb der Seite. Für nicht angemeldete Besucher geben Sie {"id": null} zurück; eine Antwort, die kein JSON ist oder fehlschlägt, gilt als „abgemeldet“.

<?php // /layvchat/identity
session_start();
header('Content-Type: application/json');
header('Cache-Control: no-store');
$secret = getenv('LAYVCHAT_IDENTITY_SECRET');
if (empty($_SESSION['member_id'])) { echo json_encode(['id' => null]); exit; }
$id = (string) $_SESSION['member_id'];
$name = (string) $_SESSION['member_username'];
$time = time();
echo json_encode([
  'id' => $id, 'username' => $name, 'zaman' => $time,
  'imza' => hash_hmac('sha256', "$id|$name|$time", $secret),
]);

// Express — /layvchat/identity
import crypto from 'node:crypto'
app.get('/layvchat/identity', (req, res) => {
  res.set('Cache-Control', 'no-store')
  const member = req.session?.member
  if (!member) return res.json({ id: null })
  const id = String(member.id), name = String(member.username), time = Math.floor(Date.now() / 1000)
  const imza = crypto.createHmac('sha256', process.env.LAYVCHAT_IDENTITY_SECRET).update(`${id}|${name}|${time}`).digest('hex')
  res.json({ id, username: name, zaman: time, imza })
})

# Flask — /layvchat/identity
import hmac, hashlib, os, time
from flask import jsonify, session

@app.get("/layvchat/identity")
def layvchat_identity():
    if "member_id" not in session:
        response = jsonify(id=None)
    else:
        uid, name, ts = str(session["member_id"]), str(session["member_username"]), int(time.time())
        imza = hmac.new(os.environ["LAYVCHAT_IDENTITY_SECRET"].encode(), f"{uid}|{name}|{ts}".encode(), hashlib.sha256).hexdigest()
        response = jsonify(id=uid, username=name, zaman=ts, imza=imza)
    response.headers["Cache-Control"] = "no-store"
    return response

Ist Einstellungen → Besucher-ID → Nur signierte Identitäten anzeigen aktiv, sehen Agenten Benutzernamen mit ungültiger Signatur nie. Ist die Option aus, dienen sie nur als Anzeigename und gelten nicht als verifiziert.

Content Security Policy (CSP)

Nutzt Ihre Website eine CSP, erlauben Sie die Layvchat-Adresse wie folgt:

script-src   {{KOK}}
connect-src  {{KOK}} {{WS}}     (mit Identitätsendpunkt auch 'self')
frame-src    {{KOK}}
style-src    'unsafe-inline'
img-src      https:            (nur mit eigenem Button-Bild)
media-src    {{KOK}}           (nur mit eigenem Benachrichtigungston)

Das Widget setzt auf Ihrer Website keine Cookies. Besucherschlüssel und Ersatzlink liegen in localStorage mit dem Präfix layv_cd_; Chatinhalte und Zugriffstoken bleiben ausschließlich im eigenen Ursprung des Layvchat-Fensters.

Website-Integration Pro

Während eines Chats sehen Ihre Agenten die Kontodaten des verifizierten Besuchers (letzte Bestellungen, Status …) und können die von Ihnen erlaubten Aktionen ausführen. Layvchat holt diese Daten mit signierten Anfragen von einigen Endpunkten auf Ihrem Server. Die Integration funktioniert nur bei verifizierten Besuchern.

1. Implementieren Sie die folgenden Endpunkte auf Ihrem Server (z. B. unter https://ihreseite.de/layvchat-api).
2. Tragen Sie diese Adresse in der Konsole unter Einstellungen → Website-Integration ein. Der Signaturschlüssel (beginnt mit entg_) wird nur einmal angezeigt; speichern Sie ihn auf Ihrem Server.
3. Geben Sie Agenten unter Einstellungen → Agenten die nötigen Berechtigungen (Daten ansehen, Notizen, Sperren).

Anfragen

:id ist die id aus der Besucheridentität. yapan ist der ausführende Agent (canli-destek:benutzername).

Signatur prüfen

Jede Anfrage kommt mit den Headern X-Imza-Zaman (Unix-Sekunden) und X-Imza:

X-Imza = HMAC-SHA256(geheimnis, zeit + "." + METHODE + "." + vollerPfad + "." + roherBody)   → Hex in Kleinbuchstaben

vollerPfad ist der Anfragepfad einschließlich des Pfads Ihrer Adresse: Lautet die Adresse https://ihreseite.de/layvchat-api, ist es /layvchat-api/uye/42. Bei GET ist der Body ein leerer String. Lehnen Sie Zeitstempel ab, die älter als 5 Minuten sind.

<?php
function layvchat_verify(string $secret): bool {
  $time = $_SERVER['HTTP_X_IMZA_ZAMAN'] ?? '';
  $sig  = $_SERVER['HTTP_X_IMZA'] ?? '';
  if (!ctype_digit($time) || abs(time() - (int) $time) > 300) return false;
  $body = file_get_contents('php://input');
  $expected = hash_hmac('sha256', $time . '.' . $_SERVER['REQUEST_METHOD'] . '.' . $_SERVER['REQUEST_URI'] . '.' . $body, $secret);
  return hash_equals($expected, $sig);
}

// Express: benötigt den rohen Body → app.use(express.json({ verify: (req, _r, buf) => { req.rawBody = buf.toString() } }))
import crypto from 'node:crypto'
function layvchatVerify(req, secret) {
  const time = req.get('x-imza-zaman') || '', sig = req.get('x-imza') || ''
  if (!/^\d+$/.test(time) || Math.abs(Date.now() / 1000 - Number(time)) > 300) return false
  const expected = crypto.createHmac('sha256', secret)
    .update(`${time}.${req.method}.${req.originalUrl}.${req.rawBody || ''}`).digest('hex')
  return expected.length === sig.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))
}

Antwort für die Kundenkarte

GET /uye/:id muss ein JSON-Objekt zurückgeben. Nur uye.id ist Pflicht; unbekannte Felder werden ignoriert. Existiert das Mitglied nicht, antworten Sie mit 404.

{
  "uye": {
    "id": "42", "kullaniciAdi": "aschmidt", "ad": "Anna", "soyad": "Schmidt",
    "eposta": "[email protected]", "telefon": "5551112233", "ulke": "DE", "paraBirimi": "EUR",
    "toplamHarcama": 5000, "toplamIade": 320,
    "durum": "aktif", "kayitTarihi": "2025-03-14T10:00:00Z", "sonGiris": "2026-10-04T21:10:00Z",
    "riskEtiketleri": ["neues Konto"]
  },
  "sonIslemler": [
    { "id": "S1001", "tur": "siparis", "tutar": 500, "durum": "versendet", "aciklama": "2 Artikel", "zaman": "2026-10-04T20:00:00Z" }
  ]
}

Bei POST-Anfragen geben Sie bei Erfolg 2xx und ein JSON-Objekt zurück (z. B. {"ok": true}). Zum Ablehnen geben Sie {"hata": "kurzer_code"} zurück. 404 sieht der Agent als „nicht gefunden“, andere Fehlercodes als „Die Website hat einen Fehler gemeldet“.

Anfragen gehen nur über https an Port 443 und an öffentliche Internetadressen; Weiterleitungen werden nicht verfolgt. Zeitlimit 10 Sekunden, Antworten höchstens 512 KB.

Webhooks Pro

Senden Sie Chat-Ereignisse in Echtzeit an Ihre eigenen Systeme (CRM, Benachrichtigungen, Berichte). Adresse und Ereignisse wählen Sie in der Konsole unter Einstellungen → Webhooks und API; der Signaturschlüssel (beginnt mit whsec_) wird einmal angezeigt.

{
  "id": "6f1c…",                 // Zustellungs-ID — bleibt bei Wiederholungen gleich
  "olay": "sohbet.bitti",          // Ereignis
  "zaman": "2026-10-05T09:12:00.000Z",
  "deneme": 1,                     // Versuch
  "veri": {
    "konusma": {                   // Unterhaltung
      "id": "…", "durum": "kapandi", "kaynak": "ziyaretci",
      "baslatildi": "…", "kapandi": "…", "kapanisSebep": "kapatildi",
      "ziyaretci": { "no": 128, "ad": "Anna", "kullaniciAdi": "aschmidt", "uyeId": "42", "ulke": "DE" },
      "ajan": "Lukas", "etiketler": ["zahlung"], "puan": 5
    }
  }
}

kullaniciAdi (Benutzername) und uyeId (Mitglieds-ID) sind nur bei verifizierten Besuchern gefüllt.

Header und Signatur

<?php
$body = file_get_contents('php://input');
$time = $_SERVER['HTTP_X_IMZA_ZAMAN'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $time . '.' . $body, getenv('LAYVCHAT_WEBHOOK_SECRET'));
if (!ctype_digit($time) || abs(time() - (int) $time) > 300 || !hash_equals($expected, $_SERVER['HTTP_X_IMZA_IMZA'] ?? '')) {
  http_response_code(401); exit;
}
$event = json_decode($body, true);
// überspringen, falls $event['id'] schon verarbeitet wurde; dann 2xx zurückgeben
http_response_code(204);

import crypto from 'node:crypto'
app.post('/layvchat/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const time = req.get('x-imza-zaman') || '', raw = req.body.toString()
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.LAYVCHAT_WEBHOOK_SECRET).update(`${time}.${raw}`).digest('hex')
  const sig = req.get('x-imza-imza') || ''
  const valid = /^\d+$/.test(time) && Math.abs(Date.now() / 1000 - Number(time)) <= 300 &&
    sig.length === expected.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
  if (!valid) return res.sendStatus(401)
  const event = JSON.parse(raw)
  // überspringen, falls event.id schon verarbeitet wurde
  res.sendStatus(204)
})

Antworten Sie innerhalb von 8 Sekunden mit 2xx; schwere Arbeit gehört in eine Warteschlange. Eine fehlgeschlagene Zustellung wird nach 5 s, 30 s und 2 min wiederholt (höchstens 4 Versuche). Nach 20 Fehlversuchen in Folge wird der Webhook deaktiviert; in der Konsole sehen Sie die letzten 50 Zustellungen und können mit „Test“ ein Beispiel senden. Die Adresse muss https auf Port 443 und öffentlich erreichbar sein.

REST-API Pro

Holen Sie Berichte und Chats in Ihre eigenen Systeme. Einen Schlüssel erstellen Sie in der Konsole unter Einstellungen → Webhooks und API → API-Schlüssel (nur Inhaber des Arbeitsbereichs); der geheime Schlüssel wird einmal angezeigt. Bis zu 5 aktive Schlüssel; für jeden lässt sich eine IP-Freigabeliste festlegen. Schlüssel sind nur lesend.

curl -u "layv_…:layvs_…" "{{KOK}}/api/v1/canli/rapor?gun=7"

Das Objekt konusma ist dasselbe wie bei Webhooks. Fehlercodes: 401 Schlüssel fehlt oder ist ungültig (der Grund wird aus Sicherheitsgründen nicht genannt) · 402 Ihr Paket enthält keine API · 404 Chat nicht gefunden.

Fehlerbehebung

Der Chat-Button erscheint nicht

Prüfen Sie den Website-Schlüssel (beginnt mit cd_). In der Konsole ist eventuell Einstellungen → Allgemein → Live-Chat aktiviert aus oder Einstellungen → Widget-Aussehen → Auf Mobilgeräten ausblenden an. Hat Ihre Website eine CSP, fügen Sie die Berechtigungen hinzu. Prüfen Sie in der Browserkonsole die Antwort auf die Anfrage /cd/v/ayar: 404 bedeutet, dass der Schlüssel nicht erkannt wurde.

Der Besucher wird nicht als verifiziert angezeigt

Häufigste Ursachen: zaman in Millisekunden gesendet (müssen Sekunden sein), Signatur in Großbuchstaben, falsche Serveruhr, signierter Benutzername weicht vom gesendeten ab, oder id enthält unzulässige Zeichen. Eine Signatur gilt 2 Stunden; auf lange geöffneten Seiten erneuern.

Webhooks kommen nicht an

Sehen Sie in der Konsole unter Einstellungen → Webhooks und API den Zustellverlauf an. Die Adresse muss https sein, innerhalb von 8 Sekunden 2xx liefern und darf nicht weiterleiten. Nach 20 Fehlern in Folge wird der Webhook deaktiviert; nach der Korrektur wieder einschalten.

Die Kundenkarte öffnet sich nicht

Die Karte öffnet sich nur bei verifizierten Besuchern und nur, wenn der Agent Daten ansehen darf. Ihr Server muss bei der Signaturprüfung den vollen Pfad (einschließlich des Pfads Ihrer Adresse) verwenden.