Înapoi la tabloul de bord

Documentație

Aflați cum să utilizați Asyntai

Referință API

Construiește integrări personalizate cu API-ul REST Asyntai

Obține cheia API

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