API

Baca dan tulis ruang kerja anda dari sistem anda sendiri dengan API key, dan diberitahu bila sesuatu berlaku.

aiBalas ada REST API di https://aibalas.com/api/v1, untuk sistem anda sendiri: skrip yang menarik lead anda ke dalam spreadsheet, papan pemuka yang memerhati penggunaan ejen anda, kerja yang menyalin setiap perbualan ke gudang data anda sendiri setiap malam. Anda panggil ia dengan API key dan bukan log masuk, dan setiap respons ialah JSON. Ia baca dan tulis ruang kerja anda, dan webhook memberitahu sistem anda sebaik sahaja sesuatu berlaku.

Dapatkan API key

1. 1Buka Developers dalam ruang kerja anda (pemilik sahaja, pada pelan berbayar) dan pilih "Cipta key".
2. 2Pilih scope yang diperlukan API key itu dan, jika anda mahu hadkan kepada satu ejen sahaja, ejen yang mana. API key tanpa ejen dipilih boleh baca merentasi setiap ejen dalam ruang kerja.
3. 3Salin API key itu. Ia ditunjukkan sekali sahaja, penuh, dan tidak lagi: jika hilang, revoke ia dan cipta satu lagi.

API key itu milik ruang kerja, bukan milik orang yang mencipta ia: membuang orang itu daripada pasukan anda tidak revoke API key mereka.

Pengesahan

curl https://aibalas.com/api/v1/me \
  -H "Authorization: Bearer aib_..."

Membaca data

• Ejen: senarai ejen anda dan satu mengikut id (setiap satu menyatakan sama ada ia dihidupkan, botEnabled), serta berapa setiap satu belanjakan bulan ini, dan satu endpoint usage seluruh ruang kerja yang menjumlahkan semua ejen sekali (untuk key yang tidak dihadkan kepada satu ejen).
• Baki seseorang ejen termasuk baki top-up kongsi ruang kerja yang boleh digunakannya, dan pada pelan legacy, penanda hampir-had mencerminkan penggunaan terkumpul seluruh ruang kerja.
• Kenalan: semua orang merentasi ruang kerja, atau kenalan satu ejen dan satu kenalan mengikut id.
• Perbualan: perbualan satu ejen, dan mesej di dalam satu perbualan.
• Tempahan: perkhidmatan tempahan satu ejen, tempahannya, dan satu tempahan mengikut id.
• Katalog: knowledge, products dan promotions satu ejen.
• Templat dan broadcast: templat satu ejen, broadcast-nya, dan penerima satu broadcast.
• Setiap endpoint, dan bentuk tepatnya, tertulis dalam dokumen OpenAPI di /api/v1/openapi.json.

curl "https://aibalas.com/api/v1/agents/{agentId}/contacts?limit=20" \
  -H "Authorization: Bearer aib_..."

Cursor dan senarai

Senarai mengambil limit (sehingga seratus setiap muka surat) dan cursor yang legap: minta muka surat seterusnya dengan cursor yang respons sebelumnya beri sebagai next_cursor (nilai yang sama turut dihantar sebagai nextCursor), dan berhenti bila ia pulang null. Penerima satu broadcast berhalaman secara berbeza, dengan nombor page biasa. Id kenalan sendiri boleh membawa kolon (tg:123, untuk kenalan Telegram), jadi URL-encode ia dahulu sebelum letak dalam path: tg%3A123.

Menulis data

Ciptaan dan kemas kini ikut peraturan yang sama seperti console: medan kenalan disahkan dengan cara yang sama, tempahan guna sekatan tempahan-berganda yang sama, products dan knowledge base ada had saiz yang sama. Setiap penulisan direkodkan dalam log aktiviti ruang kerja terhadap API key yang membuatnya.

• POST /v1/agents/{agentId}/contacts — cipta kenalan; PATCH …/contacts/{contactId} — profil, medan lead, kategori, urgency, mode.
• POST /v1/agents/{agentId}/conversations/{contactId}/messages — hantar mesej manusia kepada seseorang yang sudah menghantar mesej dahulu. Ejen berhenti seketika untuk kenalan itu melainkan anda hantar "pause": false.
• POST …/conversations/{contactId}/mode — serahkan perbualan kepada manusia ("human") atau kembalikan kepada ejen ("bot").
• POST /v1/agents/{agentId}/bookings dan POST …/bookings/{id}/cancel.
• PUT /v1/agents/{agentId}/knowledge — ganti knowledge base; POST/PATCH/DELETE products dan promotions.
• PATCH /v1/agents/{agentId} dengan { "botEnabled": false } matikan ejen.

curl -X POST https://aibalas.com/api/v1/agents/AGENT_ID/contacts \
  -H "Authorization: Bearer aib_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-lead-8841" \
  -d '{"id":"60123456789","displayName":"Ali","email":"[email protected]","tags":["vip"]}'

