Natrag na nadzornu ploču

Dokumentacija

Naučite kako koristiti Asyntai

API referenca

Izradite prilagođene integracije s Asyntai REST API-jem

Dohvatite API ključ

Potreban plaćeni plan: API pristup dostupan je na Starter, Standard i Pro planovima. Pogledajte cijene

Pregled

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.

Autentifikacija

Svi API zahtjevi zahtijevaju autentifikaciju pomoću vašeg API ključa. Svoj API ključ možete dobiti na stranici API postavke.

Uključite svoj API ključ u zahtjeve koristeći jednu od ovih metoda:

  • Authorization zaglavlje (preporučeno): Authorization: Bearer YOUR_API_KEY
  • X-API-Key zaglavlje: X-API-Key: YOUR_API_KEY

Čuvajte svoj API ključ u tajnosti. Svatko s vašim ključem može pristupiti vašem računu putem API-ja. Nikada ga ne izlažite u klijentskom kodu.

Bazni URL

https://asyntai.com/api/v1/

Krajnje točke

POST /chat/

Pošaljite poruku i primite odgovor generiran AI-jem.

Tijelo zahtjeva

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}
Parametar Tip Obavezno Opis
message string Da Korisnička poruka za slanje AI-ju
session_id string Ne Jedinstveni identifikator za razgovor. Koristite isti session_id za održavanje povijesti razgovora.
website_id integer Ne Specifični ID web stranice. Ako nije naveden, koristi se vaša primarna web stranica.

Odgovor

{
  "success": true,
  "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
  "session_id": "user_123"
}

Primjer (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"}'

Primjer (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"])

Primjer (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/

Prikažite sve web stranice povezane s vašim računom.

Odgovor

{
  "success": true,
  "websites": [
    {
      "id": 1,
      "name": "My Website",
      "domain": "example.com",
      "is_primary": true
    }
  ]
}

Primjer (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.

Tijelo zahtjeva

Polje Tip Opis
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.

Odgovor

{
  "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>"
}

Primjer (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.

Odgovor

{
  "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.

Primjer (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 Postavke Examples
Any paid plan 25 widget_color, ai_support_name, initial_message
Starter i viši 22 profile_picture, conversation_starters_enabled
Standard i viši 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}'

Tijelo zahtjeva

Polje Tip Opis
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/

Dohvatite povijest razgovora za određenu sesiju.

Parametri upita

Parametar Tip Obavezno Opis
session_id string Da ID sesije za dohvaćanje povijesti
limit integer Ne Maksimalni broj poruka za vraćanje (zadano: 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",
      "sender_type": "ai",
      "agent_name": null,
      "response_time_ms": 1840.5
    }
  ]
}

Pitanje i njegov odgovor spremaju se u jedan zapis, pa oba nose isti timestamp. Nemojte oduzimati jedno od drugoga da biste izmjerili brzinu odgovora, jer je rezultat uvijek nula. Upotrijebite response_time_ms, što je stvarno vrijeme odgovora u milisekundama.

sender_type je ai kada je odgovorio chatbot, a human kada je jedan od vaših agenata preuzeo razgovor. agent_name sadrži prikazano ime tog agenta.

Primjer (cURL)

curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /sessions/

Prikažite svoje nedavne chat sesije. Koristite ovo za otkrivanje ID-ova sesija, koje zatim možete proslijediti na /conversations/ za dohvaćanje pune povijesti poruka.

Parametri upita

Parametar Tip Obavezno Opis
limit integer Ne Broj nedavnih sesija za vraćanje (zadano: 20, maks: 100)
website_id string Ne Filtrirajte sesije prema određenom ID-u web stranice
source string Ne Filtrirajte prema izvoru sesije: 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",
      "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"
    }
  ]
}

Polja s vremenskim oznakama za izvještavanje

Polje Opis
started_at Kada je posjetitelj otvorio razgovor. Dostupno samo za sesije widgeta, jer sesije stvorene putem API-ja nikada ne otvaraju widget.
first_message_at Kada je spremljena prva poruka razgovora.
first_response_time_ms Koliko je trajao prvi odgovor, u milisekundama. Upotrijebite ovo za vrijeme prvog odgovora.
first_human_response_at Kada je jedan od vaših agenata poslao prvi odgovor. Vrijednost je null kada je chatbot vodio cijeli razgovor.
taken_over_at Kada je agent preuzeo razgovor od chatbota.
last_message_at Kada je spremljena posljednja poruka razgovora.
ended_at Kada je posjetitelj napustio razgovor. Razgovor nema stanje riješeno ni zatvoreno, jer se posjetitelj uvijek može vratiti i postaviti novo pitanje.

Sve vremenske oznake su u UTC-u i koriste format ISO 8601. Vremensku zonu ne možete promijeniti. Pretvorite vrijednosti u vlastitom alatu za izvještavanje.

Primjer (cURL)

curl "https://asyntai.com/api/v1/sessions/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /leads/

Dohvati prikupljene kontakte — adrese e-pošte i telefonske brojeve koje su posjetitelji poslali tijekom chat razgovora.

Parametri upita

Parametar Tip Obavezno Opis
limit integer Ne Broj kontakata za vraćanje (zadano: 50, maks: 100)
website_id string Ne Filtrirajte kontakte prema određenom ID-u web stranice

Odgovor

{
  "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"
    }
  ]
}
Polje Tip Opis
session_id string ID chat sesije. Proslijedite ga na /conversations/ za pregled potpune povijesti chata.
email niz ili null E-mail adresa koju je posjetitelj naveo, ili null ako nije prikupljena
phone niz ili null Telefonski broj koji je posjetitelj naveo, ili null ako nije prikupljen
page_url niz ili null URL stranice na kojoj je posjetitelj razgovarao
started_at string ISO 8601 vremenska oznaka početka chat sesije

