Membangun Integrasi dari Awal hingga Akhir

Panduan ini membahas semua yang Anda perlukan untuk menjalankan Your AI Connector dari kode Anda sendiri, tanpa perlu membuka dasbor. Di akhir panduan ini, Anda akan membangun integrasi minimal yang:

Melakukan autentikasi dengan kunci API
Membuat Agen AI dan mengonfigurasi perilaku asistennya
Menghubungkan saluran pesan (kami menggunakan WhatsApp Web sebagai contoh yang dikerjakan) dan mengarahkannya ke Agen
Mengimpor kontak
Mengirim dan membaca pesan
Membaca analitik
Berlangganan webhook untuk peristiwa waktu nyata

Setiap langkah menautkan ke panduan sumber daya lengkap agar Anda dapat mendalami detailnya saat dibutuhkan. Halaman ini adalah petanya; panduan sumber daya adalah wilayahnya.

Sebelum Anda memulai. Akses API adalah fitur berbayar. Jika paket Anda tidak menyertakannya, setiap permintaan akan mengembalikan 403. Lihat Akses API untuk memastikan fitur tersebut diaktifkan, dan Autentikasi untuk semua cara mengirimkan kunci Anda.

Semua jalur di bawah ini bersifat relatif terhadap URL dasar:

https://api.youraiconnector.com/v1

Langkah 1 — Dapatkan kunci API dan buat permintaan pertama Anda

Kunci API Anda berada di aplikasi di bawah Pengaturan → Integrasi → Kunci API — bagian tersendiri di bawah Integrasi, terpisah dari Webhook, yang hanya muncul setelah akses API diaktifkan pada paket Anda. Buat satu, salin, dan simpan di tempat yang aman (penyimpanan rahasia sisi server atau variabel lingkungan — jangan pernah di kode peramban). Petunjuk lengkap ada di Akses API.

Setelah Anda memiliki kunci, konfirmasikan bahwa kunci tersebut berfungsi dengan memanggil titik akhir kesehatan. Ada beberapa cara untuk mengirim kunci; yang paling sederhana adalah parameter kueri ?apiKey=, tetapi untuk kode nyata, gunakan header X-API-Key agar kunci tidak pernah berakhir di log server atau riwayat peramban.

cURL

curl "https://api.youraiconnector.com/v1/health?apiKey=YOUR_API_KEY"

JavaScript

const BASE = "https://api.youraiconnector.com/v1";
const headers = { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" };

const res = await fetch(`${BASE}/health`, { headers });
const data = await res.json();
console.log(data); // { "success": true, ... }

Python

import requests

BASE = "https://api.youraiconnector.com/v1"
HEADERS = {"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"}

res = requests.get(f"{BASE}/health", headers=HEADERS)
print(res.json())  # { "success": true, ... }

Setiap respons yang berhasil dibungkus dalam amplop yang sama — bidang success: true ditambah data hasil. Kesalahan mengembalikan success: false dengan pesan error dan error_code. Lihat Kesalahan & Penomoran Halaman untuk daftar lengkap dan cara titik akhir daftar melakukan penomoran halaman dengan ?limit dan ?cursor.

Batas kecepatan. Permintaan terautentikasi dibatasi hingga 300 per menit (dengan batas atas yang lebih luas yaitu 1.200/menit per akun). Melebihi batas tersebut akan mengembalikan 429; hentikan permintaan dan coba lagi.

Langkah 2 — Membuat Agen AI

Sebuah Agen AI adalah unit yang menampung perilaku asisten Anda: instruksinya, tujuannya, jam aktifnya, dan cara ia berbicara dengan kontak. Agen inilah yang menjawab percakapan, jadi ini adalah hal pertama yang wajar untuk dibuat.

Buat satu dengan POST /agents. name adalah satu-satunya kolom yang perlu dikirim di awal; sisanya dapat diatur dengan panggilan bot-config di bawah ini.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inbound WhatsApp Leads",
    "language": "en"
  }'

JavaScript

const res = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    name: "Inbound WhatsApp Leads",
    language: "en",
  }),
});
const { agent_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/agents",
    headers=HEADERS,
    json={"name": "Inbound WhatsApp Leads", "language": "en"},
)
agent_id = res.json()["agent_id"]

Pembuatan yang berhasil akan mengembalikan 201 dengan ID baru:

{
  "success": true,
  "agent_id": "abc123agent"
}

