Vissza az irányítópultra

Dokumentáció

Ismerd meg az Asyntai használatát

API-referencia

Hozz létre egyéni integrációkat az Asyntai REST API segítségével

API-kulcs megszerzése

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
Starter100 000
Standard500 000
Pro2 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.