Primjer (cURL)

curl "https://asyntai.com/api/v1/leads/?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Primjer (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/

Dohvatite informacije o svom računu i statistiku korištenja.

Odgovor

{
  "success": true,
  "account": {
    "email": "[email protected]",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 2500
  }
}

Primjer (cURL)

curl https://asyntai.com/api/v1/account/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Više web stranica? Krajnje točke baze znanja zadano koriste vašu primarnu web stranicu. Ako imate više web stranica, proslijedite website_id za ciljanje određene. Svoje ID-ove web stranica možete pronaći koristeći GET /websites/.

Dnevna ograničenja prijenosa: Prijenosi u bazu znanja (tekst, URL, tablice) podliježu dnevnom ograničenju znakova na temelju vašeg plana. Ovo se odnosi na ukupni sadržaj prenesen preko svih krajnjih točaka baze znanja dnevno.

Plan Znakova/dan
Starter300.000
Standard1.500.000
Pro6.000.000

GET /knowledge/

Prikažite unose u bazi znanja. To su izvori sadržaja koje vaš AI chatbot koristi za odgovaranje na pitanja.

Parametri upita

Parametar Tip Obavezno Opis
limit integer Ne Broj unosa za vraćanje (zadano: 50, maks: 100)
website_id string Ne Filtrirajte prema ID-u web stranice (zadano vaša primarna web stranica)

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"
    }
  ]
}

Primjer (cURL)

curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /knowledge/text/

Dodajte prilagođeni tekstualni sadržaj u svoju bazu znanja. AI će ovo koristiti za odgovaranje na pitanja posjetitelja.

Tijelo zahtjeva

{
  "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"
}
Parametar Tip Obavezno Opis
title string Da Naslov za ovaj unos u bazu znanja
content string Da Tekstualni sadržaj (minimalno 10 znakova)
website_id string Ne Ciljna web stranica (zadano vaša primarna web stranica)

Odgovor

{
  "success": true,
  "id": "abc-123-def",
  "title": "Return Policy",
  "chunks_created": 1
}

