API Интеграция

Изпращайте данни програмно към вашата AI SmartTalk база знания, използвайки нашия REST API. Идеален за персонализирани интеграции, автоматизирани потоци и всякакви източници на данни, които не са обхванати от нашите вградени конектори.

---

Преглед

Интеграцията на API ви позволява да:

• Изпращате документи директно към вашата база знания
• Актуализирате съдържание програмно
• Изтривате остарели записи
• Създавате персонализирани потоци от данни
• Интегрирате с всяка система, която може да прави HTTP заявки

---

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

Преди да започнете, уверете се, че имате:

• Активен акаунт в AI SmartTalk
• Включен достъп до API (проверете вашия план)
• Основни познания за REST APIs
• Инструмент за правене на HTTP заявки (curl, Postman или вашия код на приложението)

---

Получаване на вашите API удостоверения

Стъпка 1: Достъп до настройки на API

1. Влезте в акаунта си в AI SmartTalk
2. Навигирайте до Настройки → Интеграции
3. Намерете API и кликнете на Конфигуриране

Стъпка 2: Генериране на API токен

1. Кликнете на Генериране на нов токен
2. Копирайте вашия Chat Model ID и API токен
3. Съхранявайте ги на сигурно място - токенът се показва само веднъж!

⚠️ Предупреждение за сигурност: Никога не излагайте вашия API токен в клиентски код или публични хранилища.

---

API крайни точки

Основен URL

https://api.aismarttalk.tech/v1

Аутентикация

Всички заявки изискват вашия API токен в заглавката:

Authorization: Bearer YOUR_API_TOKEN

---

API Endpoints

Base URL

https://api.aismarttalk.tech/v1

Authentication

Всички заявки изискват вашия API токен в заглавката:

Authorization: Bearer YOUR_API_TOKEN

---

Import Documents

Endpoint

POST /documents/import

Request Body

{
  "chatModelId": "your-chat-model-id",
  "documents": [
    {
      "title": "Product Documentation",
      "content": "Full content of your document goes here...",
      "url": "https://example.com/docs/product",
      "metadata": {
        "category": "documentation",
        "language": "en"
      }
    }
  ]
}

Parameters

Field	Type	Required	Description
chatModelId	string	✅	Вашият уникален идентификатор на чат модела
documents	array	✅	Масив от обекти на документи
documents[].title	string	✅	Заглавие на документа за идентификация
documents[].content	string	✅	Пълен текстов съдържание
documents[].url	string	❌	Източник на URL (за справка)
documents[].metadata	object	❌	Персонализирани ключ-стойност двойки

Response

{
  "success": true,
  "imported": 1,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Product Documentation",
      "status": "processing"
    }
  ]
}

Example: cURL

curl -X POST https://api.aismarttalk.tech/v1/documents/import \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "chatModelId": "your-chat-model-id",
    "documents": [
      {
        "title": "Getting Started Guide",
        "content": "Welcome to our platform. Here is how to get started...",
        "url": "https://docs.example.com/getting-started"
      }
    ]
  }'

---

Query Documents

Задавайте въпроси на вашата база знания програмно.

Endpoint

POST /chat/query

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "How do I reset my password?",
  "options": {
    "maxTokens": 500,
    "temperature": 0.7
  }
}

Response

{
  "success": true,
  "response": "To reset your password, navigate to Settings > Security > Change Password...",
  "sources": [
    {
      "documentId": "doc_abc123",
      "title": "Security Guide",
      "relevance": 0.95
    }
  ]
}

---

Retrieve Documents

Получете документи, които отговарят на запитване (без AI отговор).

Endpoint

POST /documents/search

Request Body

{
  "chatModelId": "your-chat-model-id",
  "query": "password security",
  "limit": 10
}

Response

{
  "success": true,
  "documents": [
    {
      "id": "doc_abc123",
      "title": "Security Best Practices",
      "content": "...",
      "relevance": 0.92
    }
  ]
}

Примери за код

Python

import requests

API_TOKEN = "your-api-token"
CHAT_MODEL_ID = "your-chat-model-id"

def import_document(title: str, content: str, url: str = None):
    response = requests.post(
        "https://api.aismarttalk.tech/v1/documents/import",
        headers={
            "Authorization": f"Bearer {API_TOKEN}",
            "Content-Type": "application/json"
        },
        json={
            "chatModelId": CHAT_MODEL_ID,
            "documents": [{
                "title": title,
                "content": content,
                "url": url
            }]
        }
    )
    return response.json()

# Импортиране на документ
result = import_document(
    title="Често задавани въпроси: Доставка",
    content="Предлагаме безплатна доставка за поръчки над $50...",
    url="https://shop.example.com/faq/shipping"
)
print(result)

