Kembali ke Papan Pemuka

Dokumentasi

Ketahui cara menggunakan Asyntai

Rujukan API

Bina integrasi tersuai dengan API REST Asyntai

Dapatkan Kunci API

Pelan Berbayar Diperlukan: Akses API tersedia pada pelan Starter, Standard, dan Pro. Lihat harga

Gambaran Keseluruhan

The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses grounded in your website content and knowledge base.

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"

POST /websites/

Create a new AI agent. This does the same thing as adding a website in your dashboard: it makes the agent, reads your site, and writes the first draft of the AI instructions.

Use this to set up customers from your own software. You get back the widget ID and the code to put on the website.

Badan Permintaan

Medan Jenis Penerangan
domain string Required. The website address, for example example.com
name string Optional. A display name for the agent. Useful when one website has several agents.
crawl boolean Optional, true by default. Set it to false to create the agent without reading the website. Nothing is crawled and no instructions are written.
force boolean Optional, false by default. Set it to true to add a website you already have. The copy is stored with a number after it.

Respons

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "crawl_started": true,
    "instructions_status": "generating",
    "job_id": "8f2c1e90-..."
  },
  "embed_code": "<script>...</script>"
}

Contoh (cURL)

curl -X POST https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "name": "Support agent"}'

Reading a website takes a few minutes, so this call answers straight away. Check when the agent is ready with the next endpoint.

Errors

Code Meaning
403 You have reached the number of websites your plan allows. The answer tells you the limit.
409 Your account already has this website. Send force as true to add it again.

GET /websites/{id}/

Get one website and see whether it is ready. Use this after you create an agent, to wait until the website has been read and the AI instructions are written.

Respons

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "created_at": "2026-08-11T09:12:00+00:00",
    "ready": true,
    "instructions": {
      "status": "completed",
      "has_instructions": true,
      "characters": 3421
    },
    "crawl": {
      "job_id": "8f2c1e90-...",
      "status": "completed",
      "pages_crawled": 47,
      "pages_found": 50,
      "max_pages": 50,
      "completed_at": "2026-08-11T09:15:31+00:00",
      "error": ""
    },
    "knowledge_items": 47
  },
  "embed_code": "<script>...</script>"
}

The ready field is true when nothing is still running. A crawl that failed also counts as ready, because it has finished. Look at the crawl status to see what happened.

Contoh (cURL)

curl https://asyntai.com/api/v1/websites/42/ \
  -H "Authorization: Bearer YOUR_API_KEY"

GET PATCH /websites/{id}/settings/

Read or change the chat widget settings for one website. These are the same settings you see on the Customize page: colours, the name of the assistant, the first message, lead capture, and everything else.

Reading the settings

A GET request returns every setting with its current value, plus a locked list. Locked shows the settings your plan cannot change, and which plans they need.

{
  "success": true,
  "settings": {
    "ai_support_name": "AI Assistant",
    "widget_color": "#6366f1",
    "initial_message": "Hi, how can I help you?",
    "hide_branding": false,
    "...": "..."
  },
  "locked": {
    "hide_branding": ["pro", "enterprise"],
    "widget_style": ["pro", "enterprise"]
  }
}

Changing the settings

A PATCH request changes only the settings you send. Everything you leave out stays as it is.

curl -X PATCH https://asyntai.com/api/v1/websites/42/settings/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ai_support_name": "Ava", "widget_color": "#0f172a", "use_emoji": true}'
{
  "success": true,
  "updated": ["ai_support_name", "use_emoji", "widget_color"],
  "settings": { "...": "..." },
  "locked": { "...": "..." }
}

Plans

Each setting needs its own plan, the same as in the dashboard. For example, hiding the Asyntai branding needs the Pro plan, and voice input needs Standard.

Plan needed Tetapan Examples
Any paid plan 25 widget_color, ai_support_name, initial_message
Starter dan ke atas 22 profile_picture, conversation_starters_enabled
Standard dan ke atas 25 speech_to_text_enabled, image_vision_enabled, escalation_enabled
Pro 6 hide_branding, widget_style

If you send a setting your plan does not allow, the whole request is refused with code 403 and nothing is saved. The same happens if any value is wrong, for example a colour that is not a hex code. Your settings never end up half changed.

GET PUT /websites/{id}/instructions/

Read or replace the AI instructions for one website. These are the rules that tell the assistant who it is, what it may say, and what it must not say. They are the same instructions you edit in the dashboard.

Reading

