Dokumentace k API

Vytvářejte vlastní integrace s Asyntai REST API

Vyžadován placený plán: Přístup k API je dostupný na plánech Starter, Standard a Pro. Zobrazit ceník

Přehled

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.

Autentizace

Všechny API požadavky vyžadují autentizaci pomocí vašeho API klíče. API klíč získáte na stránce Nastavení API.

Zahrňte svůj API klíč do požadavků jedním z těchto způsobů:

Hlavička Authorization (doporučeno): Authorization: Bearer YOUR_API_KEY
Hlavička X-API-Key: X-API-Key: YOUR_API_KEY

Udržujte svůj API klíč v tajnosti. Kdokoli s vaším klíčem může přistupovat k vašemu účtu přes API. Nikdy ho nezveřejňujte v klientském kódu.

Základní URL

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

Endpointy

POST /chat/

Odešlete zprávu a obdržíte odpověď vygenerovanou umělou inteligencí.

Tělo požadavku

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}

Parametr	Typ	Povinné	Popis
`message`	string	Ano	Zpráva uživatele k odeslání umělé inteligenci
`session_id`	string	Ne	Jedinečný identifikátor konverzace. Použijte stejné session_id pro zachování historie konverzace.
`website_id`	integer	Ne	Konkrétní ID webu. Pokud není zadáno, použije se váš primární web.

Odpověď

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

