API-Integration

Übertragen Sie Daten programmgesteuert in Ihre AI SmartTalk-Wissensdatenbank mithilfe unserer REST API. Ideal für benutzerdefinierte Integrationen, automatisierte Pipelines und jede Datenquelle, die nicht von unseren nativen Konnektoren abgedeckt wird.

---

Übersicht

Die API-Integration ermöglicht Ihnen:

• Dokumente direkt in Ihre Wissensdatenbank zu übertragen
• Inhalte programmgesteuert zu aktualisieren
• Veraltete Einträge zu löschen
• Benutzerdefinierte Datenpipelines zu erstellen
• Integrieren mit jedem System, das HTTP-Anfragen stellen kann

---

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie:

• Ein aktives AI SmartTalk-Konto haben
• API-Zugriff aktiviert ist (prüfen Sie Ihren Plan)
• Grundkenntnisse über REST APIs besitzen
• Ein Werkzeug zum Stellen von HTTP-Anfragen haben (curl, Postman oder Ihren Anwendungscode)

---

Abrufen Ihrer API-Anmeldeinformationen

Schritt 1: Zugriff auf API-Einstellungen

1. Melden Sie sich bei Ihrem AI SmartTalk-Konto an
2. Navigieren Sie zu Einstellungen → Integrationen
3. Finden Sie API und klicken Sie auf Konfigurieren

Schritt 2: API-Token generieren

1. Klicken Sie auf Neues Token generieren
2. Kopieren Sie Ihre Chat Model ID und API-Token
3. Bewahren Sie diese sicher auf – das Token wird nur einmal angezeigt!

⚠️ Sicherheitswarnung: Geben Sie Ihr API-Token niemals im Client-Code oder in öffentlichen Repositories preis.

---

API-Endpunkte

Basis-URL

https://api.aismarttalk.tech/v1

Authentifizierung

Alle Anfragen erfordern Ihr API-Token im Header:

Authorization: Bearer YOUR_API_TOKEN

---

API-Endpunkte

Basis-URL

https://api.aismarttalk.tech/v1

Authentifizierung

Alle Anfragen erfordern Ihr API-Token im Header:

Authorization: Bearer YOUR_API_TOKEN

---

Dokumente importieren

Endpunkt

POST /documents/import

Anfragekörper

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Produktdokumentation",
      "content": "Der vollständige Inhalt Ihres Dokuments kommt hier hin...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parameter

Feld	Typ	Erforderlich	Beschreibung
chatModelId	string	✅	Ihre eindeutige Kennung des Chatmodells
documents	array	✅	Array von Dokumentobjekten
documents[].title	string	✅	Dokumenttitel zur Identifikation
documents[].content	string	✅	Vollständiger Textinhalt
documents[].url	string	❌	Quell-URL (zur Referenz)
documents[].metadata	object	❌	Benutzerdefinierte Schlüssel-Wert-Paare

Antwort

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Produktdokumentation",
      "status": "processing"
    }
  ]
}

Beispiel: cURL

curl -X POST https://api.aismarttalk.tech/v1/documents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatModelId": "your-chat-model-id",
    "documents": [
      {
        "title": "Einsteigerleitfaden",
        "content": "Willkommen auf unserer Plattform. So starten Sie...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Dokumente abfragen

Stellen Sie programmgesteuert Fragen an Ihre Wissensdatenbank.

Endpunkt

POST /chat/query

Anfragekörper

{
  "chatModelId": "your-chat-model-id",
  "query": "Wie setze ich mein Passwort zurück?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Antwort

{
  "success": true,
  "response": "Um Ihr Passwort zurückzusetzen, navigieren Sie zu Einstellungen > Sicherheit > Passwort ändern...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Sicherheitsleitfaden",
      "relevance": 0.95
    }
  ]
}

---

Dokumente abrufen

Holen Sie Dokumente, die einer Abfrage entsprechen (ohne KI-Antwort).

Endpunkt

POST /documents/search

Anfragekörper

{
  "chatModelId": "your-chat-model-id",
  "query": "Passwortsicherheit",
  "limit": 10
}

Antwort

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Sicherheitsbest Practices",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

---

Codebeispiele

Python

import requests

API_TOKEN = "your-api-token"
CHAT_MODEL_ID = "your-chat-model-id"

def import_document(title: str, content: str, url: str = None):
    response = requests.post(
        "https://api.aismarttalk.tech/v1/documents/import",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "chatModelId": CHAT_MODEL_ID,
            "documents": [{
                "title": title,
                "content": content,
                "url": url
            }]
        }
    )
    return response.json()