Simpan agent_id — Anda akan merujuknya saat merutekan saluran.

Mengonfigurasi asisten

PUT /agents/{agentId}/bot-config mengatur perilaku asisten. Panggilan ini menggabungkan kolom yang Anda kirim ke dalam konfigurasi yang ada, jadi apa pun yang Anda lewatkan akan tetap dipertahankan:

curl -X PUT "https://api.youraiconnector.com/v1/agents/abc123agent/bot-config" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Greet warmly, answer questions about our services, and offer to book a call.",
    "goal": "Book a discovery call.",
    "ai_speed": "balanced"
  }'

Atur jam aktif dengan PUT /agents/{agentId}/active-hours agar asisten hanya membalas selama jam kerja; di luar waktu tersebut, asisten tidak akan membalas secara otomatis.

Basis pengetahuan. Agar asisten menjawab dari konten Anda sendiri, lampirkan FAQ. Lihat panduan FAQ.

Warisan: kampanye klasik. Akun yang masih memiliki halaman Kampanye membuat perilaku asisten yang sama pada kampanye sebagai gantinya (POST /campaigns dengan objek type dan bot, lalu PUT /campaigns/{campaignId}/bot-config). Daftar lengkap kolom kampanye dan kontrol siklus hidup ada di panduan Kampanye. Jika Anda membangun sesuatu yang baru, buatlah Agen.

Langkah 3 — Menghubungkan saluran

Agen memerlukan cara untuk mengirim dan menerima pesan. Tujuh alur koneksi dapat dijalankan dari API: WhatsApp Business, WhatsApp Web, Instagram dan Messenger secara bersamaan (satu alur Meta bersama), akun pribadi Instagram, Telegram, LINE, dan Viber. Saluran lainnya — SMS, email, widget obrolan, dan saluran kustom di antaranya — disiapkan di dasbor, bukan melalui REST, dan setelah terhubung, titik akhir pesan, kontak, dan perutean akan berfungsi dengan cara yang sama persis. GET /channels adalah sumber kebenaran langsung untuk apa yang sebenarnya telah terhubung pada akun tertentu:

curl "https://api.youraiconnector.com/v1/channels?apiKey=YOUR_API_KEY"

Rangkaian lengkap alur hubungkan/putuskan untuk setiap saluran didokumentasikan dalam Panduan Saluran. Di bawah ini kami akan membahas WhatsApp Web dari awal hingga akhir, karena ini menunjukkan pola yang paling menarik: alur pemasangan kode QR yang harus dirender dan dipol oleh wrapper Anda.

Contoh pengerjaan: memasangkan WhatsApp Web dengan kode QR

Pemasangan WhatsApp Web adalah proses tiga panggilan — mulai, ambil QR, pol hingga terhubung.

1. Mulai sesi pemasangan. Masukkan nomor yang ingin Anda hubungkan dalam format E.164.

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+15551230000" }'

await fetch(`${BASE}/channels/whatsapp-web/connections`, {
  method: "POST",
  headers,
  body: JSON.stringify({ phone_number: "+15551230000" }),
});

requests.post(
    f"{BASE}/channels/whatsapp-web/connections",
    headers=HEADERS,
    json={"phone_number": "+15551230000"},
)

2. Ambil kode QR dan tunjukkan kepada pengguna. Pol ini setiap 10–15 detik. Responsnya mencakup payload qr_code mentah (render sendiri sebagai gambar QR) dan qr_data_url yang siap ditampilkan.

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr?apiKey=YOUR_API_KEY"

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@abc...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo..."
}

Di UI wrapper Anda, masukkan qr_data_url langsung ke dalam <img src="..."> dan minta pengguna untuk memindainya dari WhatsApp → Perangkat Tertaut di ponsel mereka. Jika QR kedaluwarsa (respons 410), mulai ulang dari langkah 1 untuk mendapatkan yang baru.

3. Pol status hingga terhubung. Setelah pengguna memindai, terus pol endpoint status hingga melaporkan connected (layanan mungkin juga melaporkan open). Anggap disconnected dan not_initialized sebagai kegagalan terminal.

import time

PHONE = "+15551230000"
while True:
    res = requests.get(
        f"{BASE}/channels/whatsapp-web/connections/{PHONE}/status",
        headers=HEADERS,
    )
    status = res.json()["status"]
    if status in ("connected", "open"):
        print("Connected!")
        break
    if status in ("disconnected", "not_initialized"):
        raise RuntimeError(f"Pairing failed: {status}")
    time.sleep(5)

