Integrasi API AgentKit

Pengenalan

AgentKit menyediakan REST API untuk membaca dan menulis data CRM, menghantar mesej WhatsApp, dan menerima webhook untuk peristiwa lead. Semua endpoint adalah scope organisasi — token awak hanya boleh akses data tenant awak sendiri.

Base URL

https://api.agentkit.my/v1

Semua respons dalam format JSON. Tarikh dalam ISO 8601 (UTC). Setiap respons mengandungi key `success` (boolean), `data` (payload), dan `message` (teks pengguna).

Pengesahan dengan Sanctum

AgentKit menggunakan Laravel Sanctum untuk pengesahan token. Setiap token diikat kepada pengguna dan organisasi tertentu. Token boleh dijana dari Settings → API selepas log masuk ke workspace.

# Contoh: hantar Bearer token dalam header Authorization
curl "https://api.agentkit.my/v1/auth/me" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Aliran lead ingestion

Lead boleh masuk ke AgentKit melalui tiga laluan: (1) Meta Lead Ads webhook automatik, (2) klik wa.me dengan tag SRC dari iklan, (3) POST manual ke endpoint /v1/leads dari sistem awak.

1. 1

   Meta Lead Ads webhook

   Setelah Meta Lead Ads dikonfigurasi dalam workspace, lead masuk secara automatik dengan attribution tag dari iklan.

2. 2

   Klik wa.me dengan tag SRC

   URL wa.me/<nombor>?text=...%5BSRC%3ARAYA2026%5D diparsing oleh Baileys gateway dan lead dicipta dengan attribution_tag = RAYA2026.

3. 3

   POST manual dari sistem awak

   Hantar lead dari CRM lain atau borang custom melalui POST /v1/leads. Bidang minimum: name, phone.

# Contoh: cipta lead dari sistem awak
# Bidang minimum: name. source dan assigned_user_id ialah opsyen.
curl -X POST "https://api.agentkit.my/v1/leads" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ahmad Hafiz",
    "phone": "+60123456789",
    "source": "manual"
  }'

Webhook outbound (event-driven)

Daftar URL endpoint dari sistem awak untuk menerima event seperti lead.created, lead.status_changed, appointment.approved, message.received, dan banyak lagi. Setiap payload ditandatangani dengan HMAC SHA-256 supaya awak boleh sahkan ia datang dari AgentKit.

Event yang tersedia (contoh)

• lead.created — lead baru masuk ke pipeline
• lead.status_changed — status lead berubah (new → contacted → won, dsb.)
• appointment.approved — temujanji disahkan
• message.received — mesej WhatsApp masuk dari pelanggan

Senarai penuh event (Campaign, Message, Lead, Follow-up, Template, Contact, Appointment — ~30 event) tersedia di rujukan Swagger.

Sahkan signature HMAC

Setiap payload dihantar dengan header X-Webhook-Signature = sha256=<hmac>. Sahkan signature ini di hujung penerima sebelum memproses payload.

# Contoh verifikasi (Node.js)
const crypto = require('crypto');

function verify(req, secret) {
  const sig = req.headers['x-webhook-signature'];
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret)
          .update(JSON.stringify(req.body))
          .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(sig), Buffer.from(expected)
  );
}

Aliran event WhatsApp

Mesej WhatsApp inbound masuk melalui Baileys gateway, dianalisis oleh AI Copilot (mode autopilot atau cadangan), dan boleh trigger webhook outbound. Mesej outbound dihantar melalui POST /v1/whatsapp/messages dengan body dan lead_id wajib.

Hantar mesej outbound

curl -X POST "https://api.agentkit.my/v1/whatsapp/messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "550e8400-e29b-41d4-a716-446655440000",
    "body": "Salam Encik Ahmad, ini follow-up dari Zaini..."
  }'