# Dokument importieren
result = import_document(
    title="FAQ: Versand",
    content="Wir bieten kostenlosen Versand für Bestellungen über 50 $ an...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

JavaScript / Node.js

const API_TOKEN = 'your-api-token';
const CHAT_MODEL_ID = 'your-chat-model-id';

async function importDocument(title, content, url = null) {
  const response = await fetch('https://api.aismarttalk.tech/v1/documents/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatModelId: CHAT_MODEL_ID,
      documents: [{
        title,
        content,
        url
      }]
    })
  });
  return response.json();
}

// Dokument importieren
importDocument(
  'FAQ: Rückgaben',
  'Sie können Artikel innerhalb von 30 Tagen nach dem Kauf zurückgeben...',
  'https://shop.example.com/faq/returns'
).then(console.log);

PHP

<?php
$apiToken = 'your-api-token';
$chatModelId = 'your-chat-model-id';

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'Produktspezifikationen',
            'content' => 'Unser Widget hat die folgenden Spezifikationen...',
            'url' => 'https://example.com/products/widget'
        ]
    ]
];

$ch = curl_init('https://api.aismarttalk.tech/v1/documents/import');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

---

Anwendungsfälle

Integration eines benutzerdefinierten CMS

Inhalte aus einem proprietären CMS synchronisieren:

• An CMS-Veröffentlichungsereignisse anschließen
• Neue/aktualisierte Inhalte an AI SmartTalk übertragen
• Gelöschte Inhalte entfernen

Datenpipeline

Import aus Datenlagern:

• Relevante Daten im JSON-Format exportieren
• Batch-Import über die API
• Regelmäßige Updates planen

E-Commerce-Produkte

Produktdaten aus benutzerdefinierten Systemen synchronisieren:

• Produktbeschreibungen
• Spezifikationen
• Preisinformationen

Interne Systeme

Interne Tools verbinden, die nicht nativ unterstützt werden:

• Benutzerdefinierte Wikis
• Altdatenbanken
• Proprietäre Anwendungen

---

Rate Limits

Endpoint	Rate Limit
Document Import	100 Anfragen/Minute
Query	60 Anfragen/Minute
Search	60 Anfragen/Minute

Hinweis: Die Ratenlimits variieren je nach Plan. Kontaktieren Sie den Support für höhere Limits.

---

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Der bereitgestellte API-Token ist ungültig oder abgelaufen"
  }
}

Common Error Codes

Code	Beschreibung	Lösung
INVALID_TOKEN	Ungültiger oder abgelaufener Token	API-Token neu generieren
INVALID_MODEL_ID	Unbekannte Chat-Modell-ID	Überprüfen Sie Ihre Chat-Modell-ID
RATE_LIMITED	Zu viele Anfragen	Backoff implementieren, später erneut versuchen
INVALID_REQUEST	Fehlformatierter Anfragekörper	JSON-Struktur überprüfen
DOCUMENT_TOO_LARGE	Inhalt überschreitet das Limit	In kleinere Dokumente aufteilen
QUOTA_EXCEEDED	Planlimits erreicht	Upgrade durchführen oder Support kontaktieren

---

Troubleshooting

Authentication Fails

Problem	Lösung
401 Unauthorized	Überprüfen Sie, ob der Token korrekt und aktiv ist
Token funktioniert nicht	Token in den Einstellungen neu generieren
Abgelaufener Token	Token laufen nicht ab, können jedoch widerrufen werden

Import Issues

Problem	Lösung
Leere Antwort	Überprüfen Sie, ob der Content-Type application/json ist
Dokument erscheint nicht	Warten Sie auf die Verarbeitung; überprüfen Sie den Wissensbereich
Teilweiser Import	Einige Dokumente können Validierungsfehler aufweisen

Performance Issues

Problem	Lösung
Langsame Importe	Dokumente in Chargen (max. 100 pro Anfrage) senden
Zeitüberschreitungen	Batch-Größe reduzieren, mit Backoff erneut versuchen
Ratenlimit erreicht	Exponentielles Backoff implementieren

---

Best Practices

1. Batch-Importe: Senden Sie mehrere Dokumente pro Anfrage (bis zu 100)
2. Eindeutige Titel: Verwenden Sie beschreibende, eindeutige Titel für jedes Dokument
3. Strukturierter Inhalt: Gut formatierter Inhalt verbessert die AI-Antworten
4. Metadaten-Tagging: Verwenden Sie Metadaten zur Kategorisierung und Filterung
5. Sichere Tokens: Speichern Sie Tokens in Umgebungsvariablen
6. Fehlerbehandlung: Implementieren Sie eine Wiederholungslogik mit exponentiellem Backoff
7. Nutzung überwachen: Verfolgen Sie API-Aufrufe im Vergleich zu Ihren Planlimits

---

Related Documentation

• Integrations Overview
• Full API Documentation
• Knowledge Base Management
• SmartFlow Webhooks — Ereignisse empfangen