Повернутися до панелі керування

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

Дізнайтеся, як використовувати Asyntai

Довідник API

Створюйте власні інтеграції з Asyntai REST API

Отримати ключ 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 точки бази знань за день.

Тариф Символів/день
Starter100 000
Standard500 000
Pro2 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.