API-Referenz

Erstellen Sie individuelle Integrationen mit der Asyntai REST API

API-Schlüssel erhalten

Kostenpflichtiger Tarif erforderlich: API-Zugang ist in den Starter-, Standard- und Pro-Tarifen verfügbar. Preise ansehen

Übersicht

Die Asyntai API ermöglicht es Ihnen, KI-gestützten Kundensupport in jede Anwendung zu integrieren. Senden Sie Nachrichten und erhalten Sie intelligente Antworten, die auf Ihren Website-Inhalten und Ihrer Wissensdatenbank trainiert sind.

Authentifizierung

Alle API-Anfragen erfordern eine Authentifizierung mit Ihrem API-Schlüssel. Sie können Ihren API-Schlüssel auf der Seite API-Einstellungen erhalten.

Fügen Sie Ihren API-Schlüssel in Anfragen mit einer dieser Methoden ein:

  • Authorization-Header (empfohlen): Authorization: Bearer YOUR_API_KEY
  • X-API-Key-Header: X-API-Key: YOUR_API_KEY

Halten Sie Ihren API-Schlüssel geheim. Jeder mit Ihrem Schlüssel kann über die API auf Ihr Konto zugreifen. Geben Sie ihn niemals in clientseitigem Code preis.

Basis-URL

https://asyntai.com/api/v1/

Endpunkte

POST /chat/

Senden Sie eine Nachricht und erhalten Sie eine KI-generierte Antwort.

Anfragekörper

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}
Parameter Typ Erforderlich Beschreibung
message string Ja Die Nachricht des Benutzers, die an die KI gesendet wird
session_id string Nein Eindeutige Kennung für die Konversation. Verwenden Sie dieselbe session_id, um den Gesprächsverlauf beizubehalten.
website_id integer Nein Spezifische Website-ID. Wenn nicht angegeben, wird Ihre primäre Website verwendet.

Antwort

{
  "success": true,
  "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
  "session_id": "user_123"
}

Beispiel (cURL)

curl -X POST https://asyntai.com/api/v1/chat/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your business hours?", "session_id": "user_123"}'

Beispiel (Python)

import requests

response = requests.post(
    "https://asyntai.com/api/v1/chat/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "message": "What are your business hours?",
        "session_id": "user_123"
    }
)

data = response.json()
print(data["response"])

Beispiel (JavaScript)

const response = await fetch("https://asyntai.com/api/v1/chat/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    session_id: "user_123"
  })
});

const data = await response.json();
console.log(data.response);

GET /websites/

Alle mit Ihrem Konto verknüpften Websites auflisten.

Antwort

{
  "success": true,
  "websites": [
    {
      "id": 1,
      "name": "My Website",
      "domain": "example.com",
      "is_primary": true
    }
  ]
}

Beispiel (cURL)

curl https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /conversations/

Konversationsverlauf für eine bestimmte Sitzung abrufen.

Abfrageparameter

Parameter Typ Erforderlich Beschreibung
session_id string Ja Die Sitzungs-ID, für die der Verlauf abgerufen werden soll
limit integer Nein Maximale Anzahl zurückzugebender Nachrichten (Standard: 50, Max: 100)

Antwort

{
  "success": true,
  "session_id": "user_123",
  "messages": [
    {
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "timestamp": "2024-01-15T10:30:01Z"
    }
  ]
}

Beispiel (cURL)

curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /sessions/

Listen Sie Ihre letzten Chat-Sitzungen auf. Verwenden Sie dies, um Sitzungs-IDs zu finden, die Sie dann an /conversations/ übergeben können, um den vollständigen Nachrichtenverlauf abzurufen.

Abfrageparameter

Parameter Typ Erforderlich Beschreibung
limit integer Nein Anzahl der zurückzugebenden letzten Sitzungen (Standard: 20, Max: 100)
website_id string Nein Sitzungen nach einer bestimmten Website-ID filtern
source string Nein Nach Sitzungsquelle filtern: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier

Antwort

{
  "success": true,
  "sessions": [
    {
      "session_id": "session_abc123def",
      "source": "widget",
      "message_count": 5,
      "first_message": "What are your business hours?",
      "first_message_at": "2024-01-15T10:30:00Z",
      "last_message_at": "2024-01-15T10:35:00Z",
      "website_domain": "example.com"
    }
  ]
}

Beispiel (cURL)

curl "https://asyntai.com/api/v1/sessions/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /leads/

Gesammelte Leads abrufen — E-Mail-Adressen und Telefonnummern, die von Besuchern während Chat-Gesprächen übermittelt wurden.

