API справка
Създайте персонализирани интеграции с Asyntai REST API
Необходим е платен план: API достъпът е наличен в плановете Starter, Standard и Pro. Вижте ценоразписа
Преглед
API-то на Asyntai ви позволява да интегрирате клиентска поддръжка, задвижвана от ИИ, във всяко приложение. Изпращайте съобщения и получавайте интелигентни отговори, обучени на съдържанието на вашия уебсайт и базата знания.
Удостоверяване
Всички 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"
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/
Списък на скорошните ви чат сесии. Използвайте това, за да откриете 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",
"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 | Не | Филтриране на потенциални клиенти по конкретен идентификатор на уебсайт |
Отговор
{
"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 | Идентификатор на чат сесията. Предайте го на /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"
Множество уебсайтове? Крайните точки на базата знания използват по подразбиране основния ви уебсайт. Ако имате множество уебсайтове, подайте website_id за да насочите конкретен. Можете да намерите идентификаторите на уебсайтовете си с помощта на GET /websites/.
Дневни лимити за качване: Качванията в базата знания (текст, URL, таблица) подлежат на дневен лимит на символи, базиран на вашия план. Това се отнася за общото съдържание, качено чрез всички крайни точки на базата знания на ден.
| План | Символи/ден |
|---|---|
| Starter | 100 000 |
| Standard | 500 000 |
| Pro | 2 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 "file=@products.csv"
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 съобщения/месец
Нуждаете се от помощ?
Ако имате въпроси или срещнете проблеми, свържете се с нас на hello@asyntai.com.