async function waitForConnection(phone) {
  while (true) {
    const res = await fetch(
      `${BASE}/channels/whatsapp-web/connections/${encodeURIComponent(phone)}/status`,
      { headers }
    );
    const { status } = await res.json();
    if (status === "connected" || status === "open") return;
    if (status === "disconnected" || status === "not_initialized") {
      throw new Error(`Pairing failed: ${status}`);
    }
    await new Promise((r) => setTimeout(r, 5000));
  }
}

Perhatian. Setiap nomor WhatsApp Web yang terhubung dikenakan biaya pemeliharaan bulanan berulang hingga Anda memutuskannya (DELETE /channels/whatsapp-web/connections/{phoneNumber}).

Merutekan saluran ke Agen Anda

Menghubungkan saluran membuatnya berfungsi; merutekannya memberi tahu platform Agen AI mana yang harus menjawab percakapan masuk yang benar-benar baru di saluran tersebut. Atur Titik Masuk default saluran untuk saluran tersebut, dengan menyebutkan nama Agen yang Anda buat di Langkah 2:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp_web", "agent_id": "abc123agent" }'

Ulangi panggilan tersebut satu kali per saluran — satu default saluran per saluran. Untuk membiarkan saluran tanpa Agen yang menjawabnya, panggil DELETE /entry-points/channel-defaults?channel=whatsapp_web; untuk memeriksa apakah tangga Titik Masuk aktif untuk akun tersebut, panggil GET /entry-points/routing-status. Peta POST /channels/campaign yang lebih lama dipertahankan hanya untuk pemulihan (rollback) dan tidak lagi digunakan untuk perutean masuk. Lihat panduan Saluran untuk jenis saluran lainnya dan untuk alur OAuth WhatsApp Business.

Langkah 4 — Impor kontak Anda