Idempotency

Hantar header Idempotency-Key (sehingga 128 aksara, unik bagi setiap permintaan) pada mana-mana ciptaan. Mengulang key yang sama dengan body yang sama dalam masa 24 jam memulangkan respons pertama semula, bersama header Location dan ETag serta Idempotent-Replayed: true, dan bukan mencipta rekod kedua. Menggunakan semula key dengan body yang BERBEZA ditolak dengan 409 conflict, reason idempotency_key_reused: gunakan key baharu untuk permintaan baharu. Jika permintaan terdahulu dengan key itu terputus sebelum ia menjawab, cubaan semula mendapat 409 conflict dengan reason outcome_unknown — semak sama ada ia berkesan, kemudian gunakan key baharu. Key ini opsyenal di mana-mana kecuali menghantar mesej, di situ ia diwajibkan — cubaan semula tanpanya boleh menghantar mesej kepada pelanggan dua kali.

curl -X POST https://aibalas.com/api/v1/agents/AGENT_ID/conversations/60123456789/messages \
  -H "Authorization: Bearer aib_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: reply-2026-09-23-001" \
  -d '{"text":"Hi Ali, your order has shipped.","pause":true}'

Mencipta dan mengemas kini

Ciptaan menjawab 201 dengan header Location yang menamakan rekod baharu. GET pada satu kenalan, produk atau promosi memulangkan header ETag. Hantar ia semula sebagai If-Match pada PATCH, dan penulisan ditolak dengan 412 precondition_failed jika rekod itu berubah sejak anda membacanya — respons membawa ETag semasa, jadi ambil semula dan cuba lagi. PATCH tanpa If-Match berkesan seperti biasa.

Ralat

Setiap ralat kembali sebagai JSON: satu kod, mesej yang ditulis untuk dibaca manusia, dan kadang-kadang butiran tambahan sekali. Kodnya ialah unauthorized, forbidden, plan_required, scope_required, account_suspended, not_found, validation, rate_limited, payload_too_large, upstream, unavailable, conflict, over_budget, precondition_failed, method_not_allowed dan internal. conflict membawa reason — exists, slot_taken, store_owned, already_cancelled, in_progress, idempotency_key_reused atau outcome_unknown; rate_limited membawa retry_after (turut dihantar sebagai retryAfter) dalam saat, sama seperti header Retry-After; over_budget membawa block, used dan max; upstream bermaksud kami tidak dapat sahkan apa yang berlaku di pihak kami (selalunya penghantaran mesej) — semak dahulu sebelum cuba semula, lihat Idempotency di atas. Setiap respons membawa header X-Request-Id: sebut ia kepada kami jika anda perlukan bantuan. Hantar X-Request-Id anda sendiri (8 hingga 128 huruf, digit dan . _ : -) dan kami akan menggunakannya, supaya satu permintaan boleh dijejak dari log anda ke log kami. Ralat tidak dijangka di pihak kami ialah 500 internal, dan body-nya mengulang id itu sebagai requestId; gangguan singkat pada perkhidmatan yang kami bergantung ialah 503 unavailable dengan header Retry-After, jadi cuba semula. Path yang tidak wujud juga mendapat 404 dalam JSON, dan method yang tidak diterima oleh sesuatu endpoint ialah 405 method_not_allowed dengan header Allow. Setiap penulisan menolak field yang tidak dikenali, dan menamakannya di bawah fields, dan bukan mengabaikannya.

{
  "error": "rate_limited",
  "message": "Too many requests. Try again shortly.",
  "retry_after": 12,
  "retryAfter": 12
}

Had

Satu API key boleh buat 120 permintaan seminit, dengan lonjakan sehingga 240 selepas tempoh senyap: jadi X-RateLimit-Remaining boleh sekejap membaca lebih tinggi daripada X-RateLimit-Limit, dan itu memang dijangka, bukan pepijat. Menghantar mesej, apabila ia dilancarkan nanti, dihadkan berasingan pada 30 seminit. Kegagalan pengesahan berulang dari satu alamat turut dilambatkan, jadi skrip yang cuba API key yang salah berulang-ulang akan melambatkan dirinya sendiri.

Perubahan

API ini tambahan sahaja: medan ditambah, tidak pernah dinamakan semula atau dibuang, dan endpoint yang wujud hari ini terus wujud. Jika kami perlu memecahkan janji itu, ia keluar sebagai versi baharu, /v2, di sebelah yang ini, jadi apa-apa yang sudah dibina atas /v1 tidak terhenti secara tiba-tiba.

Webhooks

