Rujukan API
Bina integrasi tersuai dengan API REST Asyntai
Pelan Berbayar Diperlukan: Akses API tersedia pada pelan Starter, Standard, dan Pro. Lihat harga
Gambaran Keseluruhan
API Asyntai membolehkan anda mengintegrasikan sokongan pelanggan berkuasa AI ke dalam mana-mana aplikasi. Hantar mesej dan terima respons pintar yang dilatih pada kandungan laman web dan pangkalan pengetahuan anda.
Pengesahan
Semua permintaan API memerlukan pengesahan menggunakan kunci API anda. Anda boleh mendapatkan kunci API anda dari halaman Tetapan API.
Sertakan kunci API anda dalam permintaan menggunakan salah satu kaedah ini:
- Pengepala Authorization (disyorkan):
Authorization: Bearer YOUR_API_KEY - Pengepala X-API-Key:
X-API-Key: YOUR_API_KEY
Rahsiakan kunci API anda. Sesiapa yang mempunyai kunci anda boleh mengakses akaun anda melalui API. Jangan dedahkannya dalam kod sisi klien.
URL Asas
https://asyntai.com/api/v1/
Titik Akhir
POST /chat/
Hantar mesej dan terima respons yang dijana oleh AI.
Badan Permintaan
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
message |
string | Ya | Mesej pengguna untuk dihantar kepada AI |
session_id |
string | Tidak | Pengecam unik untuk perbualan. Gunakan session_id yang sama untuk mengekalkan sejarah perbualan. |
website_id |
integer | Tidak | ID laman web khusus. Jika tidak disediakan, menggunakan laman web utama anda. |
Respons
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Contoh (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"}'
Contoh (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"])
Contoh (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/
Senaraikan semua laman web yang dikaitkan dengan akaun anda.
Respons
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Contoh (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Dapatkan semula sejarah perbualan untuk sesi tertentu.
Parameter Pertanyaan
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
session_id |
string | Ya | ID sesi untuk mendapatkan semula sejarah |
limit |
integer | Tidak | Mesej maksimum untuk dikembalikan (lalai: 50, maks: 100) |
Respons
{
"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"
}
]
}
Contoh (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Senaraikan sesi sembang terkini anda. Gunakan ini untuk menemui ID sesi, yang kemudian anda boleh hantar ke /conversations/ untuk mendapatkan semula sejarah mesej penuh.
Parameter Pertanyaan
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
limit |
integer | Tidak | Bilangan sesi terkini untuk dikembalikan (lalai: 20, maks: 100) |
website_id |
string | Tidak | Tapis sesi mengikut ID laman web tertentu |
source |
string | Tidak | Tapis mengikut sumber sesi: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Respons
{
"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"
}
]
}
Contoh (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Dapatkan prospek yang dikumpul — alamat e-mel dan nombor telefon yang dihantar oleh pelawat semasa perbualan sembang.
Parameter Pertanyaan
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
limit |
integer | Tidak | Bilangan prospek untuk dikembalikan (lalai: 50, maks: 100) |
website_id |
string | Tidak | Tapis prospek mengikut ID laman web tertentu |
Respons
{
"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"
}
]
}
| Medan | Jenis | Penerangan |
|---|---|---|
session_id |
string | ID sesi sembang. Hantar ini ke /conversations/ untuk melihat sejarah sembang penuh. |
email |
rentetan atau null | Alamat e-mel yang diberikan oleh pelawat, atau null jika tidak dikumpul |
phone |
rentetan atau null | Nombor telefon yang diberikan oleh pelawat, atau null jika tidak dikumpul |
page_url |
rentetan atau null | URL halaman di mana pelawat sedang bersembang |
started_at |
string | Cap masa ISO 8601 bila sesi sembang bermula |
Contoh (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Contoh (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/
Dapatkan maklumat akaun dan statistik penggunaan anda.
Respons
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Contoh (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
Pelbagai laman web? Titik akhir pangkalan pengetahuan lalai kepada laman web utama anda. Jika anda mempunyai pelbagai laman web, hantar website_id untuk menyasarkan yang tertentu. Anda boleh mencari ID laman web anda menggunakan GET /websites/.
Had muat naik harian: Muat naik pangkalan pengetahuan (teks, URL, hamparan) tertakluk pada had aksara harian berdasarkan pelan anda. Ini terpakai pada jumlah kandungan yang dimuat naik merentasi semua titik akhir pangkalan pengetahuan setiap hari.
| Pelan | Aksara/hari |
|---|---|
| Starter | 100,000 |
| Standard | 500,000 |
| Pro | 2,000,000 |
GET /knowledge/
Senaraikan entri pangkalan pengetahuan anda. Ini adalah sumber kandungan yang digunakan oleh chatbot AI anda untuk menjawab soalan.
Parameter Pertanyaan
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
limit |
integer | Tidak | Bilangan entri untuk dikembalikan (lalai: 50, maks: 100) |
website_id |
string | Tidak | Tapis mengikut ID laman web (lalai kepada laman web utama anda) |
Respons
{
"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"
}
]
}
Contoh (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Tambah kandungan teks tersuai ke pangkalan pengetahuan anda. AI akan menggunakan ini untuk menjawab soalan pelawat.
Badan Permintaan
{
"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"
}
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
title |
string | Ya | Tajuk untuk entri pengetahuan ini |
content |
string | Ya | Kandungan teks (minimum 10 aksara) |
website_id |
string | Tidak | Laman web sasaran (lalai kepada laman web utama anda) |
Respons
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Contoh (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/
Tambah halaman web ke pangkalan pengetahuan anda. Kandungan akan diambil dan diekstrak secara automatik.
Badan Permintaan
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
url |
string | Ya | URL untuk mengambil kandungan |
website_id |
string | Tidak | Laman web sasaran (lalai kepada laman web utama anda) |
Respons
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Contoh (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/
Muat naik hamparan CSV atau Excel (.xlsx) ke pangkalan pengetahuan anda. Setiap baris menjadi entri pengetahuan berasingan, sesuai untuk katalog produk, senarai Soalan Lazim, jadual harga, dan direktori.
Permintaan
Hantar sebagai multipart/form-data (muat naik fail), bukan JSON.
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
file |
fail | Ya | Fail .csv atau .xlsx. Baris pertama mesti menjadi pengepala lajur. Baris maksimum setiap muat naik: Starter 500, Standard 2,000, Pro 10,000. Baris lebihan akan dipotong. |
website_id |
string | Tidak | Laman web sasaran (lalai kepada laman web utama anda) |
Respons
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Contoh (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Padam entri pangkalan pengetahuan. id boleh didapati dari respons GET /knowledge/.
Respons
{
"success": true,
"message": "Knowledge base entry deleted"
}
Contoh (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Petua: Anda juga boleh mengurus webhooks dari Tetapan API halaman tanpa menulis sebarang kod.
GET /webhooks/
Senaraikan webhooks berdaftar anda.
Respons
{
"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"
}
]
}
Contoh (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Daftar webhook baharu untuk menerima pemberitahuan acara masa nyata.
Acara Tersedia
| Acara | Penerangan |
|---|---|
message.received |
Seorang pelawat menghantar mesej dan menerima respons |
conversation.started |
Sesi sembang baharu telah dimulakan |
escalation.requested |
AI mencetuskan eskalasi kepada ejen manusia |
takeover.started |
Ejen manusia mengambil alih sesi sembang |
Badan Permintaan
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Parameter | Jenis | Diperlukan | Penerangan |
|---|---|---|---|
url |
string | Ya | URL HTTPS untuk menerima permintaan POST webhook |
events |
array | Ya | Senarai acara untuk dilanggan (lihat jadual di atas) |
website_id |
string | Tidak | Laman web sasaran (lalai kepada laman web utama anda) |
Respons
{
"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"
}
}
Mengesahkan webhooks: Setiap webhook termasuk secret (ditunjukkan hanya semasa penciptaan). Setiap POST ke URL anda termasuk X-Webhook-Signature header — HMAC-SHA256 bagi badan permintaan yang ditandatangani dengan kunci rahsia anda.
Contoh (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}/
Padam webhook. id boleh didapati dari respons GET /webhooks/.
Respons
{
"success": true,
"message": "Webhook deleted"
}
Contoh (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Respons Ralat
Semua respons ralat mengikut format ini:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Kod Status | Penerangan |
|---|---|
400 |
Permintaan Tidak Sah - Parameter tidak sah atau medan wajib tiada |
401 |
Tidak Dibenarkan - Kunci API tidak sah atau tiada |
429 |
Terlalu Banyak Permintaan - Had mesej dicapai untuk pelan anda |
503 |
Perkhidmatan Tidak Tersedia - Perkhidmatan AI tidak tersedia buat sementara |
Had Kadar
Penggunaan API dihadkan oleh pelan langganan anda:
- Free: 100 mesej/bulan
- Starter ($39/bln): 2,500 mesej/bulan
- Standard ($139/bln): 15,000 mesej/bulan
- Pro ($449/bln): 50,000 mesej/bulan
Perlukan Bantuan?
Jika anda mempunyai sebarang soalan atau menghadapi masalah, hubungi kami di hello@asyntai.com.