JavaScript / Node.js

const API_TOKEN = 'your-api-token';
const CHAT_MODEL_ID = 'your-chat-model-id';

async function importDocument(title, content, url = null) {
  const response = await fetch('https://api.aismarttalk.tech/v1/documents/import', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      chatModelId: CHAT_MODEL_ID,
      documents: [{
        title,
        content,
        url
      }]
    })
  });
  return response.json();
}

// Импортиране на документ
importDocument(
  'Често задавани въпроси: Връщане',
  'Можете да върнете артикули в рамките на 30 дни след покупката...',
  'https://shop.example.com/faq/returns'
).then(console.log);

PHP

<?php
$apiToken = 'your-api-token';
$chatModelId = 'your-chat-model-id';

$data = [
    'chatModelId' => $chatModelId,
    'documents' => [
        [
            'title' => 'Спецификации на продукта',
            'content' => 'Нашият уиджет има следните спецификации...',
            'url' => 'https://example.com/products/widget'
        ]
    ]
];

$ch = curl_init('https://api.aismarttalk.tech/v1/documents/import');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $apiToken,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));

$response = curl_exec($ch);
curl_close($ch);

print_r(json_decode($response, true));

---

Сценарии на употреба

Интеграция на персонализирана CMS

Синхронизиране на съдържание от собствена CMS:

• Свързване с събития за публикуване на CMS
• Изпращане на ново/актуализирано съдържание до AI SmartTalk
• Премахване на изтрито съдържание

Данни в поток

Импорт от хранилища на данни:

• Експорт на съответните данни в JSON
• Пакетен импорт чрез API
• Планиране на редовни актуализации

Продукти в електронна търговия

Синхронизиране на данни за продукти от персонализирани системи:

• Описания на продукти
• Спецификации
• Информация за цени

Вътрешни системи

Свързване на вътрешни инструменти, които не се поддържат нативно:

• Персонализирани уики
• Стари бази данни
• Собствени приложения

---

Лимити на заявките

Точка на достъп	Лимит на заявките
Импорт на документи	100 заявки/минута
Запитване	60 заявки/минута
Търсене	60 заявки/минута

Забележка: Лимитите на заявките варират в зависимост от плана. Свържете се с поддръжката за по-високи лимити.

---

Обработка на грешки

Формат на отговорите при грешки

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided API token is invalid or expired"
  }
}

Чести кодове на грешки

Код	Описание	Решение
INVALID_TOKEN	Невалиден или изтекъл токен	Регенерирайте API токена
INVALID_MODEL_ID	Неизвестен ID на чат модел	Проверете ID на вашия чат модел
RATE_LIMITED	Прекалено много заявки	Имплементирайте backoff, опитайте отново по-късно
INVALID_REQUEST	Неправилно форматирано тяло на заявката	Проверете JSON структурата
DOCUMENT_TOO_LARGE	Съдържанието надвишава лимита	Разделете на по-малки документи
QUOTA_EXCEEDED	Достигнати лимити на плана	Актуализирайте или се свържете с поддръжката

---

Отстраняване на проблеми

Провал на удостоверяване

Проблем	Решение
401 Неупълномощен	Проверете дали токенът е правилен и активен
Токенът не работи	Регенерирайте токена в настройките
Изтекъл токен	Токените не изтичат, но могат да бъдат оттеглени

Проблеми с импорта

Проблем	Решение
Празен отговор	Проверете дали Content-Type е application/json
Документът не се появява	Изчакайте обработката; проверете секцията Знания
Частичен импорт	Някои документи може да имат грешки при валидиране

Проблеми с производителността

Проблем	Решение
Бавен импорт	Групирайте документите (максимум 100 на заявка)
Таймаути	Намалете размера на групата, опитайте отново с backoff
Лимит на заявките	Имплементирайте експоненциален backoff

---

Най-добри практики

1. Групов импорт: Изпращайте множество документи на заявка (до 100)
2. Уникални заглавия: Използвайте описателни, уникални заглавия за всеки документ
3. Структурирано съдържание: Добре форматираното съдържание подобрява отговорите на AI
4. Тагове за метаданни: Използвайте метаданни за категоризация и филтриране
5. Сигурни токени: Съхранявайте токените в променливи на средата
6. Обработка на грешки: Имплементирайте логика за повторно опитване с експоненциален backoff
7. Наблюдение на употребата: Следете API повикванията спрямо лимитите на вашия план

---

Свързана документация

• Обзор на интеграциите
• Пълна документация на API
• Управление на база знания
• SmartFlow Webhooks — Получавайте събития