API референца
Направите прилагођене интеграције са Asyntai REST API-јем
Потребан је плаћени план: API приступ је доступан на Starter, Standard и Pro плановима. Погледајте цене
Преглед
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.
Аутентификација
Сви API захтеви захтевају аутентификацију помоћу вашег API кључа. Можете преузети свој API кључ са странице API подешавања.
Укључите свој API кључ у захтеве користећи један од ових метода:
- Authorization заглавље (препоручено):
Authorization: Bearer YOUR_API_KEY - X-API-Key заглавље:
X-API-Key: YOUR_API_KEY
Чувајте свој API кључ у тајности. Свако ко има ваш кључ може приступити вашем налогу преко API-ја. Никада га не излажите у клијентском коду.
Основни URL
https://asyntai.com/api/v1/
Крајње тачке
POST /chat/
Пошаљите поруку и примите одговор генерисан вештачком интелигенцијом.
Тело захтева
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
message |
string | Да | Порука корисника за слање вештачкој интелигенцији |
session_id |
string | Не | Јединствени идентификатор за разговор. Користите исти session_id за одржавање историје разговора. |
website_id |
integer | Не | Одређени ID веб-сајта. Ако није наведен, користи се ваш примарни веб-сајт. |
Одговор
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Пример (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"}'
Пример (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"])
Пример (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/
Прикажите све веб-сајтове повезане са вашим налогом.
Одговор
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Пример (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.
Тело захтева
| Поље | Тип | Опис |
|---|---|---|
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. |
Одговор
{
"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>"
}
Пример (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.
Одговор
{
"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.
Пример (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 | Подешавања | Examples |
|---|---|---|
| Any paid plan | 25 | widget_color, ai_support_name, initial_message |
| Starter и изнад | 22 | profile_picture, conversation_starters_enabled |
| 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}'
Тело захтева
| Поље | Тип | Опис |
|---|---|---|
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/
Преузмите историју разговора за одређену сесију.
Параметри упита
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
session_id |
string | Да | ID сесије за преузимање историје |
limit |
integer | Не | Максималан број порука за враћање (подразумевано: 50, макс: 100) |
Одговор
{
"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
}
]
}
Питање и његов одговор чувају се у једном запису, па оба носе исти timestamp. Немојте одузимати једно од другог да бисте измерили брзину одговора, јер је резултат увек нула. Користите response_time_ms, што је стварно време одговора у милисекундама.
sender_type је ai када је одговорио чатбот, а human када је разговор преузео неки од ваших агената. agent_name садржи приказано име тог агента.
Пример (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Прикажите своје недавне сесије ћаскања. Користите ово да бисте открили ID-јеве сесија, које затим можете проследити на /conversations/ за преузимање целокупне историје порука.
Параметри упита
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
limit |
integer | Не | Број недавних сесија за враћање (подразумевано: 20, макс: 100) |
website_id |
string | Не | Филтрирајте сесије по одређеном ID-ју веб-сајта |
source |
string | Не | Филтрирајте по извору сесије: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Одговор
{
"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"
}
]
}
Поља са временским ознакама за извештавање
| Поље | Опис |
|---|---|
started_at |
Када је посетилац отворио разговор. Доступно само за сесије виџета, јер сесије направљене преко API-ја никада не отварају виџет. |
first_message_at |
Када је сачувана прва порука разговора. |
first_response_time_ms |
Колико је трајао први одговор, у милисекундама. Ово користите за време првог одговора. |
first_human_response_at |
Када је неки од ваших агената послао први одговор. Вредност је null када је чатбот водио цео разговор. |
taken_over_at |
Када је агент преузео разговор од чатбота. |
last_message_at |
Када је сачувана последња порука разговора. |
ended_at |
Када је посетилац напустио разговор. Разговор нема стање решено ни затворено, јер се посетилац увек може вратити и поставити друго питање. |
Све временске ознаке су у UTC и користе формат ISO 8601. Временску зону не можете променити. Претворите вредности у сопственом алату за извештавање.
Пример (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Преузмите прикупљене потенцијалне клијенте — имејл адресе и бројеве телефона које су посетиоци послали током ћаскања.
Параметри упита
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
limit |
integer | Не | Број потенцијалних клијената за враћање (подразумевано: 50, макс: 100) |
website_id |
string | Не | Филтрирајте потенцијалне клијенте по одређеном ID-у веб сајта |
Одговор
{
"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"
}
]
}
| Поље | Тип | Опис |
|---|---|---|
session_id |
string | ID сесије ћаскања. Проследите га у /conversations/ да бисте видели комплетну историју ћаскања. |
email |
ниска или null | Имејл адреса коју је посетилац навео, или null ако није прикупљена |
phone |
ниска или null | Број телефона који је посетилац навео, или null ако није прикупљен |
page_url |
ниска или null | URL странице на којој је посетилац ћаскао |
started_at |
string | ISO 8601 временски печат почетка сесије ћаскања |
Пример (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Пример (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/
Преузмите информације о свом налогу и статистику коришћења.
Одговор
{
"success": true,
"account": {
"email": "[email protected]",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Пример (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Више веб-сајтова? Крајње тачке базе знања подразумевано се односе на ваш примарни веб-сајт. Ако имате више веб-сајтова, проследите website_id да циљате одређени. Можете пронаћи ваше ID-јеве веб-сајта користећи GET /websites/.
Дневна ограничења отпремања: Отпремања у базу знања (текст, URL, табела) подлежу дневном ограничењу карактера на основу вашег плана. Ово се односи на укупан садржај отпремљен преко свих крајњих тачака базе знања дневно.
| План | Карактера/дан |
|---|---|
| Starter | 300.000 |
| Standard | 1.500.000 |
| Pro | 6.000.000 |
GET /knowledge/
Прикажите ставке своје базе знања. Ово су извори садржаја које ваш AI чатбот користи за одговарање на питања.
Параметри упита
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
limit |
integer | Не | Број ставки за враћање (подразумевано: 50, макс: 100) |
website_id |
string | Не | Филтрирајте по ID-ју веб-сајта (подразумевано ваш примарни веб-сајт) |
Одговор
{
"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"
}
]
}
Пример (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Додајте прилагођени текстуални садржај у своју базу знања. Вештачка интелигенција ће ово користити за одговарање на питања посетилаца.
Тело захтева
{
"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"
}
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
title |
string | Да | Наслов за ову ставку знања |
content |
string | Да | Текстуални садржај (мин. 10 карактера) |
website_id |
string | Не | Циљани веб-сајт (подразумевано ваш примарни веб-сајт) |
Одговор
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Пример (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/
Додајте веб-страницу у своју базу знања. Садржај ће бити аутоматски преузет и извучен.
Тело захтева
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
url |
string | Да | URL са ког се преузима садржај |
website_id |
string | Не | Циљани веб-сајт (подразумевано ваш примарни веб-сајт) |
Одговор
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Пример (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/
Отпремите CSV или Excel (.xlsx) табелу у своју базу знања. Сваки ред постаје засебна ставка знања, идеално за каталоге производа, листе честих питања, ценовнике и именике.
Захтев
Пошаљите као multipart/form-data (отпремање датотеке), не JSON.
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
file |
датотека | Да | .csv или .xlsx датотека. Први ред морају бити заглавља колона. Макс. редова по отпремању: Starter 500, Standard 2.000, Pro 10.000. Вишак редова се скраћује. |
website_id |
string | Не | Циљани веб-сајт (подразумевано ваш примарни веб-сајт) |
Одговор
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Пример (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "[email protected]"
GET /knowledge/{id}/
Прочитајте једну ставку базе знања, укључујући текст који је за њу сачуван. Вредност id долази из одговора GET /knowledge/.
Садржај се враћа за ставке које сте ви додали: текст, датотеке, табеле, појединачне URL адресе и видео снимке. Претраживање сајта се приказује на листи, али се његове странице не враћају, јер је извор ваш сопствени јавни сајт. У том случају content је null, а поље reason објашњава разлог.
Одговор
{
"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
}
Пример (cURL)
curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
DELETE /knowledge/{id}/
Обришите ставку базе знања. id се може пронаћи из одговора GET /knowledge/.
Одговор
{
"success": true,
"message": "Knowledge base entry deleted"
}
Пример (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Савет: Такође можете управљати веб-хуковима са API подешавања странице без писања било каквог кода.
GET /webhooks/
Прикажите своје регистроване веб-хукове.
Одговор
{
"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"
}
]
}
Пример (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Региструјте нови веб-хук за примање обавештења о догађајима у реалном времену.
Доступни догађаји
| Догађај | Опис |
|---|---|
message.received |
Посетилац је послао поруку и примио одговор |
conversation.started |
Нова сесија ћаскања је покренута |
escalation.requested |
Вештачка интелигенција је покренула ескалацију ка живом агенту |
takeover.started |
Живи агент је преузео сесију ћаскања |
Тело захтева
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Параметар | Тип | Обавезно | Опис |
|---|---|---|---|
url |
string | Да | HTTPS URL за примање POST захтева веб-хука |
events |
array | Да | Листа догађаја на које се претплаћујете (погледајте табелу изнад) |
website_id |
string | Не | Циљани веб-сајт (подразумевано ваш примарни веб-сајт) |
Одговор
{
"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"
}
}
Верификација веб-хукова: Сваки веб-хук укључује secret (приказан само при креирању). Сваки POST на ваш URL укључује X-Webhook-Signature заглавље — HMAC-SHA256 тела захтева потписан вашом тајном.
Пример (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}/
Обришите веб-хук. id се може пронаћи из одговора GET /webhooks/.
Одговор
{
"success": true,
"message": "Webhook deleted"
}
Пример (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Одговори са грешком
Сви одговори са грешком прате овај формат:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Статусни код | Опис |
|---|---|
400 |
Лош захтев - Неважећи параметри или недостајућа обавезна поља |
401 |
Неовлашћено - Неважећи или недостајући API кључ |
429 |
Превише захтева - Достигнуто ограничење порука за ваш план |
503 |
Услуга недоступна - AI услуга привремено недоступна |
Ограничења учесталости захтева
Коришћење API-ја је ограничено вашим планом претплате:
- Free: 100 порука/месечно
- Starter ($39/мес.): 2.500 порука/месечно
- Standard ($139/мес.): 15.000 порука/месечно
- Pro ($449/мес.): 50.000 порука/месечно
Потребна вам је помоћ?
Ако имате питања или наиђете на проблеме, контактирајте нас на [email protected].