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ă
The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses grounded in your website content and knowledge base.
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"
POST /websites/
Create a new AI agent. This does the same thing as adding a website in your dashboard: it makes the agent, reads your site, and writes the first draft of the AI instructions.
Use this to set up customers from your own software. You get back the widget ID and the code to put on the website.
Corp cerere
| Câmp | Tip | Descriere |
|---|---|---|
domain |
string | Required. The website address, for example example.com |
name |
string | Optional. A display name for the agent. Useful when one website has several agents. |
crawl |
boolean | Optional, true by default. Set it to false to create the agent without reading the website. Nothing is crawled and no instructions are written. |
force |
boolean | Optional, false by default. Set it to true to add a website you already have. The copy is stored with a number after it. |
Răspuns
{
"success": true,
"website": {
"id": 42,
"domain": "example.com",
"name": "Support agent",
"widget_id": "asyntai_ab12cd34ef56",
"is_primary": true,
"crawl_started": true,
"instructions_status": "generating",
"job_id": "8f2c1e90-..."
},
"embed_code": "<script>...</script>"
}
Exemplu (cURL)
curl -X POST https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"domain": "example.com", "name": "Support agent"}'
Reading a website takes a few minutes, so this call answers straight away. Check when the agent is ready with the next endpoint.
Errors
| Code | Meaning |
|---|---|
403 |
You have reached the number of websites your plan allows. The answer tells you the limit. |
409 |
Your account already has this website. Send force as true to add it again. |
GET /websites/{id}/
Get one website and see whether it is ready. Use this after you create an agent, to wait until the website has been read and the AI instructions are written.
Răspuns
{
"success": true,
"website": {
"id": 42,
"domain": "example.com",
"name": "Support agent",
"widget_id": "asyntai_ab12cd34ef56",
"is_primary": true,
"created_at": "2026-08-11T09:12:00+00:00",
"ready": true,
"instructions": {
"status": "completed",
"has_instructions": true,
"characters": 3421
},
"crawl": {
"job_id": "8f2c1e90-...",
"status": "completed",
"pages_crawled": 47,
"pages_found": 50,
"max_pages": 50,
"completed_at": "2026-08-11T09:15:31+00:00",
"error": ""
},
"knowledge_items": 47
},
"embed_code": "<script>...</script>"
}
The ready field is true when nothing is still running. A crawl that failed also counts as ready, because it has finished. Look at the crawl status to see what happened.
Exemplu (cURL)
curl https://asyntai.com/api/v1/websites/42/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET PATCH /websites/{id}/settings/
Read or change the chat widget settings for one website. These are the same settings you see on the Customize page: colours, the name of the assistant, the first message, lead capture, and everything else.
Reading the settings
A GET request returns every setting with its current value, plus a locked list. Locked shows the settings your plan cannot change, and which plans they need.
{
"success": true,
"settings": {
"ai_support_name": "AI Assistant",
"widget_color": "#6366f1",
"initial_message": "Hi, how can I help you?",
"hide_branding": false,
"...": "..."
},
"locked": {
"hide_branding": ["pro", "enterprise"],
"widget_style": ["pro", "enterprise"]
}
}
Changing the settings
A PATCH request changes only the settings you send. Everything you leave out stays as it is.
curl -X PATCH https://asyntai.com/api/v1/websites/42/settings/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ai_support_name": "Ava", "widget_color": "#0f172a", "use_emoji": true}'
{
"success": true,
"updated": ["ai_support_name", "use_emoji", "widget_color"],
"settings": { "...": "..." },
"locked": { "...": "..." }
}
Plans
Each setting needs its own plan, the same as in the dashboard. For example, hiding the Asyntai branding needs the Pro plan, and voice input needs Standard.
| Plan needed | Setări | Examples |
|---|---|---|
| Any paid plan | 25 | widget_color, ai_support_name, initial_message |
| Starter și superior | 22 | profile_picture, conversation_starters_enabled |
| Standard și superior | 25 | speech_to_text_enabled, image_vision_enabled, escalation_enabled |
| Pro | 6 | hide_branding, widget_style |
If you send a setting your plan does not allow, the whole request is refused with code 403 and nothing is saved. The same happens if any value is wrong, for example a colour that is not a hex code. Your settings never end up half changed.
GET PUT /websites/{id}/instructions/
Read or replace the AI instructions for one website. These are the rules that tell the assistant who it is, what it may say, and what it must not say. They are the same instructions you edit in the dashboard.
Reading
{
"success": true,
"instructions": "You are the support agent for Acme Tools...",
"characters": 1979,
"version": 7,
"mode": "instructions",
"ask_questions": true,
"generation_status": "completed",
"being_edited_by": null
}
Replacing
A PUT request replaces the whole text, the same as saving in the dashboard. There is no append mode. To add a paragraph, read the instructions, add your text, then write it back.
curl -X PUT https://asyntai.com/api/v1/websites/42/instructions/ \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"instructions": "You are the support agent for Acme Tools...", "version": 7}'
Corp cerere
| Câmp | Tip | Descriere |
|---|---|---|
instructions |
string | Required. The complete new text. It replaces everything that was there. |
version |
number | Optional but recommended. The version you read. If somebody changed the instructions since then, your write is refused instead of overwriting their work. |
mode |
string | Optional. Either instructions or general. |
ask_questions |
boolean | Optional. Whether the assistant asks a follow-up question at the end of its answers. |
force |
boolean | Optional, false by default. Needed only when your new text is less than half the length of the current text. |
How your instructions are protected
Instructions can take hours to write, so a write can be refused to protect them:
| Code | Meaning |
|---|---|
400 |
Your new text is less than half the length of the current text. This catches a script that sends empty or cut-off text over instructions somebody spent hours on. Send force as true if you meant it. |
409 |
The instructions changed after you read them. Read them again, apply your change, then write. |
423 |
Somebody is editing the instructions in the dashboard right now. The answer tells you who. Try again in a couple of minutes. |
Every change also saves a copy of the previous text, so an earlier version can always be restored from the dashboard.
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",
"sender_type": "ai",
"agent_name": null,
"response_time_ms": 1840.5
}
]
}
O întrebare și răspunsul ei sunt salvate într-o singură înregistrare, deci ambele au același timestamp. Nu scădeți una din cealaltă pentru a măsura viteza răspunsului, deoarece rezultatul este întotdeauna zero. Folosiți response_time_ms, care este timpul real al răspunsului, în milisecunde.
sender_type este ai când a răspuns chatbotul și human când unul dintre agenții dumneavoastră a preluat conversația. agent_name conține numele afișat al acelui agent.
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",
"first_response_time_ms": 1840.5,
"first_human_response_at": null,
"started_at": "2024-01-15T10:29:58Z",
"ended_at": "2024-01-15T10:41:12Z",
"taken_over_at": null,
"website_domain": "example.com"
}
]
}
Câmpuri de marcaj temporal pentru raportare
| Câmp | Descriere |
|---|---|
started_at |
Când a deschis vizitatorul conversația. Disponibil doar pentru sesiunile widgetului, deoarece sesiunile create prin API nu deschid niciodată un widget. |
first_message_at |
Când a fost salvat primul mesaj al conversației. |
first_response_time_ms |
Cât a durat primul răspuns, în milisecunde. Folosiți acest câmp pentru timpul primului răspuns. |
first_human_response_at |
Când a trimis unul dintre agenții dumneavoastră primul răspuns. Valoarea este null când chatbotul a gestionat întreaga conversație. |
taken_over_at |
Când a preluat un agent conversația de la chatbot. |
last_message_at |
Când a fost salvat ultimul mesaj al conversației. |
ended_at |
Când a părăsit vizitatorul conversația. O conversație nu are o stare rezolvată sau închisă, deoarece un vizitator poate reveni oricând și poate pune altă întrebare. |
Toate marcajele temporale sunt în UTC și folosesc formatul ISO 8601. Nu puteți schimba fusul orar. Convertiți valorile în propriul dumneavoastră instrument de raportare.
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": "[email protected]",
"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": "[email protected]",
"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 | 300.000 |
| Standard | 1.500.000 |
| Pro | 6.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 "[email protected]"
GET /knowledge/{id}/
Citiți o intrare din baza de cunoștințe, inclusiv textul stocat pentru ea. Valoarea id provine din răspunsul GET /knowledge/.
Conținutul este returnat pentru intrările pe care le-ați adăugat dumneavoastră: text, fișiere, foi de calcul, adrese URL individuale și videoclipuri. Parcurgerea unui site apare în listă, dar paginile sale nu sunt returnate, deoarece sursa este propriul dumneavoastră site public. În acest caz, content este null, iar câmpul reason explică motivul.
Răspuns
{
"success": true,
"id": "abc-123-def",
"type": "text",
"title": "Business Hours",
"description": "Manual text content (150 words)",
"created_at": "2024-01-15T10:30:00Z",
"chunks_count": 3,
"content": "We are open Monday to Friday, 9am to 5pm...",
"content_available": true,
"char_count": 43
}
Exemplu (cURL)
curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
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 [email protected].