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 | Не | Филтриране на потенциални клиенти по конкретен идентификатор на уебсайт |
Отговор
{
"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 | Идентификатор на чат сесията. Предайте го на /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 за да насочите конкретен. Можете да намерите идентификаторите на уебсайтовете си с помощта на GET /websites/.
Дневни лимити за качване: Качванията в базата знания (текст, URL, таблица) подлежат на дневен лимит на символи, базиран на вашия план. Това се отнася за общото съдържание, качено чрез всички крайни точки на базата знания на ден.
| План | Символи/ден |
|---|---|
| Starter | 300 000 |
| Standard | 1 500 000 |
| Pro | 6 000 000 |
GET /knowledge/
Списък на записите в базата ви знания. Това са източниците на съдържание, които вашият ИИ чатбот използва, за да отговаря на въпроси.
Параметри на заявката
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
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 адресът за получаване на webhook 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 |
Услугата е недостъпна - ИИ услугата е временно недостъпна |
Ограничения на честотата
Използването на API е ограничено от вашия абонаментен план:
- Free: 100 съобщения/месец
- Starter ($39/мес.): 2 500 съобщения/месец
- Standard ($139/мес.): 15 000 съобщения/месец
- Pro ($449/мес.): 50 000 съобщения/месец
Нуждаете се от помощ?
Ако имате въпроси или срещнете проблеми, свържете се с нас на [email protected].