Memulai API #

REST API Your AI Connector memungkinkan Anda membangun integrasi sendiri di atas akun Anda. Anda dapat membuat dan mencari kontak, mengelola kampanye, FAQ, tugas dan janji temu, mengirim pesan, mendaftarkan webhook, membaca analitik, dan menghubungkan saluran pesan — semua yang dilakukan dasbor, digerakkan oleh kode.

Ini adalah halaman pusat untuk dokumentasi API. Jika Anda menghubungkan Your AI Connector ke alat yang sudah memiliki integrasi bawaan, Anda mungkin tidak memerlukan API sama sekali. API ditujukan untuk integrasi kustom dan otomatisasi dalam skala besar.

URL Dasar #

Setiap permintaan ditujukan ke alamat web dasar yang sama, dan semua jalur dalam dokumen ini bersifat relatif terhadap alamat tersebut:

https://api.youraiconnector.com/v1

Jadi, endpoint kampanye adalah https://api.youraiconnector.com/v1/campaigns, endpoint kontak adalah https://api.youraiconnector.com/v1/contacts, dan seterusnya.

Semua permintaan harus menggunakan koneksi aman (HTTPS). Permintaan HTTP biasa akan ditolak.

Mendapatkan kunci API #

Akses API adalah fitur berbayar. Jika paket Anda tidak menyertakannya, setiap permintaan akan mengembalikan 403 dengan isi berikut:

{
  "success": false,
  "error_code": 403,
  "error": "This action requires the \"api_access\" feature, which is not enabled for this account."
}

Setelah akses API diaktifkan pada paket Anda, buat kunci dari dasbor. Langkah-langkah lengkapnya ada di Akses API — singkatnya: buka Pengaturan → Integrasi → Kunci API untuk membuat atau membuat ulang kunci Anda. Kunci API adalah bagian tersendiri di bawah Integrasi, terpisah dari Webhook, dan hanya muncul setelah akses API diaktifkan pada paket Anda. Perlakukan kunci tersebut seperti kata sandi: kunci ini memberikan akses penuh ke akun Anda.

Autentikasi #

Anda dapat mengirim kunci API Anda dengan empat cara. Semuanya berfungsi pada setiap endpoint yang menerima autentikasi kunci API.

Untuk produksi, gunakan salah satu bentuk header agar kunci Anda tidak pernah tersimpan dalam log server atau riwayat peramban. Bentuk parameter kueri selalu berfungsi dan merupakan yang paling sederhana untuk pengujian sekali pakai.

Lihat Autentikasi untuk rincian lengkap setiap metode, beserta contoh dan panduan tentang kapan harus menggunakan metode yang mana.

Permintaan pertama Anda #

Berikut adalah panggilan lengkap yang berfungsi untuk mencantumkan kampanye di akun Anda. Panggilan ini menggunakan kunci API Anda dan menampilkan kampanye terbaru terlebih dahulu.

cURL

curl "https://api.youraiconnector.com/v1/campaigns?apiKey=YOUR_API_KEY&limit=10"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/campaigns?limit=10", {
  headers: {
    "X-API-Key": "YOUR_API_KEY",
  },
});

const data = await res.json();
console.log(data.campaigns);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/campaigns",
    params={"limit": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

data = res.json()
print(data["campaigns"])

Respons yang berhasil akan terlihat seperti ini:

{
  "success": true,
  "campaigns": [
    {
      "id": "NBCXrhqGPSFsd6MV7pRo",
      "name": "Inbound WhatsApp Leads",
      "type": "Incoming from Unknown Contacts",
      "status": "Live",
      "enabled": true,
      "archived": false,
      "created_at": 1700000000000,
      "ai_mode": true,
      "language": "en",
      "enabled_channels": ["whatsapp", "instagram"]
    }
  ],
  "next_cursor": null
}

Respons sukses dan error #

Setiap respons JSON membawa flag success sehingga Anda dapat melakukan percabangan tanpa harus mengurai kode status.

Respons yang berhasil adalah success: true ditambah data untuk endpoint tersebut (nama kolom bervariasi — campaigns, contacts, data, dan seterusnya):

{
  "success": true,
  "campaigns": []
}

Respons yang gagal adalah success: false dengan pesan error yang dapat dibaca manusia dan error_code numerik yang sesuai dengan status HTTP:

{
  "success": false,
  "error": "Invalid cursor",
  "error_code": 400
}

Selalu periksa success (atau status HTTP) sebelum membaca data. Lihat Errors & Pagination untuk tabel kode status lengkap dan cara melakukan penomoran halaman melalui kumpulan hasil yang besar.

Batas kecepatan #

Permintaan terautentikasi dibatasi hingga 300 permintaan per menit per kunci API. Terdapat juga batas yang lebih luas yaitu 1.200 permintaan per menit per akun, yang menghitung setiap permintaan terautentikasi yang dibuat untuk akun tersebut.

Jika Anda melebihi salah satu batas tersebut, Anda akan mendapatkan respons 429:

{
  "success": false,
  "error_code": 429,
  "error": "Rate limit exceeded. Please try again later."
}

Berhentilah sejenak dan coba lagi setelah menunggu beberapa saat. Anda juga dapat memeriksa penggunaan Anda saat ini kapan saja dengan GET https://api.youraiconnector.com/v1/api-keys/usage, yang mengembalikan berapa banyak permintaan yang telah Anda gunakan dalam jendela saat ini dan kapan waktu resetnya — berguna untuk membangun pembatasan (throttling) di sisi klien. Lihat API Keys.

Panduan sumber daya #

Grup sumber daya di bawah ini masing-masing memiliki panduan sendiri dengan jalur, kolom permintaan, dan bentuk respons yang tepat.

Agen, Titik Masuk, dan Siaran #

AI Agents, Entry Points, dan Broadcasts semuanya ada dalam spesifikasi OpenAPI yang dipublikasikan, sehingga Anda dapat menelusuri kolom persisnya dan menjalankan permintaan langsung terhadapnya di API explorer. Masing-masing memiliki panduannya sendiri: AI Agents, Entry Points, dan Broadcasts.

Membaca dokumentasi ini sebagai Markdown #

Setiap halaman dalam dokumentasi ini memiliki kembaran dalam format Markdown biasa: ambil alamat halaman tersebut dan tambahkan /index.md di akhirnya. Jadi, halaman ini juga tersedia di https://docs.youraiconnector.com/api/getting-started/index.md, dan akan muncul sebagai teks biasa, bukan halaman web — berguna saat Anda ingin menempelkan halaman ke asisten AI atau menariknya ke dalam skrip.

Untuk menelusuri seluruh set, mulailah dari https://docs.youraiconnector.com/sitemap.xml, yang mencantumkan setiap halaman yang kami terbitkan. Perlu diketahui bahwa dokumentasi ini sengaja dijauhkan dari mesin pencari, jadi mengambil alamat-alamat ini secara langsung adalah cara untuk mengaksesnya dari kode.

Belum ada titik akhir dokumentasi yang dilindungi kunci dan belum ada unduhan massal — kembaran Markdown dan peta situs adalah keseluruhan antarmukanya, dan keduanya tidak memerlukan kunci API.

Langkah berikutnya #

• Autentikasi — pilih metode autentikasi yang tepat untuk integrasi Anda.
• Kesalahan & Penomoran Halaman — menangani kegagalan dan melakukan penomoran halaman melalui hasil.
• Akses API — buat kunci Anda dan lihat contoh yang telah dikerjakan.