Wenn Du Entwickler bist und die Funktionen von AllAI in eine mobile Anwendung, ein benutzerdefiniertes CRM, ein internes Dashboard oder ein anderes System integrieren möchtest, ist unsere REST-API Dein Werkzeug. Dieser Leitfaden deckt alles ab, was Du benötigst: von der Authentifizierung und den wichtigsten Endpunkten bis hin zu Webhooks, Codebeispielen und Best Practices.

REST API Übersicht

Die AllAI-API folgt den Standard-REST-Prinzipien:

  • Basis-URL: https://api.allai.ro/v2/
  • Format: JSON für Anfragen und Antworten
  • Versionierung: Die aktuelle Version ist v2 (v1 bleibt aktiv für Rückwärtskompatibilität)
  • HTTPS erforderlich: Alle Anfragen müssen über HTTPS erfolgen
  • Encoding: UTF-8

Die vollständige interaktive Dokumentation (Swagger/OpenAPI) ist verfügbar unter https://api.allai.ro/docs.

Authentifizierung (API-Schlüssel)

Alle API-Anfragen erfordern eine Authentifizierung über einen API-Schlüssel. Hier ist, wie Du den Schlüssel erhältst und verwendest:

API-Schlüssel erhalten

  1. Gehe zu Dashboard AllAI > Einstellungen > API
  2. Klicke auf „Neuen API-Schlüssel generieren"
  3. Benenne den Schlüssel (z.B. „Mobile App Produktion")
  4. Wähle die Berechtigungen (lesen, schreiben, admin)
  5. Kopiere den generierten Schlüssel — er wird nur einmal angezeigt

Verwendung in Anfragen

Übermittle den API-Schlüssel im Header Authorization:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
⚠️ Sicherheit

Expose niemals den API-Schlüssel im Client-Code (JavaScript-Frontend, dekompilierbare mobile Anwendungen). Verwende ihn nur serverseitig. Für Frontend-Integrationen nutze die Sitzungstoken (siehe Abschnitt Sitzungstoken weiter unten).

Sitzungstoken (für Frontend)

Für clientseitige Integrationen generiere ein Sitzungstoken aus Deinem Backend:

POST /v2/auth/session-token
{
    "chatbot_id": "cb_abc123",
    "visitor_id": "visitor_xyz",
    "expires_in": 3600
}

// Antwort:
{
    "session_token": "st_live_...",
    "expires_at": "2026-01-19T15:30:00Z"
}

Das Sitzungstoken hat eingeschränkte Berechtigungen (nur Konversation) und läuft automatisch ab.

Wichtige Endpunkte

/conversations — Verwaltung von Konversationen

// Auflisten von Konversationen
GET /v2/conversations?status=active&limit=50&offset=0

// Konversationsdetails
GET /v2/conversations/{conversation_id}

// Neue Konversation erstellen
POST /v2/conversations
{
    "chatbot_id": "cb_abc123",
    "visitor": {
        "name": "Ion Popescu",
        "email": "ion@exemplu.ro"
    },
    "channel": "api",
    "metadata": {
        "source": "mobile_app",
        "page": "/produse/laptop-x"
    }
}

// Konversation schließen
PATCH /v2/conversations/{conversation_id}
{
    "status": "closed",
    "resolution": "resolved_by_bot"
}

/messages — Nachrichten senden und empfangen

// Nachricht in Konversation senden
POST /v2/conversations/{conversation_id}/messages
{
    "content": "Guten Tag, ich möchte Informationen über das Produkt X",
    "role": "visitor",
    "type": "text"
}

// Antwort (inklusive der AI-Antwort):
{
    "visitor_message": {
        "id": "msg_001",
        "content": "Guten Tag, ich möchte Informationen über das Produkt X",
        "timestamp": "2026-01-19T10:30:00Z"
    },
    "bot_response": {
        "id": "msg_002",
        "content": "Guten Tag! Das Produkt X ist verfügbar...",
        "confidence": 0.94,
        "sources": ["kb_article_15", "kb_article_23"],
        "timestamp": "2026-01-19T10:30:01Z"
    }
}

// Nachrichten aus der Konversation auflisten
GET /v2/conversations/{conversation_id}/messages?limit=100

/contacts — Kontaktmanagement

// Kontakte auflisten
GET /v2/contacts?search=ion@exemplu.ro

// Kontakt erstellen
POST /v2/contacts
{
    "name": "Ion Popescu",
    "email": "ion@exemplu.ro",
    "phone": "+40722123456",
    "tags": ["lead", "interesat-produs-x"],
    "custom_fields": {
        "companie": "SRL Exemplu",
        "industrie": "einzelhandel"
    }
}

// Kontakt aktualisieren
PUT /v2/contacts/{contact_id}

// Konversationshistorie eines Kontakts
GET /v2/contacts/{contact_id}/conversations

/analytics — Daten und Berichte

// Allgemeine Statistiken
GET /v2/analytics/overview?period=30d

// Antwort:
{
    "total_conversations": 1847,
    "resolution_rate": 0.82,
    "avg_response_time_ms": 680,
    "satisfaction_score": 4.3,
    "top_topics": [
        {"topic": "preise", "count": 312},
        {"topic": "lieferung", "count": 287},
        {"topic": "rückgabe", "count": 156}
    ],
    "conversations_by_channel": {
        "website": 1203,
        "whatsapp": 412,
        "messenger": 232
    }
}

// Konversationen pro Tag
GET /v2/analytics/conversations?period=30d&granularity=day

// Zufriedenheitsbericht
GET /v2/analytics/satisfaction?period=30d

Webhooks: Echtzeit-Benachrichtigungen

Webhooks senden HTTP POST-Benachrichtigungen an Deine URL, jedes Mal wenn ein Ereignis eintritt. Sie sind entscheidend für reaktive Integrationen.

Webhook-Konfiguration

POST /v2/webhooks
{
    "url": "https://api.dein-sitz.de/allai-webhook",
    "events": [
        "conversation.started",
        "conversation.ended",
        "message.received",
        "lead.created",
        "handoff.requested"
    ],
    "secret": "webhook_secret_zur_verifizierung"
}

Verfügbare Ereignisse

  • conversation.started — Eine neue Konversation hat begonnen
  • conversation.ended — Eine Konversation wurde geschlossen
  • message.received — Eine neue Nachricht vom Besucher
  • message.sent — Der Chatbot hat eine Antwort gesendet
  • lead.created — Ein neuer Lead wurde identifiziert
  • lead.qualified — Ein Lead wurde automatisch qualifiziert
  • handoff.requested — Der Chatbot fordert die Übergabe an einen menschlichen Agenten an
  • satisfaction.rated — Der Kunde hat eine Zufriedenheitsbewertung abgegeben

Signaturverifizierung

Jeder Webhook enthält einen Header X-AllAI-Signature zur Verifizierung:

// Verifizierung in Node.js
const crypto = require('crypto');
const signature = req.headers['x-allai-signature'];
const hash = crypto.createHmac('sha256', WEBHOOK_SECRET)
    .update(JSON.stringify(req.body))
    .digest('hex');

if (signature === hash) {
    // Webhook gültig, verarbeiten
} else {
    // Webhook ungültig, ablehnen
}
💡 Profi-Tipp

Konfiguriere die Webhooks so, dass sie schnell (unter 5 Sekunden) den Status 200 zurückgeben und verarbeite die Daten asynchron. Wenn Dein Endpunkt nicht innerhalb von 30 Sekunden antwortet, wird AllAI dreimal mit exponentiellem Backoff erneut versuchen.

Codebeispiele

JavaScript (Node.js)

const axios = require('axios');

const allai = axios.create({
    baseURL: 'https://api.allai.ro/v2',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
});

// Sende eine Nachricht und erhalte die AI-Antwort
async function sendMessage(conversationId, message) {
    const response = await allai.post(
        `/conversations/${conversationId}/messages`,
        {
            content: message,
            role: 'visitor',
            type: 'text'
        }
    );
    return response.data.bot_response;
}

// Hole die Analytik der letzten 30 Tage
async function getAnalytics() {
    const response = await allai.get('/analytics/overview', {
        params: { period: '30d' }
    });
    return response.data;
}

Python

import requests

API_KEY = 'YOUR_API_KEY'
BASE_URL = 'https://api.allai.ro/v2'
HEADERS = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

# Neue Konversation erstellen
def create_conversation(chatbot_id, visitor_name, visitor_email):
    response = requests.post(
        f'{BASE_URL}/conversations',
        headers=HEADERS,
        json={
            'chatbot_id': chatbot_id,
            'visitor': {
                'name': visitor_name,
                'email': visitor_email
            },
            'channel': 'api'
        }
    )
    return response.json()

# Alle aktiven Konversationen abrufen
def get_active_conversations():
    response = requests.get(
        f'{BASE_URL}/conversations',
        headers=HEADERS,
        params={'status': 'active', 'limit': 50}
    )
    return response.json()

PHP

<?php
$apiKey = 'YOUR_API_KEY';
$baseUrl = 'https://api.allai.ro/v2';

// Hilfsfunktion für API-Anfragen
function allaiRequest($method, $endpoint, $data = null) {
    global $apiKey, $baseUrl;

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $baseUrl . $endpoint);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json'
    ]);

    if ($method === 'POST') {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }

    $response = curl_exec($ch);
    curl_close($ch);
    return json_decode($response, true);
}

