Referință API
Construiește integrări personalizate cu API-ul REST Asyntai
Plan plătit necesar: Accesul la API este disponibil pentru planurile Starter, Standard și Pro. Vezi prețurile
Prezentare generală
API-ul Asyntai îți permite să integrezi suportul clienți bazat pe AI în orice aplicație. Trimite mesaje și primește răspunsuri inteligente antrenate pe conținutul site-ului tău și baza de cunoștințe.
Autentificare
Toate cererile API necesită autentificare folosind cheia ta API. Poți obține cheia API din pagina Setări API.
Include cheia ta API în cereri folosind una dintre aceste metode:
- Antet Authorization (recomandat):
Authorization: Bearer YOUR_API_KEY - Antet X-API-Key:
X-API-Key: YOUR_API_KEY
Păstrează cheia ta API secretă. Oricine are cheia ta poate accesa contul tău prin API. Nu o expune niciodată în codul client-side.
URL de bază
https://asyntai.com/api/v1/
Endpoint-uri
POST /chat/
Trimite un mesaj și primește un răspuns generat de AI.
Corp cerere
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
message |
string | Da | Mesajul utilizatorului care se trimite către AI |
session_id |
string | Nu | Identificator unic pentru conversație. Folosește același session_id pentru a menține istoricul conversației. |
website_id |
integer | Nu | ID specific site-ului. Dacă nu este furnizat, se folosește site-ul tău principal. |
Răspuns
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Exemplu (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"}'
Exemplu (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"])
Exemplu (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/
Listează toate site-urile asociate contului tău.
Răspuns
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Exemplu (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Recuperează istoricul conversației pentru o sesiune specifică.
Parametri de interogare
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
session_id |
string | Da | ID-ul sesiunii pentru care se recuperează istoricul |
limit |
integer | Nu | Număr maxim de mesaje de returnat (implicit: 50, maxim: 100) |
Răspuns
{
"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"
}
]
}
Exemplu (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Listează sesiunile tale recente de chat. Folosește acest lucru pentru a descoperi ID-urile sesiunilor, pe care le poți transmite apoi la /conversations/ pentru a recupera istoricul complet al mesajelor.
Parametri de interogare
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
limit |
integer | Nu | Număr de sesiuni recente de returnat (implicit: 20, maxim: 100) |
website_id |
string | Nu | Filtrează sesiunile după un ID specific de site |
source |
string | Nu | Filtrați după sursa sesiunii: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Răspuns
{
"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"
}
]
}
Exemplu (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Recuperați lead-urile colectate — adrese de e-mail și numere de telefon trimise de vizitatori în timpul conversațiilor de chat.
Parametri de interogare
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
limit |
integer | Nu | Numărul de lead-uri de returnat (implicit: 50, max: 100) |
website_id |
string | Nu | Filtrați lead-urile după un ID de site web specific |
Răspuns
{
"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"
}
]
}
| Câmp | Tip | Descriere |
|---|---|---|
session_id |
string | ID-ul sesiunii de chat. Transmiteți-l la /conversations/ pentru a vedea istoricul complet al chat-ului. |
email |
șir sau null | Adresa de e-mail furnizată de vizitator, sau null dacă nu a fost colectată |
phone |
șir sau null | Numărul de telefon furnizat de vizitator, sau null dacă nu a fost colectat |
page_url |
șir sau null | URL-ul paginii unde vizitatorul conversa |
started_at |
string | Marca temporală ISO 8601 a momentului când a început sesiunea de chat |
Exemplu (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Exemplu (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/
Obține informațiile contului tău și statisticile de utilizare.
Răspuns
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Exemplu (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Mai multe site-uri? Endpoint-urile bazei de cunoștințe au ca implicit site-ul tău principal. Dacă ai mai multe site-uri, transmite website_id pentru a viza unul specific. Poți găsi ID-urile site-urilor tale folosind GET /websites/.
Limite zilnice de încărcare: Încărcările în baza de cunoștințe (text, URL, foaie de calcul) sunt supuse unei limite zilnice de caractere în funcție de planul tău. Aceasta se aplică conținutului total încărcat pe toate endpoint-urile bazei de cunoștințe pe zi.
| Plan | Caractere/zi |
|---|---|
| Starter | 100.000 |
| Standard | 500.000 |
| Pro | 2.000.000 |
GET /knowledge/
Listează intrările din baza ta de cunoștințe. Acestea sunt sursele de conținut pe care chatbot-ul tău AI le folosește pentru a răspunde la întrebări.
Parametri de interogare
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
limit |
integer | Nu | Număr de intrări de returnat (implicit: 50, maxim: 100) |
website_id |
string | Nu | Filtrează după ID-ul site-ului (implicit site-ul tău principal) |
Răspuns
{
"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"
}
]
}
Exemplu (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Adaugă conținut text personalizat în baza ta de cunoștințe. AI-ul va folosi acest lucru pentru a răspunde la întrebările vizitatorilor.
Corp cerere
{
"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"
}
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
title |
string | Da | Un titlu pentru această intrare de cunoștințe |
content |
string | Da | Conținutul text (minim 10 caractere) |
website_id |
string | Nu | Site-ul țintă (implicit site-ul tău principal) |
Răspuns
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Exemplu (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/
Adaugă o pagină web în baza ta de cunoștințe. Conținutul va fi preluat și extras automat.
Corp cerere
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
url |
string | Da | URL-ul din care se preia conținutul |
website_id |
string | Nu | Site-ul țintă (implicit site-ul tău principal) |
Răspuns
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Exemplu (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/
Încarcă un fișier CSV sau Excel (.xlsx) în baza ta de cunoștințe. Fiecare rând devine o intrare separată de cunoștințe, ideal pentru cataloage de produse, liste de întrebări frecvente, tabele de prețuri și directoare.
Cerere
Trimite ca multipart/form-data (încărcare fișier), nu JSON.
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
file |
fișier | Da | Un fișier .csv sau .xlsx. Primul rând trebuie să fie antete de coloane. Rânduri maxime per încărcare: Starter 500, Standard 2.000, Pro 10.000. Rândurile în exces sunt trunchiate. |
website_id |
string | Nu | Site-ul țintă (implicit site-ul tău principal) |
Răspuns
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Exemplu (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Șterge o intrare din baza de cunoștințe. id-ul poate fi găsit în răspunsul GET /knowledge/.
Răspuns
{
"success": true,
"message": "Knowledge base entry deleted"
}
Exemplu (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Sfat: Poți gestiona și webhook-urile din Setări API pagină fără a scrie cod.
GET /webhooks/
Listează webhook-urile tale înregistrate.
Răspuns
{
"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"
}
]
}
Exemplu (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Înregistrează un nou webhook pentru a primi notificări de evenimente în timp real.
Evenimente disponibile
| Eveniment | Descriere |
|---|---|
message.received |
Un vizitator a trimis un mesaj și a primit un răspuns |
conversation.started |
O nouă sesiune de chat a fost inițiată |
escalation.requested |
AI-ul a declanșat o escaladare către un agent uman |
takeover.started |
Un agent uman a preluat o sesiune de chat |
Corp cerere
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
url |
string | Da | URL-ul HTTPS pentru a primi cereri POST webhook |
events |
array | Da | Lista evenimentelor la care te abonezi (vezi tabelul de mai sus) |
website_id |
string | Nu | Site-ul țintă (implicit site-ul tău principal) |
Răspuns
{
"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"
}
}
Verificarea webhook-urilor: Fiecare webhook include un secret (afișat doar la creare). Fiecare POST către URL-ul tău include un X-Webhook-Signature header — un HMAC-SHA256 al corpului cererii, semnat cu cheia ta secretă.
Exemplu (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}/
Șterge un webhook. id-ul poate fi găsit în răspunsul GET /webhooks/.
Răspuns
{
"success": true,
"message": "Webhook deleted"
}
Exemplu (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Răspunsuri de eroare
Toate răspunsurile de eroare urmează acest format:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Cod de stare | Descriere |
|---|---|
400 |
Cerere invalidă - Parametri invalizi sau câmpuri obligatorii lipsă |
401 |
Neautorizat - Cheie API invalidă sau lipsă |
429 |
Prea multe cereri - Limita de mesaje atinsă pentru planul tău |
503 |
Serviciu indisponibil - Serviciul AI temporar indisponibil |
Limite de rată
Utilizarea API este limitată de planul tău de abonament:
- Free: 100 mesaje/lună
- Starter (39$/lună): 2.500 mesaje/lună
- Standard (139$/lună): 15.000 mesaje/lună
- Pro (449$/lună): 50.000 mesaje/lună
Ai nevoie de ajutor?
Dacă ai întrebări sau întâmpini probleme, contactează-ne la hello@asyntai.com.