Î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ă

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
Starter300.000
Standard1.500.000
Pro6.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].