// Kontakte auflisten
$contacts = allaiRequest('GET', '/contacts?limit=100');

// Lead aus Formular erstellen
$newLead = allaiRequest('POST', '/contacts', [
    'name' => 'Maria Popescu',
    'email' => 'maria@exemplu.ro',
    'tags' => ['lead', 'formular-contact']
]);
?>

Ratenlimits und Best Practices

Request-Limits

  • Professional-Plan: 1.000 Anfragen/Minute
  • Enterprise-Plan: 5.000 Anfragen/Minute
  • White-Label-Plan: 10.000 Anfragen/Minute

Die Antworten enthalten Header zur Überwachung der Limits:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1706097600

Best Practices

  1. Implementiere Retry mit exponentiellem Backoff — Bei Fehlern 429 (Zu viele Anfragen) oder 5xx, warte und versuche es erneut mit zunehmenden Intervallen.
  2. Verwende Paginierung — Für große Listen, verwende limit und offset, anstatt alle Ergebnisse auf einmal anzufordern.
  3. Cache statische Daten — Die Konfiguration des Chatbots, die Liste der Integrationen und andere Daten, die sich nicht häufig ändern.
  4. Validiere Webhooks — Überprüfe immer die Signatur X-AllAI-Signature, bevor Du die Daten verarbeitest.
  5. Fehler verwalten — Die API gibt Standard-HTTP-Codes (400, 401, 403, 404, 429, 500) mit beschreibenden Nachrichten zurück.
  6. Verwende spezifische Felder — Der Parameter fields ermöglicht die Auswahl nur der benötigten Felder, wodurch die Payload reduziert wird.
