API referenca
Zgradite prilagojene integracije z Asyntai REST API
Zahtevan plačljiv načrt: Dostop do API je na voljo v načrtih Starter, Standard in Pro. Ogled cen
Pregled
API Asyntai vam omogoča, da integrirate podporo strankam z umetno inteligenco v katero koli aplikacijo. Pošljite sporočila in prejemajte inteligentne odgovore, naučene na vsebini vašega spletnega mesta in bazi znanja.
Avtentikacija
Vse zahteve API zahtevajo avtentikacijo z vašim API ključem. Svoj API ključ lahko pridobite na strani Nastavitve API.
Vključite svoj API ključ v zahteve z eno od teh metod:
- Glava Authorization (priporočeno):
Authorization: Bearer YOUR_API_KEY - Glava X-API-Key:
X-API-Key: YOUR_API_KEY
Vaš API ključ naj ostane skrivnost. Kdorkoli z vašim ključem lahko dostopa do vašega računa prek API. Nikoli ga ne izpostavljajte v kodi na strani odjemalca.
Osnovni URL
https://asyntai.com/api/v1/
Končne točke
POST /chat/
Pošljite sporočilo in prejmite odgovor, ustvarjen z UI.
Telo zahteve
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
message |
string | Da | Uporabnikovo sporočilo za pošiljanje UI-ju |
session_id |
string | Ne | Edinstven identifikator za pogovor. Uporabite isti session_id za ohranjanje zgodovine pogovora. |
website_id |
integer | Ne | Specifičen ID spletnega mesta. Če ni naveden, se uporabi vaše primarno spletno mesto. |
Odgovor
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Primer (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"}'
Primer (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"])
Primer (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/
Seznam vseh spletnih mest, povezanih z vašim računom.
Odgovor
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Primer (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Pridobite zgodovino pogovorov za določeno sejo.
Parametri poizvedbe
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
session_id |
string | Da | ID seje, za katero želite pridobiti zgodovino |
limit |
integer | Ne | Največje število sporočil za vrnitev (privzeto: 50, maks.: 100) |
Odgovor
{
"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"
}
]
}
Primer (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Seznam vaših nedavnih sej klepeta. Uporabite to za odkrivanje ID-jev sej, ki jih lahko nato posredujete v /conversations/ za pridobitev celotne zgodovine sporočil.
Parametri poizvedbe
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
limit |
integer | Ne | Število nedavnih sej za vrnitev (privzeto: 20, maks.: 100) |
website_id |
string | Ne | Filtrirajte seje po določenem ID-ju spletnega mesta |
source |
string | Ne | Filtrirajte po viru seje: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Odgovor
{
"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"
}
]
}
Primer (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Pridobi zbrane potencialne stranke — e-poštne naslove in telefonske številke, ki so jih obiskovalci poslali med pogovori v klepetu.
Parametri poizvedbe
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
limit |
integer | Ne | Število potencialnih strank za vrnitev (privzeto: 50, maks: 100) |
website_id |
string | Ne | Filtrirajte potencialne stranke po določenem ID-ju spletnega mesta |
Odgovor
{
"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"
}
]
}
| Polje | Tip | Opis |
|---|---|---|
session_id |
string | ID seje klepeta. Posredujte ga v /conversations/ za ogled celotne zgodovine klepeta. |
email |
niz ali null | E-poštni naslov, ki ga je posredoval obiskovalec, ali null, če ni bil zbran |
phone |
niz ali null | Telefonska številka, ki jo je posredovala obiskovalka, ali null, če ni bila zbrana |
page_url |
niz ali null | URL strani, kjer se je obiskovalec pogovarjal |
started_at |
string | Časovni žig ISO 8601 začetka seje klepeta |
Primer (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Primer (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/
Pridobite informacije o svojem računu in statistiko uporabe.
Odgovor
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Primer (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Več spletnih mest? Končne točke baze znanja privzeto uporabljajo vaše primarno spletno mesto. Če imate več spletnih mest, posredujte website_id za ciljanje določenega. ID-je svojih spletnih mest lahko najdete z uporabo GET /websites/.
Dnevne omejitve nalaganja: Nalaganja v bazo znanja (besedilo, URL, preglednica) so predmet dnevne omejitve znakov glede na vaš načrt. To velja za celotno vsebino, naloženo prek vseh končnih točk baze znanja na dan.
| Načrt | Znakov/dan |
|---|---|
| Starter | 100.000 |
| Standard | 500.000 |
| Pro | 2.000.000 |
GET /knowledge/
Seznam vnosov vaše baze znanja. To so viri vsebine, ki jih vaš klepetalni robot z UI uporablja za odgovarjanje na vprašanja.
Parametri poizvedbe
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
limit |
integer | Ne | Število vnosov za vrnitev (privzeto: 50, maks.: 100) |
website_id |
string | Ne | Filtrirajte po ID-ju spletnega mesta (privzeto vaše primarno spletno mesto) |
Odgovor
{
"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"
}
]
}
Primer (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Dodajte prilagojeno besedilno vsebino v svojo bazo znanja. UI bo to uporabila za odgovarjanje na vprašanja obiskovalcev.
Telo zahteve
{
"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 | Tip | Zahtevano | Opis |
|---|---|---|---|
title |
string | Da | Naslov za ta vnos v bazo znanja |
content |
string | Da | Besedilna vsebina (najmanj 10 znakov) |
website_id |
string | Ne | Ciljno spletno mesto (privzeto vaše primarno spletno mesto) |
Odgovor
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Primer (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/
Dodajte spletno stran v svojo bazo znanja. Vsebina bo samodejno pridobljena in izvlečena.
Telo zahteve
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
url |
string | Da | URL, s katerega se pridobi vsebina |
website_id |
string | Ne | Ciljno spletno mesto (privzeto vaše primarno spletno mesto) |
Odgovor
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Primer (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/
Naložite preglednico CSV ali Excel (.xlsx) v svojo bazo znanja. Vsaka vrstica postane ločen vnos v bazo znanja, idealno za kataloge izdelkov, sezname pogostih vprašanj, cenike in imenike.
Zahteva
Pošljite kot multipart/form-data (nalaganje datoteke), ne JSON.
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
file |
datoteka | Da | Datoteka .csv ali .xlsx. Prva vrstica morajo biti glave stolpcev. Največje število vrstic na nalaganje: Starter 500, Standard 2.000, Pro 10.000. Presežne vrstice so odrezane. |
website_id |
string | Ne | Ciljno spletno mesto (privzeto vaše primarno spletno mesto) |
Odgovor
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Primer (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Izbrišite vnos iz baze znanja. id lahko najdete v odgovoru GET /knowledge/.
Odgovor
{
"success": true,
"message": "Knowledge base entry deleted"
}
Primer (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Nasvet: Webhooke lahko upravljate tudi iz Nastavitve API strani brez pisanja kakršne koli kode.
GET /webhooks/
Seznam vaših registriranih webhookov.
Odgovor
{
"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"
}
]
}
Primer (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Registrirajte nov webhook za prejemanje obvestil o dogodkih v realnem času.
Razpoložljivi dogodki
| Dogodek | Opis |
|---|---|
message.received |
Obiskovalec je poslal sporočilo in prejel odgovor |
conversation.started |
Začeta je bila nova seja klepeta |
escalation.requested |
UI je sprožila eskalacijo na človeškega agenta |
takeover.started |
Človeški agent je prevzel sejo klepeta |
Telo zahteve
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Parameter | Tip | Zahtevano | Opis |
|---|---|---|---|
url |
string | Da | HTTPS URL za prejemanje POST zahtev webhookov |
events |
array | Da | Seznam dogodkov za naročilo (glejte zgornjo tabelo) |
website_id |
string | Ne | Ciljno spletno mesto (privzeto vaše primarno spletno mesto) |
Odgovor
{
"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"
}
}
Preverjanje webhookov: Vsak webhook vključuje secret (prikazano samo ob ustvarjanju). Vsak POST na vaš URL vključuje X-Webhook-Signature glavo — HMAC-SHA256 telesa zahteve, podpisan z vašim tajnim ključem.
Primer (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}/
Izbrišite webhook. id lahko najdete v odgovoru GET /webhooks/.
Odgovor
{
"success": true,
"message": "Webhook deleted"
}
Primer (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Odgovori z napako
Vsi odgovori z napako sledijo temu formatu:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Statusna koda | Opis |
|---|---|
400 |
Napačna zahteva - Neveljavni parametri ali manjkajoča zahtevana polja |
401 |
Nepooblaščeno - Neveljaven ali manjkajoč API ključ |
429 |
Preveč zahtev - Dosežena omejitev sporočil za vaš načrt |
503 |
Storitev ni na voljo - Storitev UI je začasno nedosegljiva |
Omejitve hitrosti
Uporaba API je omejena z vašim naročniškim načrtom:
- Free: 100 sporočil/mesec
- Starter (39 $/mesec): 2.500 sporočil/mesec
- Standard (139 $/mesec): 15.000 sporočil/mesec
- Pro (449 $/mesec): 50.000 sporočil/mesec
Potrebujete pomoč?
Če imate kakršna koli vprašanja ali naletite na težave, nas kontaktirajte na hello@asyntai.com.