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

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

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

API справка

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

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

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