Abfrageparameter

Parameter Typ Erforderlich Beschreibung
limit integer Nein Anzahl der zurückzugebenden Leads (Standard: 50, Max: 100)
website_id string Nein Leads nach einer bestimmten Website-ID filtern

Antwort

{
  "success": true,
  "leads": [
    {
      "session_id": "session_abc123def",
      "email": "visitor@example.com",
      "phone": "+1234567890",
      "page_url": "https://example.com/pricing",
      "started_at": "2024-01-15T10:30:00Z"
    }
  ]
}
Feld Typ Beschreibung
session_id string Die Chat-Sitzungs-ID. Übergeben Sie diese an /conversations/, um den vollständigen Chatverlauf zu sehen.
email String oder null Vom Besucher angegebene E-Mail-Adresse, oder null wenn nicht erfasst
phone String oder null Vom Besucher angegebene Telefonnummer, oder null wenn nicht erfasst
page_url String oder null Die Seiten-URL, auf der der Besucher gechattet hat
started_at string ISO 8601 Zeitstempel des Chat-Sitzungsbeginns

Beispiel (cURL)

curl "https://asyntai.com/api/v1/leads/?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Beispiel (Python)

import requests

response = requests.get(
    "https://asyntai.com/api/v1/leads/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 20}
)

leads = response.json()["leads"]
for lead in leads:
    print(f"{lead['email'] or ''} | {lead['phone'] or ''}")

GET /account/

Ihre Kontoinformationen und Nutzungsstatistiken abrufen.

Antwort

{
  "success": true,
  "account": {
    "email": "you@example.com",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 2500
  }
}

Beispiel (cURL)

curl https://asyntai.com/api/v1/account/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Mehrere Websites? Wissensdatenbank-Endpunkte verwenden standardmäßig Ihre primäre Website. Wenn Sie mehrere Websites haben, übergeben Sie website_id um eine bestimmte auszuwählen. Sie finden Ihre Website-IDs mit GET /websites/.

Tägliche Upload-Limits: Wissensdatenbank-Uploads (Text, URL, Tabellenkalkulation) unterliegen einem täglichen Zeichenlimit basierend auf Ihrem Plan. Dies gilt für den gesamten Inhalt, der pro Tag über alle Wissensdatenbank-Endpunkte hochgeladen wird.

Plan Zeichen/Tag
Starter100.000
Standard500.000
Pro2.000.000

GET /knowledge/

Listen Sie Ihre Wissensdatenbank-Einträge auf. Dies sind die Inhaltsquellen, die Ihr KI-Chatbot zur Beantwortung von Fragen verwendet.

Abfrageparameter

Parameter Typ Erforderlich Beschreibung
limit integer Nein Anzahl der zurückzugebenden Einträge (Standard: 50, Max: 100)
website_id string Nein Nach Website-ID filtern (Standard ist Ihre primäre Website)

Antwort

{
  "success": true,
  "entries": [
    {
      "id": "abc-123-def",
      "type": "text",
      "title": "Business Hours",
      "description": "Manual text content (150 words)",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ghi-456-jkl",
      "type": "url",
      "title": "About Us - Example",
      "description": "Content from https://example.com/about",
      "created_at": "2024-01-14T09:00:00Z"
    }
  ]
}

Beispiel (cURL)

curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /knowledge/text/

Fügen Sie benutzerdefinierten Textinhalt zu Ihrer Wissensdatenbank hinzu. Die KI wird diesen verwenden, um Besucherfragen zu beantworten.

Anfragekörper

{
  "title": "Return Policy",
  "content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
  "website_id": "123"
}
Parameter Typ Erforderlich Beschreibung
title string Ja Ein Titel für diesen Wissensdatenbank-Eintrag
content string Ja Der Textinhalt (mindestens 10 Zeichen)
website_id string Nein Zielwebsite (Standard ist Ihre primäre Website)

Antwort

{
  "success": true,
  "id": "abc-123-def",
  "title": "Return Policy",
  "chunks_created": 1
}