Příklad (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"}'

Příklad (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"])

Příklad (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/

Zobrazí všechny weby přiřazené k vašemu účtu.

Odpověď

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

Příklad (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.

Tělo požadavku

Pole	Typ	Popis
`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.

Odpověď

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

Příklad (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.

Odpověď

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

Příklad (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	Nastavení	Examples
Any paid plan	25	`widget_color`, `ai_support_name`, `initial_message`
Od tarifu Starter	22	`profile_picture`, `conversation_starters_enabled`
Od tarifu Standard	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}'

Tělo požadavku

Pole	Typ	Popis
`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/

Načte historii konverzace pro konkrétní relaci.

Parametry dotazu

Parametr	Typ	Povinné	Popis
`session_id`	string	Ano	ID relace, pro kterou se má načíst historie
`limit`	integer	Ne	Maximální počet zpráv k vrácení (výchozí: 50, max: 100)

Odpověď

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

Otázka a její odpověď se ukládají do jednoho záznamu, takže obě nesou stejný timestamp. Neodčítejte jeden od druhého pro měření rychlosti odpovědi, protože výsledek je vždy nula. Použijte response_time_ms, což je skutečná doba odpovědi v milisekundách.

sender_type je ai, když odpověděl chatbot, a human, když chat převzal některý z vašich agentů. agent_name obsahuje zobrazované jméno tohoto agenta.

Příklad (cURL)

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

GET /sessions/

Zobrazí vaše nedávné chatové relace. Použijte k zjištění ID relací, která pak můžete předat do /conversations/ pro načtení úplné historie zpráv.

Parametry dotazu

Parametr	Typ	Povinné	Popis
`limit`	integer	Ne	Počet nedávných relací k vrácení (výchozí: 20, max: 100)
`website_id`	string	Ne	Filtrovat relace podle konkrétního ID webu
`source`	string	Ne	Filtrovat podle zdroje relace: `widget`, `api`, `whatsapp`, `instagram`, `messenger`, `gorgias`, `freshchat`, `zapier`

Odpověď

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

Pole s časovými údaji pro reporting

Pole	Popis
`started_at`	Kdy návštěvník otevřel chat. Dostupné pouze u relací widgetu, protože relace vytvořené přes API widget nikdy neotevřou.
`first_message_at`	Kdy byla uložena první zpráva konverzace.
`first_response_time_ms`	Jak dlouho trvala první odpověď, v milisekundách. Použijte to pro dobu první odpovědi.
`first_human_response_at`	Kdy poslal první odpověď některý z vašich agentů. Hodnota je `null`, když celou konverzaci zvládl chatbot.
`taken_over_at`	Kdy agent převzal chat od chatbota.
`last_message_at`	Kdy byla uložena poslední zpráva konverzace.
`ended_at`	Kdy návštěvník opustil chat. Chat nemá stav vyřešeno ani uzavřeno, protože návštěvník se může kdykoli vrátit a položit další otázku.

Všechny časové údaje jsou v UTC a používají formát ISO 8601. Časové pásmo nelze změnit. Převeďte hodnoty ve svém nástroji pro reporting.

Příklad (cURL)

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

GET /leads/

Získejte shromážděné kontakty — e-mailové adresy a telefonní čísla, které návštěvníci odeslali během chatových konverzací.

Parametry dotazu

Parametr	Typ	Povinné	Popis
`limit`	integer	Ne	Počet kontaktů k vrácení (výchozí: 50, max: 100)
`website_id`	string	Ne	Filtrovat kontakty podle konkrétního ID webu

Odpověď

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

Pole	Typ	Popis
`session_id`	string	ID chatové relace. Předejte ho do `/conversations/` pro zobrazení úplné historie chatu.
`email`	řetězec nebo null	E-mailová adresa poskytnutá návštěvníkem, nebo null pokud nebyla shromážděna
`phone`	řetězec nebo null	Telefonní číslo poskytnuté návštěvníkem, nebo null pokud nebylo shromážděno
`page_url`	řetězec nebo null	URL stránky, kde návštěvník chatoval
`started_at`	string	Časové razítko ISO 8601 začátku chatové relace

Příklad (cURL)

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

Příklad (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/

Získejte informace o svém účtu a statistiky využití.

Odpověď

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

Příklad (cURL)

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

Více webů? Koncové body znalostní báze se výchozě vztahují k vašemu primárnímu webu. Pokud máte více webů, předejte website_id pro zacílení konkrétního webu. ID svých webů najděte pomocí GET /websites/.

Denní limity nahrávání: Nahrávání do znalostní báze (text, URL, tabulka) podléhá dennímu limitu znaků podle vašeho tarifu. Toto platí pro celkový obsah nahraný prostřednictvím všech koncových bodů znalostní báze za den.

Tarif	Znaky/den
Starter	300 000
Standard	1 500 000
Pro	6 000 000

GET /knowledge/

Zobrazí záznamy vaší znalostní báze. Jedná se o zdroje obsahu, které váš AI chatbot používá k odpovídání na otázky.

Parametry dotazu

Parametr	Typ	Povinné	Popis
`limit`	integer	Ne	Počet záznamů k vrácení (výchozí: 50, max: 100)
`website_id`	string	Ne	Filtrovat podle ID webu (výchozí je váš primární web)

Odpověď

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

Příklad (cURL)

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

POST /knowledge/text/

Přidejte vlastní textový obsah do znalostní báze. AI jej použije k odpovídání na dotazy návštěvníků.

Tělo požadavku

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

Parametr	Typ	Povinné	Popis
`title`	string	Ano	Název tohoto záznamu znalostní báze
`content`	string	Ano	Textový obsah (min. 10 znaků)
`website_id`	string	Ne	Cílový web (výchozí je váš primární web)

Odpověď

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

Příklad (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/

Přidejte webovou stránku do znalostní báze. Obsah bude automaticky stažen a extrahován.

Tělo požadavku

{
  "url": "https://example.com/faq",
  "website_id": "123"
}

Parametr	Typ	Povinné	Popis
`url`	string	Ano	URL adresa, ze které se má načíst obsah
`website_id`	string	Ne	Cílový web (výchozí je váš primární web)

Odpověď

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

Příklad (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/

Nahrajte CSV nebo Excel (.xlsx) tabulku do znalostní báze. Každý řádek se stane samostatným záznamem znalostní báze, ideální pro produktové katalogy, seznamy FAQ, ceníky a adresáře.

Požadavek

Odešlete jako multipart/form-data (nahrání souboru), ne JSON.

Parametr	Typ	Povinné	Popis
`file`	file	Ano	Soubor .csv nebo .xlsx. První řádek musí být záhlaví sloupců. Max. řádků na nahrání: Starter 500, Standard 2 000, Pro 10 000. Přebytečné řádky budou zkráceny.
`website_id`	string	Ne	Cílový web (výchozí je váš primární web)

Odpověď

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

Příklad (cURL)

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

GET /knowledge/{id}/

Načtěte jednu položku znalostní báze včetně textu, který je pro ni uložen. Hodnotu id získáte z odpovědi GET /knowledge/.

Obsah se vrací u položek, které jste vložili vy: text, soubory, tabulky, jednotlivé URL adresy a videa. Procházení webu se v seznamu zobrazí, ale jeho stránky se nevracejí, protože zdrojem je váš vlastní veřejný web. V takovém případě je content hodnota null a pole reason vysvětlí důvod.

Odpověď

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

Příklad (cURL)

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

DELETE /knowledge/{id}/

Smazání záznamu znalostní báze. id najděte v odpovědi GET /knowledge/.

Odpověď

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

Příklad (cURL)

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

Tip: Webhooky můžete také spravovat z Nastavení API stránky bez psaní jakéhokoliv kódu.

GET /webhooks/

Zobrazí vaše registrované webhooky.

Odpověď

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

Příklad (cURL)

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

POST /webhooks/

Zaregistrujte nový webhook pro příjem upozornění na události v reálném čase.

Dostupné události

Událost	Popis
`message.received`	Návštěvník odeslal zprávu a obdržel odpověď
`conversation.started`	Byla zahájena nová chatová relace
`escalation.requested`	AI spustila eskalaci na lidského agenta
`takeover.started`	Lidský agent převzal chatovou relaci

Tělo požadavku

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}

Parametr	Typ	Povinné	Popis
`url`	string	Ano	HTTPS URL pro příjem webhook POST požadavků
`events`	pole	Ano	Seznam událostí k odběru (viz tabulka výše)
`website_id`	string	Ne	Cílový web (výchozí je váš primární web)

Odpověď

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

Ověřování webhooku: Každý webhook obsahuje secret (zobrazeno pouze při vytvoření). Každý POST na vaši URL obsahuje X-Webhook-Signature hlavičku — HMAC-SHA256 těla požadavku podepsaného vaším tajným klíčem.

Příklad (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}/

Smazání webhooku. id najděte v odpovědi GET /webhooks/.

Odpověď

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

Příklad (cURL)

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

Chybové odpovědi

Všechny chybové odpovědi mají tento formát:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Stavový kód	Popis
`400`	Chybný požadavek - Neplatné parametry nebo chybějící povinná pole
`401`	Neautorizováno - Neplatný nebo chybějící API klíč
`429`	Příliš mnoho požadavků - Dosažen limit zpráv vašeho tarifu
`503`	Služba nedostupná - AI služba je dočasně nedostupná

Limity požadavků

Používání API je omezeno vaším předplatným:

Free: 100 zpráv/měsíc
Starter (39 $/měs.): 2 500 zpráv/měsíc
Standard (139 $/měs.): 15 000 zpráv/měsíc
Pro (449 $/měs.): 50 000 zpráv/měsíc

Potřebujete pomoc?

Máte-li jakékoli dotazy nebo narazíte na problémy, kontaktujte nás na [email protected].