Довідник API
Створюйте власні інтеграції з Asyntai REST API
Потрібен платний тариф: Доступ до API доступний на тарифах Starter, Standard та Pro. Переглянути ціни
Огляд
API Asyntai дозволяє iнтегрувати пiдтримку клiєнтiв на основi ШI в будь-який додаток. Надсилайте повiдомлення та отримуйте iнтелектуальнi вiдповiдi, навченi на контентi вашого сайту та базi знань.
Автентифікація
Усi запити API потребують автентифiкацiї за допомогою вашого ключа API. Ви можете отримати ключ API на сторiнцi Налаштування API.
Додайте ваш ключ API до запитів одним з цих методів:
- Заголовок Authorization (рекомендовано):
Authorization: Bearer YOUR_API_KEY - Заголовок X-API-Key:
X-API-Key: YOUR_API_KEY
Зберігайте ваш ключ API в таємниці. Будь-хто з вашим ключем може отримати доступ до вашого облiкового запису через API. Нiколи не показуйте його в клiєнтському кодi.
Базова URL-адреса
https://asyntai.com/api/v1/
Кінцеві точки
POST /chat/
Надішліть повідомлення та отримайте відповідь, згенеровану ШI.
Тіло запиту
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
message |
string | Так | Повідомлення користувача для надсилання ШI |
session_id |
string | Ні | Унiкальний iдентифiкатор розмови. Використовуйте той самий session_id для збереження iсторiї розмови. |
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"
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"
}
]
}
Приклад (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Список ваших останнiх сеансiв чату. Використовуйте це для виявлення ID сеансiв, якi потiм можна передати до /conversations/ для отримання повної iсторiї повiдомлень.
Параметри запиту
| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
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",
"website_domain": "example.com"
}
]
}
Приклад (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": "visitor@example.com",
"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": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Приклад (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Декілька сайтів? Кiнцевi точки бази знань за замовчуванням використовують ваш основний сайт. Якщо у вас декiлька сайтiв, передайте website_id для вибору конкретного. Ви можете знайти ID ваших сайтів за допомогою GET /websites/.
Щоденні ліміти завантаження: Завантаження в базу знань (текст, URL, таблицi) мають щоденний лiмiт символiв залежно вiд вашого тарифу. Це стосується загального обсягу контенту, завантаженого через усi кiнцевi точки бази знань за день.
| Тариф | Символів/день |
|---|---|
| Starter | 100 000 |
| Standard | 500 000 |
| Pro | 2 000 000 |
GET /knowledge/
Список записiв вашої бази знань. Це джерела контенту, якi ваш ШI-чатбот використовує для вiдповiдей на запитання.
Параметри запиту
| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
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/
Додайте власний текстовий контент до вашої бази знань. ШI буде використовувати це для вiдповiдей на запитання вiдвiдувачiв.
Тіло запиту
{
"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/
Додайте веб-сторiнку до вашої бази знань. Контент буде автоматично завантажено та вилучено.
Тіло запиту
{
"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) до вашої бази знань. Кожен рядок стає окремим записом бази знань, iдеально пiдходить для каталогiв товарiв, спискiв FAQ, таблиць цiн та довiдникiв.
Запит
Надсилайте як multipart/form-data (завантаження файлу), а не JSON.
| Параметр | Тип | Обов'язковий | Опис |
|---|---|---|---|
file |
file | Так | Файл .csv або .xlsx. Перший рядок повинен мiстити заголовки стовпцiв. Макс. рядкiв на завантаження: Starter 500, Standard 2 000, Pro 10 000. Зайвi рядки обрiзаються. |
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 "file=@products.csv"
DELETE /knowledge/{id}/
Видалити запис бази знань. id можна знайти у вiдповiдi 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 |
ШI ініціював ескалацію до живого оператора |
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 можна знайти у вiдповiдi 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 |
Сервіс недоступний - Сервіс ШI тимчасово недоступний |
Обмеження частоти запитів
Використання API обмежене вашим тарифним планом:
- Free: 100 повідомлень/місяць
- Starter ($39/міс.): 2 500 повідомлень/місяць
- Standard ($139/міс.): 15 000 повідомлень/місяць
- Pro ($449/міс.): 50 000 повідомлень/місяць
Потрібна допомога?
Якщо у вас є запитання або виникли проблеми, зв'яжiться з нами за адресою hello@asyntai.com.