Beispiel (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'

POST /knowledge/url/

Fügen Sie eine Webseite zu Ihrer Wissensdatenbank hinzu. Der Inhalt wird automatisch abgerufen und extrahiert.

Anfragekörper

{
  "url": "https://example.com/faq",
  "website_id": "123"
}
Parameter Typ Erforderlich Beschreibung
url string Ja Die URL, von der der Inhalt abgerufen werden soll
website_id string Nein Zielwebsite (Standard ist Ihre primäre Website)

Antwort

{
  "success": true,
  "id": "abc-123-def",
  "title": "FAQ - Example",
  "url": "https://example.com/faq",
  "chunks_created": 5
}

Beispiel (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/faq"}'

POST /knowledge/spreadsheet/

Laden Sie eine CSV- oder Excel-Tabelle (.xlsx) in Ihre Wissensdatenbank hoch. Jede Zeile wird zu einem separaten Wissensdatenbank-Eintrag – ideal für Produktkataloge, FAQ-Listen, Preistabellen und Verzeichnisse.

Anfrage

Als multipart/form-data (Datei-Upload) senden, nicht als JSON.

Parameter Typ Erforderlich Beschreibung
file Datei Ja Eine .csv- oder .xlsx-Datei. Die erste Zeile muss Spaltenüberschriften enthalten. Maximale Zeilen pro Upload: Starter 500, Standard 2.000, Pro 10.000. Überschüssige Zeilen werden abgeschnitten.
website_id string Nein Zielwebsite (Standard ist Ihre primäre Website)

Antwort

{
  "success": true,
  "id": "abc-123-def",
  "title": "products.csv",
  "rows_processed": 15,
  "chunks_created": 15
}

Beispiel (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@products.csv"

DELETE /knowledge/{id}/

Einen Wissensdatenbank-Eintrag löschen. Die id finden Sie in der Antwort von GET /knowledge/.

Antwort

{
  "success": true,
  "message": "Knowledge base entry deleted"
}

Beispiel (cURL)

curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tipp: Sie können Webhooks auch über die API-Einstellungen Seite verwalten, ohne Code zu schreiben.

GET /webhooks/

Ihre registrierten Webhooks auflisten.

Antwort

{
  "success": true,
  "webhooks": [
    {
      "id": "abc-123-def",
      "url": "https://example.com/webhook",
      "events": ["message.received", "escalation.requested"],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Beispiel (cURL)

curl "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /webhooks/

Registrieren Sie einen neuen Webhook, um Echtzeit-Ereignisbenachrichtigungen zu erhalten.

Verfügbare Ereignisse

Ereignis Beschreibung
message.received Ein Besucher hat eine Nachricht gesendet und eine Antwort erhalten
conversation.started Eine neue Chat-Sitzung wurde gestartet
escalation.requested Die KI hat eine Eskalation an einen menschlichen Agenten ausgelöst
takeover.started Ein menschlicher Agent hat eine Chat-Sitzung übernommen

Anfragekörper

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}
Parameter Typ Erforderlich Beschreibung
url string Ja Die HTTPS-URL zum Empfangen von Webhook-POST-Anfragen
events Array Ja Liste der Ereignisse, die abonniert werden sollen (siehe Tabelle oben)
website_id string Nein Zielwebsite (Standard ist Ihre primäre Website)

Antwort

{
  "success": true,
  "webhook": {
    "id": "abc-123-def",
    "url": "https://example.com/webhook",
    "events": ["message.received", "escalation.requested"],
    "secret": "whsec_abc123...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Webhooks verifizieren: Jeder Webhook enthält ein secret (wird nur bei der Erstellung angezeigt). Jeder POST an Ihre URL enthält ein X-Webhook-Signature Header — ein HMAC-SHA256 des Anfragetexts, signiert mit Ihrem Geheimnis.

Beispiel (cURL)

curl -X POST "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["message.received"]}'

DELETE /webhooks/{id}/

Einen Webhook löschen. Die id finden Sie in der Antwort von GET /webhooks/.

Antwort

{
  "success": true,
  "message": "Webhook deleted"
}

Beispiel (cURL)

curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Fehlerantworten

Alle Fehlerantworten folgen diesem Format:

{
  "success": false,
  "error": "Error message describing what went wrong"
}
Statuscode Beschreibung
400 Bad Request – Ungültige Parameter oder fehlende Pflichtfelder
401 Unauthorized – Ungültiger oder fehlender API-Schlüssel
429 Too Many Requests – Nachrichtenlimit für Ihren Tarif erreicht
503 Service Unavailable – KI-Dienst vorübergehend nicht verfügbar

Ratenbegrenzungen

Die API-Nutzung ist durch Ihren Abonnementplan begrenzt:

  • Free: 100 Nachrichten/Monat
  • Starter (39 $/Monat): 2.500 Nachrichten/Monat
  • Standard (139 $/Monat): 15.000 Nachrichten/Monat
  • Pro (449 $/Monat): 50.000 Nachrichten/Monat

Brauchen Sie Hilfe?

Wenn Sie Fragen haben oder auf Probleme stoßen, kontaktieren Sie uns unter hello@asyntai.com.