Setelah saluran aktif, muat orang-orang yang ingin Anda hubungi. Titik akhir impor menerima hingga 500 data per panggilan. Setiap data memerlukan phone_number dalam format internasional; sisanya bersifat opsional. Data dengan nomor yang salah, saluran yang tidak didukung, atau nomor yang sudah ada akan dilewati — dan setiap data yang dilewati akan dilaporkan beserta indeks dan alasannya, sehingga Anda dapat mencoba ulang hanya untuk data yang gagal.

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/import" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee" },
      { "phone_number": "+12025551235", "first_name": "Bob" }
    ],
    "defaultChannel": "whatsapp_web"
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/import`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    contacts: [
      { phone_number: "+12025551234", first_name: "Ann", last_name: "Lee" },
      { phone_number: "+12025551235", first_name: "Bob" },
    ],
    defaultChannel: "whatsapp_web",
  }),
});
const result = await res.json();
console.log(`${result.imported} imported, ${result.skipped.length} skipped`);

Python

res = requests.post(
    f"{BASE}/contacts/import",
    headers=HEADERS,
    json={
        "contacts": [
            {"phone_number": "+12025551234", "first_name": "Ann", "last_name": "Lee"},
            {"phone_number": "+12025551235", "first_name": "Bob"},
        ],
        "defaultChannel": "whatsapp_web",
    },
)
result = res.json()
print(f"{result['imported']} imported, {len(result['skipped'])} skipped")

Respons tersebut memberi tahu Anda apa yang sebenarnya terjadi:

{
  "success": true,
  "imported": 2,
  "contact_ids": ["contactId1", "contactId2"],
  "skipped": []
}

Untuk pembuatan satu per satu, daftar/pencarian, daftar, tag, dan bidang kustom, lihat Panduan kontak.

Langkah 5 — Mengirim dan membaca pesan

Mengirim pesan

Pengiriman paling sederhana bersifat agnostik terhadap saluran: berikan identitas kontak dan isi pesan, lalu platform akan mengirimkannya melalui saluran apa pun yang digunakan kontak tersebut. Anda dapat menargetkan berdasarkan contact_id, atau berdasarkan channel ditambah bidang identitas yang cocok (phone_number untuk WhatsApp/WhatsApp Web/SMS, instagram_id untuk Instagram, dan seterusnya).

cURL

curl -X POST "https://api.youraiconnector.com/v1/contacts/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "phone_number": "+12025551234",
    "body": "Hi Ann! Thanks for reaching out."
  }'

JavaScript

const res = await fetch(`${BASE}/contacts/send`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    channel: "whatsapp_web",
    phone_number: "+12025551234",
    body: "Hi Ann! Thanks for reaching out.",
  }),
});
const { message_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/contacts/send",
    headers=HEADERS,
    json={
        "channel": "whatsapp_web",
        "phone_number": "+12025551234",
        "body": "Hi Ann! Thanks for reaching out.",
    },
)
message_id = res.json()["message_id"]

Pengiriman bersifat asinkron — 201 berarti pesan telah diterima dan dimasukkan ke antrean, belum terkirim. (Kontak dengan mode jangan ganggu atau mode pribadi aktif akan ditolak dengan 422.)

{
  "success": true,
  "message_id": "aB3dE5fG7hI9jK1lM2nO",
  "contact_id": "contact123",
  "channel": "whatsapp_web"
}

Membaca percakapan

Untuk membaca pesan kembali, buat daftar berdasarkan kontak, yang terbaru terlebih dahulu, dengan penomoran halaman kursor. Teruskan next_cursor dari satu respons sebagai cursor dari respons berikutnya untuk menelusuri riwayat.

curl "https://api.youraiconnector.com/v1/contacts/contact123/messages?limit=50&apiKey=YOUR_API_KEY"

res = requests.get(
    f"{BASE}/contacts/contact123/messages",
    headers=HEADERS,
    params={"limit": 50},
)
page = res.json()
for msg in page["messages"]:
    print(msg)
next_cursor = page["next_cursor"]  # pass back as ?cursor= for the next page

Anda juga dapat memfilter berdasarkan tipe konten (?filter=text|media|tool_use) atau arah (?direction=inbound|outbound). Panduan pesan mencakup lampiran media, menandai pesan sebagai telah dibaca, dan tampilan pesan per sesi.

Jangan melakukan polling untuk balasan. Membuat daftar pesan dengan pengatur waktu memang berfungsi, tetapi membuang-buang permintaan dan menambah jeda. Untuk pesan masuk, gunakan webhook sebagai gantinya — itu adalah Langkah 7.

Langkah 6 — Membaca analitik

Setelah pesan mengalir, ringkasan analitik memberikan Anda jumlah agregat selama rentang tanggal: terkirim, tersampaikan, dibaca, dibalas, dipesan, kontak dibuat, dan kredit yang digunakan/diisi ulang. Anda mendapatkan total rentang dan deret per hari yang diisi nol — sempurna untuk bagan dasbor. Secara opsional, batasi ke satu kampanye dengan campaign_id (contoh di bawah menggunakan ID kampanye placeholder, abc123campaign); biarkan parameter tersebut kosong untuk total seluruh akun.

curl "https://api.youraiconnector.com/v1/analytics/summary?from=2026-05-01&to=2026-05-31&campaign_id=abc123campaign&apiKey=YOUR_API_KEY"

const params = new URLSearchParams({
  from: "2026-05-01",
  to: "2026-05-31",
  campaign_id: "abc123campaign",
});
const res = await fetch(`${BASE}/analytics/summary?${params}`, { headers });
const { totals, by_date } = await res.json();

res = requests.get(
    f"{BASE}/analytics/summary",
    headers=HEADERS,
    params={"from": "2026-05-01", "to": "2026-05-31", "campaign_id": "abc123campaign"},
)
data = res.json()
totals = data["totals"]
by_date = data["by_date"]

Rentang default adalah 30 hari terakhir dan dibatasi hingga 366 hari. Untuk catatan penggunaan kredit demi kredit dan perincian biaya AI, lihat Panduan analitik.

Langkah 7 — Berlangganan webhook untuk peristiwa waktu nyata

Polling memang baik untuk skrip cepat, tetapi integrasi yang nyata haruslah berbasis push. Webhook memungkinkan platform untuk memanggil server Anda saat sesuatu terjadi — kontak baru, balasan, janji temu yang dipesan, atau obrolan yang selesai.

Pertama, temukan nama peristiwa yang tepat yang dapat Anda langgani:

curl "https://api.youraiconnector.com/v1/webhooks/events?apiKey=YOUR_API_KEY"

{
  "success": true,
  "events": [
    "Contact Created",
    "Human Alerted",
    "Appointment Booked",
    "Replies",
    "New Message",
    "Chat Concluded",
    "Task Created",
    "Daily Summary Created"
  ]
}

Kemudian buat langganan yang mengarah ke URL HTTPS di server Anda. Gunakan string peristiwa yang tepat dari panggilan di atas.

cURL

curl -X POST "https://api.youraiconnector.com/v1/webhooks" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "name": "Lead updates hook"
  }'

JavaScript

const res = await fetch(`${BASE}/webhooks`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    url: "https://hooks.example.com/incoming",
    subscribed_to: ["Contact Created", "Replies"],
    name: "Lead updates hook",
  }),
});
const { webhook_id } = await res.json();

Python

res = requests.post(
    f"{BASE}/webhooks",
    headers=HEADERS,
    json={
        "url": "https://hooks.example.com/incoming",
        "subscribed_to": ["Contact Created", "Replies"],
        "name": "Lead updates hook",
    },
)
webhook_id = res.json()["webhook_id"]

{
  "success": true,
  "webhook_id": "1",
  "webhook": {
    "id": "1",
    "name": "Lead updates hook",
    "url": "https://hooks.example.com/incoming",
    "subscribed_to": ["Contact Created", "Replies"],
    "subscribed_to_tags": [],
    "created_at": "2026-06-09T12:00:00.000Z"
  }
}

URL harus menggunakan HTTPS dan dapat diakses secara publik. Mulai saat ini, server Anda akan menerima POST untuk setiap peristiwa yang dilanggani. Anda dapat mengirim pengiriman uji coba, memeriksa kesehatan langganan, dan mengaktifkan kembali langganan yang dinonaktifkan secara otomatis setelah kegagalan berulang — lihat Panduan webhook dan halaman Webhook tingkat integrasi untuk bentuk payload dan verifikasi.

Menyusun semuanya

Berikut adalah ringkasan alur keseluruhannya:

Langkah	Tujuan	Panggilan kunci
1	Autentikasi	`GET /health`
2	Buat + sesuaikan asisten	`POST /agents`, `PUT /agents/{id}/bot-config`, `PUT /agents/{id}/active-hours`
3	Hubungkan saluran dan arahkan	`POST /channels/whatsapp-web/connections` → polling QR + status → `PUT /entry-points/channel-defaults`
4	Muat kontak	`POST /contacts/import`
5	Kirim & baca	`POST /contacts/send`, `GET /contacts/{id}/messages`
6	Ukur	`GET /analytics/summary`
7	Bereaksi secara waktu nyata	`POST /webhooks`

Pembungkus minimal hanyalah tujuh panggilan ini yang dihubungkan ke UI Anda sendiri. Dari sana, tambahkan panduan per sumber daya sesuai kebutuhan Anda:

Kampanye · Kontak · FAQ · Pesan · Janji Temu
Saluran · Templat · Analitik · Webhook · Kunci API
Baru di sini? Memulai · Autentikasi · Kesalahan & Penomoran Halaman

Stuck on something this guide does not cover? Email hi@youraiconnector.com.

Membangun Integrasi dari Awal hingga Akhir #

Langkah 1 — Dapatkan kunci API dan buat permintaan pertama Anda #

Langkah 2 — Membuat Agen AI #

Mengonfigurasi asisten #

Langkah 3 — Menghubungkan saluran #

Contoh pengerjaan: memasangkan WhatsApp Web dengan kode QR #

Merutekan saluran ke Agen Anda #

Langkah 4 — Impor kontak Anda #

Langkah 5 — Mengirim dan membaca pesan #

Mengirim pesan #

Membaca percakapan #

Langkah 6 — Membaca analitik #

Langkah 7 — Berlangganan webhook untuk peristiwa waktu nyata #

Menyusun semuanya #

Membangun Integrasi dari Awal hingga Akhir

Langkah 1 — Dapatkan kunci API dan buat permintaan pertama Anda

Langkah 2 — Membuat Agen AI

Mengonfigurasi asisten

Langkah 3 — Menghubungkan saluran

Contoh pengerjaan: memasangkan WhatsApp Web dengan kode QR

Merutekan saluran ke Agen Anda

Langkah 4 — Impor kontak Anda

Langkah 5 — Mengirim dan membaca pesan

Mengirim pesan

Membaca percakapan

Langkah 6 — Membaca analitik

Langkah 7 — Berlangganan webhook untuk peristiwa waktu nyata

Menyusun semuanya