# Membangun Integrasi dari Awal hingga Akhir

Panduan ini membahas semua yang Anda perlukan untuk menjalankan <span data-t="appName">Your AI Connector</span> dari kode Anda sendiri, tanpa perlu membuka dasbor. Di akhir panduan ini, Anda akan membangun integrasi minimal yang:

1. Melakukan autentikasi dengan kunci API
2. Membuat Agen AI dan mengonfigurasi perilaku asistennya
3. Menghubungkan saluran pesan (kami menggunakan WhatsApp Web sebagai contoh yang dikerjakan) dan mengarahkannya ke Agen
4. Mengimpor kontak
5. Mengirim dan membaca pesan
6. Membaca analitik
7. 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](../integrations/api-access.md) untuk memastikan fitur tersebut diaktifkan, dan [Autentikasi](authentication.md) 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](../integrations/api-access.md).

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**

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

**JavaScript**

```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**

```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](errors-and-pagination.md) 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**

```bash
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**

```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**

```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:

```json
{
  "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:

```bash
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](faqs.md).

> **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](campaigns.md). 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:

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

Rangkaian lengkap alur hubungkan/putuskan untuk setiap saluran didokumentasikan dalam [Panduan Saluran](channels.md). 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.

```bash
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" }'
```

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

```python
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.

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

```json
{
  "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.

```python
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)
```

```javascript
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:

```bash
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](channels.md) 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**

```bash
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**

```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**

```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:

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

Untuk pembuatan satu per satu, daftar/pencarian, daftar, tag, dan bidang kustom, lihat [Panduan kontak](contacts.md).

---

## 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**

```bash
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**

```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**

```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`.)

```json
{
  "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.

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

```python
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](messages.md) 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.

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

```javascript
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();
```

```python
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](analytics.md).

---

## 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:

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

```json
{
  "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**

```bash
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**

```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**

```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"]
```

```json
{
  "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](webhooks.md) dan halaman [Webhook](../integrations/webhooks.md) 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](campaigns.md) · [Kontak](contacts.md) · [FAQ](faqs.md) · [Pesan](messages.md) · [Janji Temu](appointments.md)
- [Saluran](channels.md) · [Templat](templates.md) · [Analitik](analytics.md) · [Webhook](webhooks.md) · [Kunci API](api-keys.md)
- Baru di sini? [Memulai](getting-started.md) · [Autentikasi](authentication.md) · [Kesalahan & Penomoran Halaman](errors-and-pagination.md)

Stuck on something this guide does not cover? Email [<span data-t="supportEmail">hi@youraiconnector.com</span>](mailto:hi@youraiconnector.com).