Обратно към таблото

Документация

Научете как да използвате Asyntai

Първи стъпки
Инсталация База знания Как ИИ получава достъп до вашето съдържание Свържете сайта си Тествайте вашия ИИ Управление на уебсайтове Съвети за ИИ инструкции Преминаване от друг чатбот Сравнение на планове
Функции
Ask AI лента AI лента за търсене AI търсене за WordPress Сканиране на уебсайт Пропуски в знанията Продуктови карти Динамични продуктови карти Динамични изображения Потребителски контекст Персонализирани инструменти Параметри на връзки Наблюдение на живо Поемане от човек Ескалация ИИ известия Дневен отчет Поток от данни в реално време Максимален поток от данни в реално време Членове на екипа Единичен вход (SSO) Двуфакторна автентикация Включване на изображения Визуално разпознаване на изображения Приспособление за превод Локализация Прозрачност на ИИ Потенциални клиенти Интелигентно събиране на контакти Тикети за поддръжка Резервации Вграждания Изключване на страници Блокирани IP адреси Политика за съхранение Режим нулево съхранение Маскиране на PII Класификатор на отговорите Access Tags Фиксиране на версията на приспособлението Одиторски дневник По-умен модел Активиране на мислене Предложения за отговор Последващи съобщения Реч към текст Изтегляне на стенограма Вграден чат Iframe Embed

API справка

Създайте персонализирани интеграции с Asyntai REST API

Получете 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, таблица) подлежат на дневен лимит на символи, базиран на вашия план. Това се отнася за общото съдържание, качено чрез всички крайни точки на базата знания на ден.

План Символи/ден
Starter300 000
Standard1 500 000
Pro6 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].