⚠️ Wichtig

Speichere API-Schlüssel nicht in öffentlichen Git-Repositories. Verwende Umgebungsvariablen (.env) oder einen Secrets-Manager. Wenn ein API-Schlüssel kompromittiert wird, widerrufe ihn sofort im Dashboard und generiere einen neuen.

Verfügbare SDKs

Wir bieten offizielle SDKs an, um die Integration zu beschleunigen:

  • JavaScript/Node.js — npm install @allai/sdk
  • Python — pip install allai-sdk
  • PHP — composer require allai/sdk

Die SDKs beinhalten:

  • Wrapper für alle API-Endpunkte
  • Automatische Verwaltung von Ratenlimits und Retries
  • TypeScript-Typen für Autovervollständigung
  • Automatische Überprüfung der Webhook-Signatur
  • Integriertes Logging für Debugging

Häufige Anwendungsfälle

Integration in mobile Anwendung

Du schaffst ein natives Chat-Erlebnis in Deiner mobilen Anwendung (iOS/Android). Dein Backend kommuniziert mit der AllAI-API, und das Frontend zeigt die Konversation in einer benutzerdefinierten Oberfläche an.

Integration in benutzerdefiniertes CRM

Dein Unternehmen hat ein intern entwickeltes CRM. Die Webhooks von AllAI senden die Daten der Konversationen direkt in Dein CRM, ohne auf vordefinierte Integrationen angewiesen zu sein.

Benutzerdefiniertes Dashboard

Du baust ein internes Dashboard, das Daten von AllAI mit anderen Quellen (Verkäufe, Marketing, Support) kombiniert. Der Endpunkt /analytics liefert die benötigten Daten.

Komplexe Automatisierungen

Du erstellst komplexe Abläufe: Lagerbestandsprüfung im ERP, dynamische Preisberechnung, PDF-Angebotserstellung — alles ausgelöst durch die Konversation des Chatbots über Webhooks.

Sandbox zum Testen

Die Sandbox-Umgebung ermöglicht das Testen der Integration, ohne die Produktionsdaten zu beeinträchtigen:

  • Basis-URL Sandbox: https://sandbox.api.allai.ro/v2/
  • API-Schlüssel Sandbox: Separat im Dashboard > Einstellungen > API > Tab Sandbox generieren
  • Testdaten: Vorgefertigte fiktive Kontakte und Konversationen
  • Keine Kosten: Sandbox-Anfragen werden nicht gezählt
  • Reduziertes Ratenlimit: 100 Anfragen/Minute (ausreichend für Tests)
💡 Profi-Tipp

Entwickle und teste immer in der Sandbox, bevor Du in die Produktion gehst. Verwende Umgebungsvariablen, um einfach zwischen sandbox.api.allai.ro und api.allai.ro zu wechseln.

Entwicklersupport

Wenn Du Fragen hast oder Probleme mit der API auftritt:

  • Interaktive Dokumentation: https://api.allai.ro/docs
  • Statusseite: https://status.allai.ro zur Überwachung der Verfügbarkeit
  • Technischer Support per E-Mail: dev@allai.ro
  • Discord-Community: Trete dem Kanal #developers bei

Bist Du bereit, AllAI in Dein Projekt zu integrieren? Generiere einen API-Schlüssel aus dem Dashboard und beginne mit der Sandbox. Oder wenn Du Unterstützung bei der Architektur der Integration benötigst, vereinbare eine technische Sitzung mit unserem Entwicklerteam.