Webhook ialah URL anda sendiri yang aiBalas panggil setiap kali sesuatu berlaku dalam ruang kerja anda: mesej masuk, lead menjadi panas, tempahan dibuat. Cipta satu di halaman Developers (pemilik sahaja): beri URL https:// awam, pilih event yang patut diterima dan, jika mahu, hadkan kepada satu ejen. Rahsia tandatangan (signing secret) ditunjukkan sekali sahaja, semasa webhook dicipta; salin ketika itu. Endpoint yang sama boleh diurus melalui API dengan API key yang ada skop webhooks:manage, di /v1/webhooks. API key yang dihadkan kepada satu ejen hanya nampak, dan hanya boleh mencipta, webhook untuk ejen itu. Menghidupkan semula webhook yang dimatikan hanya boleh dibuat di halaman Developers.

Event

• message.received — pelanggan menulis kepada salah satu ejen anda.
• message.sent — ejen anda, seseorang dalam pasukan anda, atau API menghantar mesej kepada pelanggan.
• message.failed — mesej tidak dapat dihantar. Inilah satu-satunya cara untuk tahu bahawa penghantaran yang API terima dengan 202 tidak keluar.
• conversation.handoff — ejen menyerahkan perbualan kepada manusia.
• conversation.mode_changed — perbualan bertukar antara ejen dan manusia.
• lead.updated — kualiti lead, status pipeline, kategori atau tahap kecemasan berubah.
• contact.created — kenalan baharu muncul.
• contact.updated — profil kenalan berubah. Event ini menamakan medan yang berubah, tidak sekali-kali nilainya.
• booking.created, booking.cancelled, booking.rescheduled — tempahan dibuat, dibatalkan atau dipindahkan.

Penghantaran

POST <your url>
Content-Type: application/json
User-Agent: aiBalas-Webhooks/1
X-aiBalas-Event: lead.updated
X-aiBalas-Delivery: <delivery id>
X-aiBalas-Signature: t=1758600000,v1=<hex>

{ "id": "1042", "type": "lead.updated", "at": "2026-09-23T04:00:00.000Z",
  "account": { "id": "...", "slug": "acme" }, "agent": { "id": "...", "slug": "sales" },
  "data": { "agentId": "...", "contactId": "60123456789", "changes": { "leadQuality": "hot" }, "source": "agent" } }

Id event ialah rentetan digit yang sentiasa meningkat: bandingkan id sebagai nombor (atau sebagai rentetan yang sama panjang), bukan sebagai teks pendek. Event mesej membawa teks mesej; event handoff tidak membawa ringkasan handoff, dan tiada event yang membawa nota peribadi kenalan anda.

Mengesahkan tandatangan

Setiap penghantaran ditandatangani dengan rahsia webhook anda. Pengepala X-aiBalas-Signature memegang t, masa penghantaran dalam saat Unix, dan v1, HMAC-SHA256 dalam hex bagi t, noktah, dan badan permintaan mentah, dengan rahsia anda sebagai kunci. Kira sendiri atas badan tepat seperti yang tiba (sebelum JSON dihuraikan), bandingkan dalam masa tetap, dan tolak t yang lebih lama daripada 5 minit supaya penghantaran lama tidak boleh diulang main.

import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
  const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
// Answer 2xx quickly; do the work after. Anything else is retried.

Cubaan semula dan susunan

Penghantaran sekurang-kurangnya sekali. Apa-apa selain jawapan 2xx dalam 10 saat akan dicuba semula, termasuk 3xx (redirect tidak pernah diikut): cubaan semula pertama selepas 60 saat dan tempoh menunggu berganda setiap kali, sehingga 10 cubaan dalam kira-kira 8.5 jam, selepas itu penghantaran itu ditanda gagal. Cubaan pertama tiba mengikut susunan id event bagi setiap webhook, tetapi cubaan semula boleh tiba selepas event yang lebih baharu, jadi proses berdasarkan id event dan anggap ulangan sebagai ulangan. Event dihantar beberapa saat selepas ia berlaku, bukan serta-merta. Webhook yang tidak menerima apa-apa selama 3 hari akan dimatikan dan pemilik ruang kerja dihantar e-mel; hidupkan semula dari halaman Developers dan penghantaran bersambung dari tempat ia berhenti.

Butang Test di halaman Developers (atau POST /v1/webhooks/{id}/test) menghantar event ping untuk menyemak penerima anda, sehingga 10 seminit. Menukar rahsia (rotate) membatalkan yang lama serta-merta, dan yang baharu ditunjukkan sekali sahaja: kemas kini penerima anda dahulu.

Tinjau (polling) sebagai ganti

Jika anda tidak mahu menjalankan penerima, GET /v1/events memulangkan event yang sama, yang paling lama dahulu, kepada mana-mana API key yang ada skop baca: hantar since=<id event terakhir yang anda lihat> dan, jika mahu, types= dan agentId=. Event disimpan selama 30 hari; tanpa since, anda dapat 24 jam terakhir. Gunakan next_cursor seperti biasa.

curl "https://aibalas.com/api/v1/events?since=1042&types=message.received,lead.updated" \
  -H "Authorization: Bearer aib_..."