API-referencia
Hozz létre egyéni integrációkat az Asyntai REST API segítségével
Fizetős csomag szükséges: Az API-hozzáférés elérhető a Starter, Standard és Pro csomagokban. Árak megtekintése
Áttekintés
Az Asyntai API lehetővé teszi az AI-alapú ügyfélszolgálat integrálását bármely alkalmazásba. Küldj üzeneteket és fogadj intelligens válaszokat, amelyek a weboldal tartalmára és tudásbázisodra épülnek.
Hitelesítés
Minden API-kérés hitelesítést igényel az API-kulcsod használatával. Az API-kulcsodat az API-beállítások oldalon szerezheted meg.
Add meg az API-kulcsot a kérésekben az alábbi módszerek egyikével:
- Authorization fejléc (ajánlott):
Authorization: Bearer YOUR_API_KEY - X-API-Key fejléc:
X-API-Key: YOUR_API_KEY
Tartsd titokban az API-kulcsodat. Bárki, aki rendelkezik a kulcsoddal, hozzáférhet a fiókodhoz az API-n keresztül. Soha ne tedd közzé kliensoldali kódban.
Alap URL
https://asyntai.com/api/v1/
Végpontok
POST /chat/
Küldj üzenetet és fogadj AI által generált választ.
Kérés törzse
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
message |
string | Igen | A felhasználó AI-nak küldött üzenete |
session_id |
string | Nem | A beszélgetés egyedi azonosítója. Ugyanazt a session_id értéket használd a beszélgetési előzmények megőrzéséhez. |
website_id |
integer | Nem | Konkrét weboldal-azonosító. Ha nincs megadva, az elsődleges weboldalt használja. |
Válasz
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Példa (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"}'
Példa (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"])
Példa (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/
Az összes weboldal listázása, amely a fiókodhoz kapcsolódik.
Válasz
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Példa (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Egy adott munkamenet beszélgetési előzményeinek lekérése.
Lekérdezési paraméterek
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
session_id |
string | Igen | A munkamenet-azonosító, amelyhez az előzményeket le kell kérni |
limit |
integer | Nem | Visszaadandó üzenetek maximuma (alapértelmezett: 50, maximum: 100) |
Válasz
{
"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"
}
]
}
Példa (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Listázd a legutóbbi chat-munkameneteidet. Ezzel felfedezheted a munkamenet-azonosítókat, amelyeket átadhatsz a /conversations/ végpontnak a teljes üzenettörténet lekéréséhez.
Lekérdezési paraméterek
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
limit |
integer | Nem | Visszaadandó munkamenetek száma (alapértelmezett: 20, maximum: 100) |
website_id |
string | Nem | Munkamenetek szűrése adott weboldal-azonosító alapján |
source |
string | Nem | Szűrés munkamenet forrás szerint: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Válasz
{
"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"
}
]
}
Példa (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Gyűjtött érdeklődők lekérése — a látogatók által a chat-beszélgetések során megadott e-mail-címek és telefonszámok.
Lekérdezési paraméterek
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
limit |
integer | Nem | Visszaadandó érdeklődők száma (alapértelmezett: 50, max: 100) |
website_id |
string | Nem | Érdeklődők szűrése adott weboldal-azonosító alapján |
Válasz
{
"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"
}
]
}
| Mező | Típus | Leírás |
|---|---|---|
session_id |
string | A chat munkamenet azonosítója. Adja át a /conversations/-nak a teljes chat előzmények megtekintéséhez. |
email |
karakterlánc vagy null | A látogató által megadott e-mail-cím, vagy null ha nem lett gyűjtve |
phone |
karakterlánc vagy null | A látogató által megadott telefonszám, vagy null ha nem lett gyűjtve |
page_url |
karakterlánc vagy null | Az oldal URL-je, ahol a látogató csevegett |
started_at |
string | ISO 8601 időbélyeg a chat munkamenet kezdetéről |
Példa (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Példa (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/
Fiókadataid és használati statisztikáid lekérése.
Válasz
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Példa (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Több weboldal? A tudásbázis-végpontok alapértelmezés szerint az elsődleges weboldaladat használják. Ha több weboldallal rendelkezel, add át a következőt: website_id egy adott kiválasztásához. A weboldal-azonosítókat megtalálhatod a GET /websites/.
Napi feltöltési korlátok: A tudásbázis-feltöltések (szöveg, URL, táblázat) napi karakterkorlátnak vannak alávetve a csomagtól függően. Ez az összes tudásbázis-végponton naponta feltöltött teljes tartalomra vonatkozik.
| Csomag | Karakter/nap |
|---|---|
| Starter | 100 000 |
| Standard | 500 000 |
| Pro | 2 000 000 |
GET /knowledge/
A tudásbázis-bejegyzések listázása. Ezek azok a tartalomforrások, amelyeket az AI chatbot a kérdések megválaszolásához használ.
Lekérdezési paraméterek
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
limit |
integer | Nem | Visszaadandó bejegyzések száma (alapértelmezett: 50, maximum: 100) |
website_id |
string | Nem | Szűrés weboldal-azonosító alapján (alapértelmezett: az elsődleges weboldal) |
Válasz
{
"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"
}
]
}
Példa (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Adj hozzá egyéni szöveges tartalmat a tudásbázisodhoz. Az AI ezt fogja felhasználni a látogatói kérdések megválaszolásához.
Kérés törzse
{
"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"
}
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
title |
string | Igen | Cím ehhez a tudásbázis-bejegyzéshez |
content |
string | Igen | A szöveges tartalom (minimum 10 karakter) |
website_id |
string | Nem | Célweboldal (alapértelmezett: az elsődleges weboldal) |
Válasz
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Példa (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/
Adj hozzá egy weboldalt a tudásbázisodhoz. A tartalmat automatikusan lekéri és kinyeri a rendszer.
Kérés törzse
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
url |
string | Igen | Az URL, amelyről a tartalmat le kell kérni |
website_id |
string | Nem | Célweboldal (alapértelmezett: az elsődleges weboldal) |
Válasz
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Példa (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/
Tölts fel egy CSV vagy Excel (.xlsx) táblázatot a tudásbázisodhoz. Minden sor külön tudásbázis-bejegyzés lesz, ami ideális termékkatalógusokhoz, GYIK-listákhoz, ártáblázatokhoz és könyvtárakhoz.
Kérés
Küldje multipart/form-data formátumban (fájlfeltöltés), ne JSON-ként.
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
file |
fájl | Igen | Egy .csv vagy .xlsx fájl. Az első sornak oszlopfejléceknek kell lennie. Feltöltésenkénti maximális sorok: Starter 500, Standard 2 000, Pro 10 000. A felesleges sorokat a rendszer levágja. |
website_id |
string | Nem | Célweboldal (alapértelmezett: az elsődleges weboldal) |
Válasz
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Példa (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Tudásbázis-bejegyzés törlése. Az id a GET /knowledge/ válaszban található.
Válasz
{
"success": true,
"message": "Knowledge base entry deleted"
}
Példa (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Tipp: A webhookokat a következő helyről is kezelheted: API-beállítások oldal kód írása nélkül.
GET /webhooks/
A regisztrált webhookjaid listázása.
Válasz
{
"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"
}
]
}
Példa (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Regisztrálj egy új webhookot a valós idejű eseményértesítések fogadásához.
Elérhető események
| Esemény | Leírás |
|---|---|
message.received |
Egy látogató üzenetet küldött és választ kapott |
conversation.started |
Új chat-munkamenet indult |
escalation.requested |
Az AI eszkalációt kezdeményezett egy emberi ügynökhöz |
takeover.started |
Egy emberi ügynök átvette a chat-munkamenetet |
Kérés törzse
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
url |
string | Igen | A HTTPS URL a webhook POST kérések fogadásához |
events |
tömb | Igen | Az előfizetendő események listája (lásd a fenti táblázatot) |
website_id |
string | Nem | Célweboldal (alapértelmezett: az elsődleges weboldal) |
Válasz
{
"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"
}
}
Webhookok ellenőrzése: Minden webhook tartalmaz egy secret (csak létrehozáskor látható). Minden URL-re küldött POST tartalmaz egy X-Webhook-Signature fejlécet – a kéréstörzs HMAC-SHA256 aláírása a titkos kulcsoddal.
Példa (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}/
Webhook törlése. Az id a GET /webhooks/ válaszban található.
Válasz
{
"success": true,
"message": "Webhook deleted"
}
Példa (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Hibaválaszok
Minden hibaválasz ezt a formátumot követi:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Állapotkód | Leírás |
|---|---|
400 |
Rossz kérés – Érvénytelen paraméterek vagy hiányzó kötelező mezők |
401 |
Jogosulatlan – Érvénytelen vagy hiányzó API-kulcs |
429 |
Túl sok kérés – Elérted a csomagod üzenetkorlátját |
503 |
Szolgáltatás nem elérhető – Az AI-szolgáltatás átmenetileg nem elérhető |
Forgalmi korlátok
Az API-használatot az előfizetési csomag korlátozza:
- Free: 100 üzenet/hó
- Starter (39$/hó): 2 500 üzenet/hó
- Standard (139$/hó): 15 000 üzenet/hó
- Pro (449$/hó): 50 000 üzenet/hó
Segítségre van szükséged?
Ha bármilyen kérdésed van vagy problémába ütközöl, lépj kapcsolatba velünk a hello@asyntai.com e-mail-címen.