Referensi API
Bangun integrasi kustom dengan REST API Asyntai
Diperlukan Paket Berbayar: Akses API tersedia pada paket Starter, Standard, dan Pro. Lihat harga
Ringkasan
API Asyntai memungkinkan Anda mengintegrasikan dukungan pelanggan bertenaga AI ke aplikasi apa pun. Kirim pesan dan terima respons cerdas yang dilatih dari konten situs web dan basis pengetahuan Anda.
Autentikasi
Semua permintaan API memerlukan autentikasi menggunakan kunci API Anda. Anda dapat mendapatkan kunci API dari halaman Pengaturan API.
Sertakan kunci API Anda dalam permintaan menggunakan salah satu metode berikut:
- Header Authorization (disarankan):
Authorization: Bearer YOUR_API_KEY - Header X-API-Key:
X-API-Key: YOUR_API_KEY
Jaga kerahasiaan kunci API Anda. Siapa pun yang memiliki kunci Anda dapat mengakses akun Anda melalui API. Jangan pernah mengeksposnya di kode sisi klien.
URL Dasar
https://asyntai.com/api/v1/
Endpoint
POST /chat/
Kirim pesan dan terima respons yang dihasilkan AI.
Isi Permintaan
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
message |
string | Ya | Pesan pengguna untuk dikirim ke AI |
session_id |
string | Tidak | Pengidentifikasi unik untuk percakapan. Gunakan session_id yang sama untuk mempertahankan riwayat percakapan. |
website_id |
integer | Tidak | ID situs web tertentu. Jika tidak disediakan, gunakan situs 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/
Daftar semua situs web yang terkait dengan akun 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/
Ambil riwayat percakapan untuk sesi tertentu.
Parameter Kueri
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
session_id |
string | Ya | ID sesi untuk mengambil riwayat |
limit |
integer | Tidak | Jumlah pesan maksimum yang dikembalikan (default: 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/
Daftar sesi chat terbaru Anda. Gunakan ini untuk menemukan ID sesi, yang kemudian dapat Anda kirimkan ke /conversations/ untuk mengambil riwayat pesan lengkap.
Parameter Kueri
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
limit |
integer | Tidak | Jumlah sesi terbaru yang dikembalikan (default: 20, maks: 100) |
website_id |
string | Tidak | Filter sesi berdasarkan ID situs web tertentu |
source |
string | Tidak | Filter berdasarkan 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/
Ambil prospek yang dikumpulkan — alamat email dan nomor telepon yang dikirimkan oleh pengunjung selama percakapan chat.
Parameter Kueri
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
limit |
integer | Tidak | Jumlah prospek yang dikembalikan (default: 50, maks: 100) |
website_id |
string | Tidak | Filter prospek berdasarkan ID situs 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"
}
]
}
| Kolom | Tipe | Deskripsi |
|---|---|---|
session_id |
string | ID sesi obrolan. Teruskan ke /conversations/ untuk melihat riwayat obrolan lengkap. |
email |
string atau null | Alamat email yang diberikan pengunjung, atau null jika tidak dikumpulkan |
phone |
string atau null | Nomor telepon yang diberikan pengunjung, atau null jika tidak dikumpulkan |
page_url |
string atau null | URL halaman tempat pengunjung mengobrol |
started_at |
string | Stempel waktu ISO 8601 saat sesi obrolan dimulai |
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 informasi akun 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"
Beberapa situs web? Endpoint basis pengetahuan default ke situs web utama Anda. Jika Anda memiliki beberapa situs web, kirimkan website_id untuk menargetkan yang spesifik. Anda dapat menemukan ID situs web Anda menggunakan GET /websites/.
Batas unggahan harian: Unggahan basis pengetahuan (teks, URL, spreadsheet) tunduk pada batas karakter harian berdasarkan paket Anda. Ini berlaku untuk total konten yang diunggah di semua endpoint basis pengetahuan per hari.
| Paket | Karakter/hari |
|---|---|
| Starter | 100.000 |
| Standard | 500.000 |
| Pro | 2.000.000 |
GET /knowledge/
Daftar entri basis pengetahuan Anda. Ini adalah sumber konten yang digunakan chatbot AI Anda untuk menjawab pertanyaan.
Parameter Kueri
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
limit |
integer | Tidak | Jumlah entri yang dikembalikan (default: 50, maks: 100) |
website_id |
string | Tidak | Filter berdasarkan ID situs web (default ke situs 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/
Tambahkan konten teks kustom ke basis pengetahuan Anda. AI akan menggunakan ini untuk menjawab pertanyaan pengunjung.
Isi 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 | Tipe | Wajib | Deskripsi |
|---|---|---|---|
title |
string | Ya | Judul untuk entri pengetahuan ini |
content |
string | Ya | Konten teks (minimal 10 karakter) |
website_id |
string | Tidak | Situs web target (default ke situs 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/
Tambahkan halaman web ke basis pengetahuan Anda. Konten akan diambil dan diekstrak secara otomatis.
Isi Permintaan
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
url |
string | Ya | URL untuk mengambil konten |
website_id |
string | Tidak | Situs web target (default ke situs 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/
Unggah spreadsheet CSV atau Excel (.xlsx) ke basis pengetahuan Anda. Setiap baris menjadi entri pengetahuan terpisah, ideal untuk katalog produk, daftar FAQ, tabel harga, dan direktori.
Permintaan
Kirim sebagai multipart/form-data (unggah file), bukan JSON.
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
file |
file | Ya | File .csv atau .xlsx. Baris pertama harus berupa header kolom. Maks baris per unggahan: Starter 500, Standard 2.000, Pro 10.000. Baris berlebih akan dipotong. |
website_id |
string | Tidak | Situs web target (default ke situs 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}/
Hapus entri basis pengetahuan. id dapat ditemukan 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"
Tip: Anda juga dapat mengelola webhook dari Pengaturan API halaman tanpa menulis kode apa pun.
GET /webhooks/
Daftar webhook terdaftar 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/
Daftarkan webhook baru untuk menerima notifikasi event secara real-time.
Event yang Tersedia
| Event | Deskripsi |
|---|---|
message.received |
Pengunjung mengirim pesan dan menerima respons |
conversation.started |
Sesi chat baru telah dimulai |
escalation.requested |
AI memicu eskalasi ke agen manusia |
takeover.started |
Agen manusia mengambil alih sesi chat |
Isi Permintaan
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
url |
string | Ya | URL HTTPS untuk menerima permintaan POST webhook |
events |
array | Ya | Daftar event untuk berlangganan (lihat tabel di atas) |
website_id |
string | Tidak | Situs web target (default ke situs 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"
}
}
Memverifikasi webhook: Setiap webhook menyertakan secret (ditampilkan hanya saat pembuatan). Setiap POST ke URL Anda menyertakan X-Webhook-Signature header — HMAC-SHA256 dari badan permintaan yang ditandatangani dengan kunci rahasia 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}/
Hapus webhook. id dapat ditemukan 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 Error
Semua respons error mengikuti format ini:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Kode Status | Deskripsi |
|---|---|
400 |
Permintaan Buruk - Parameter tidak valid atau kolom wajib hilang |
401 |
Tidak Terotorisasi - Kunci API tidak valid atau hilang |
429 |
Terlalu Banyak Permintaan - Batas pesan tercapai untuk paket Anda |
503 |
Layanan Tidak Tersedia - Layanan AI sementara tidak tersedia |
Batas Laju
Penggunaan API dibatasi oleh paket langganan Anda:
- Free: 100 pesan/bulan
- Starter ($39/bln): 2.500 pesan/bulan
- Standard ($139/bln): 15.000 pesan/bulan
- Pro ($449/bln): 50.000 pesan/bulan
Butuh Bantuan?
Jika Anda memiliki pertanyaan atau mengalami masalah, hubungi kami di hello@asyntai.com.