API-Referenz
Erstellen Sie individuelle Integrationen mit der Asyntai REST API
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 |
|---|---|
| Starter | 100.000 |
| Standard | 500.000 |
| Pro | 2.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.