Primjer (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 web stranicu u svoju bazu znanja. Sadržaj će se automatski dohvatiti i izvući.

Tijelo zahtjeva

{
  "url": "https://example.com/faq",
  "website_id": "123"
}
Parametar Tip Obavezno Opis
url string Da URL s kojeg se dohvaća sadržaj
website_id string Ne Ciljna web stranica (zadano vaša primarna web stranica)

Odgovor

{
  "success": true,
  "id": "abc-123-def",
  "title": "FAQ - Example",
  "url": "https://example.com/faq",
  "chunks_created": 5
}

Primjer (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/

Prenesite CSV ili Excel (.xlsx) tablicu u svoju bazu znanja. Svaki redak postaje zasebni unos u bazu znanja, idealno za kataloge proizvoda, popise čestih pitanja, tablice cijena i imenike.

Zahtjev

Pošaljite kao multipart/form-data (učitavanje datoteke), ne JSON.

Parametar Tip Obavezno Opis
file datoteka Da .csv ili .xlsx datoteka. Prvi redak moraju biti zaglavlja stupaca. Maks. redaka po prijenosu: Starter 500, Standard 2.000, Pro 10.000. Višak redaka se skraćuje.
website_id string Ne Ciljna web stranica (zadano vaša primarna web stranica)

Odgovor

{
  "success": true,
  "id": "abc-123-def",
  "title": "products.csv",
  "rows_processed": 15,
  "chunks_created": 15
}

Primjer (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

GET /knowledge/{id}/

Pročitajte jedan unos baze znanja, uključujući tekst pohranjen za njega. Vrijednost id dolazi iz odgovora GET /knowledge/.

Sadržaj se vraća za unose koje ste sami dodali: tekst, datoteke, proračunske tablice, pojedinačne URL adrese i videozapise. Pretraživanje web-mjesta prikazuje se na popisu, ali se njegove stranice ne vraćaju jer je izvor vaše vlastito javno web-mjesto. U tom je slučaju content jednak null, a polje reason objašnjava razlog.

Odgovor

{
  "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
}

Primjer (cURL)

curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE /knowledge/{id}/

Obrišite unos u bazi znanja. id se može pronaći iz odgovora GET /knowledge/.

Odgovor

{
  "success": true,
  "message": "Knowledge base entry deleted"
}

Primjer (cURL)

curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Savjet: Također možete upravljati webhookovima iz API postavke stranice bez pisanja ikakvog koda.

GET /webhooks/

Prikažite svoje registrirane webhookove.

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"
    }
  ]
}

Primjer (cURL)

curl "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /webhooks/

Registrirajte novi webhook za primanje obavijesti o događajima u stvarnom vremenu.

Dostupni događaji

Događaj Opis
message.received Posjetitelj je poslao poruku i primio odgovor
conversation.started Pokrenuta je nova chat sesija
escalation.requested AI je pokrenuo eskalaciju na ljudskog agenta
takeover.started Ljudski agent je preuzeo chat sesiju

Tijelo zahtjeva

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}
Parametar Tip Obavezno Opis
url string Da HTTPS URL za primanje webhook POST zahtjeva
events niz Da Popis događaja za pretplatu (pogledajte gornju tablicu)
website_id string Ne Ciljna web stranica (zadano vaša primarna web stranica)

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"
  }
}

Provjera webhookova: Svaki webhook uključuje secret (prikazano samo pri kreiranju). Svaki POST na vaš URL uključuje X-Webhook-Signature zaglavlje — HMAC-SHA256 hash tijela zahtjeva potpisan vašom tajnom.

Primjer (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}/

Obrišite webhook. id se može pronaći iz odgovora GET /webhooks/.

Odgovor

{
  "success": true,
  "message": "Webhook deleted"
}

Primjer (cURL)

curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Odgovori s greškom

Svi odgovori s greškom slijede ovaj format:

{
  "success": false,
  "error": "Error message describing what went wrong"
}
Statusni kod Opis
400 Neispravan zahtjev - Nevažeći parametri ili nedostajuća obavezna polja
401 Neovlašteno - Nevažeći ili nedostajući API ključ
429 Previše zahtjeva - Dosegnuto ograničenje poruka za vaš plan
503 Usluga nedostupna - AI usluga privremeno nedostupna

Ograničenja brzine

Korištenje API-ja ograničeno je vašim pretplatničkim planom:

  • Free: 100 poruka/mjesečno
  • Starter (39 $/mj.): 2.500 poruka/mjesečno
  • Standard (139 $/mj.): 15.000 poruka/mjesečno
  • Pro (449 $/mj.): 50.000 poruka/mjesečno

Trebate pomoć?

Ako imate pitanja ili naiđete na probleme, kontaktirajte nas na [email protected].