{
  "success": true,
  "instructions": "You are the support agent for Acme Tools...",
  "characters": 1979,
  "version": 7,
  "mode": "instructions",
  "ask_questions": true,
  "generation_status": "completed",
  "being_edited_by": null
}

Replacing

A PUT request replaces the whole text, the same as saving in the dashboard. There is no append mode. To add a paragraph, read the instructions, add your text, then write it back.

curl -X PUT https://asyntai.com/api/v1/websites/42/instructions/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You are the support agent for Acme Tools...", "version": 7}'

Badan Permintaan

Medan Jenis Penerangan
instructions string Required. The complete new text. It replaces everything that was there.
version number Optional but recommended. The version you read. If somebody changed the instructions since then, your write is refused instead of overwriting their work.
mode string Optional. Either instructions or general.
ask_questions boolean Optional. Whether the assistant asks a follow-up question at the end of its answers.
force boolean Optional, false by default. Needed only when your new text is less than half the length of the current text.

How your instructions are protected

Instructions can take hours to write, so a write can be refused to protect them:

Code Meaning
400 Your new text is less than half the length of the current text. This catches a script that sends empty or cut-off text over instructions somebody spent hours on. Send force as true if you meant it.
409 The instructions changed after you read them. Read them again, apply your change, then write.
423 Somebody is editing the instructions in the dashboard right now. The answer tells you who. Try again in a couple of minutes.

Every change also saves a copy of the previous text, so an earlier version can always be restored from the dashboard.

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",
      "sender_type": "ai",
      "agent_name": null,
      "response_time_ms": 1840.5
    }
  ]
}

Soalan dan jawapannya disimpan dalam satu rekod, jadi kedua-duanya membawa timestamp yang sama. Jangan tolak satu daripada yang lain untuk mengukur kelajuan balasan, kerana hasilnya sentiasa sifar. Gunakan response_time_ms, iaitu masa sebenar yang diambil oleh jawapan, dalam milisaat.

sender_type ialah ai apabila chatbot menjawab, dan human apabila salah seorang ejen anda mengambil alih sembang. agent_name mengandungi nama paparan ejen tersebut.

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",
      "first_response_time_ms": 1840.5,
      "first_human_response_at": null,
      "started_at": "2024-01-15T10:29:58Z",
      "ended_at": "2024-01-15T10:41:12Z",
      "taken_over_at": null,
      "website_domain": "example.com"
    }
  ]
}

Medan cap masa untuk pelaporan

Medan Penerangan
started_at Bila pelawat membuka sembang. Tersedia untuk sesi widget sahaja, kerana sesi yang dicipta melalui API tidak pernah membuka widget.
first_message_at Bila mesej pertama perbualan disimpan.
first_response_time_ms Berapa lama jawapan pertama mengambil masa, dalam milisaat. Gunakan ini untuk masa respons pertama.
first_human_response_at Bila salah seorang ejen anda menghantar balasan pertama. Nilainya null apabila chatbot mengendalikan keseluruhan perbualan.
taken_over_at Bila seorang ejen mengambil alih sembang daripada chatbot.
last_message_at Bila mesej terakhir perbualan disimpan.
ended_at Bila pelawat meninggalkan sembang. Sembang tidak mempunyai status selesai atau ditutup, kerana pelawat sentiasa boleh kembali dan bertanya soalan lain.

Semua cap masa dalam UTC dan menggunakan format ISO 8601. Anda tidak boleh menukar zon waktu. Tukarkan nilai dalam alat pelaporan anda sendiri.

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": "[email protected]",
      "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": "[email protected]",
    "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
Starter300,000
Standard1,500,000
Pro6,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 "[email protected]"

GET /knowledge/{id}/

Baca satu entri pangkalan pengetahuan, termasuk teks yang disimpan untuknya. Nilai id datang daripada respons GET /knowledge/.

Kandungan dikembalikan bagi entri yang anda tambah sendiri: teks, fail, hamparan, URL tunggal dan video. Perayapan laman web tersenarai, tetapi halamannya tidak dikembalikan, kerana sumbernya ialah laman web awam anda sendiri. Dalam keadaan itu content ialah null dan medan reason menerangkan sebabnya.

Respons

{
  "success": true,
  "id": "abc-123-def",
  "type": "text",
  "title": "Business Hours",
  "description": "Manual text content (150 words)",
  "created_at": "2024-01-15T10:30:00Z",
  "chunks_count": 3,
  "content": "We are open Monday to Friday, 9am to 5pm...",
  "content_available": true,
  "char_count": 43
}

Contoh (cURL)

curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

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 [email protected].