Akses API #

API (Application Programming Interface) adalah cara bagi sistem perangkat lunak yang berbeda untuk saling berkomunikasi. API Your AI Connector memungkinkan Anda (atau pengembang Anda) untuk membuat kontak, mengirim pesan, mengelola daftar, dan menerima pesan masuk dari saluran kustom secara otomatis — semuanya tanpa menggunakan dasbor.

Mengapa menggunakan API? Jika Anda ingin menghubungkan aplikasi ke alat yang tidak memiliki integrasi bawaan, atau Anda perlu mengotomatiskan tugas berulang dalam skala besar, API adalah cara untuk melakukannya.

Membuat Kunci API Anda #

1. Di bilah sisi kiri, klik Settings (ikon roda gigi).
2. Di bilah sisi Settings, di bawah grup Integrations, klik API Key.

3. Jika Anda belum memiliki kunci, klik Generate API key.
4. Jika Anda sudah memilikinya, kunci tersebut akan ditampilkan dalam bentuk tersamar di bawah Your key. Jika kunci Anda mendukungnya, klik Show untuk melihatnya, lalu Copy untuk menyalinnya — Anda akan melihat notifikasi konfirmasi.
5. Simpan kunci tersebut di tempat yang aman — Anda akan memerlukannya untuk setiap permintaan API.

Anggota tim: kunci API adalah milik pemilik akun, jadi jika Anda masuk sebagai anggota tim yang diundang (termasuk Admin), bagian ini akan menampilkan catatan alih-alih kuncinya. Masuklah sebagai pemilik akun untuk melihat, menyalin, atau membuat ulang kunci tersebut — ini juga berlaku untuk kunci dengan cakupan (scoped keys).

Di mana menemukannya: API Key adalah bagian tersendiri di bawah Settings → Integrations, terpisah dari Webhooks. Jika panduan atau rekan kerja memberi tahu Anda untuk mencari kunci di bawah “Webhooks”, carilah di bagian sebelahnya.

Kunci cakupan: kunci tambahan untuk satu tugas #

Kunci utama Anda dapat melakukan segalanya, jadi kunci tersebut bukanlah kunci yang tepat untuk diberikan kepada laporan, dasbor klien, atau pengaturan sandbox dan pengembangan terpisah. Untuk itu, buat kunci cakupan di kartu Kunci cakupan, di bagian API Key yang sama di bawah Kunci Anda:

1. Klik Kunci baru.
2. Berikan Nama yang akan Anda kenali nanti, misalnya “Sandbox” atau “Dasbor klien Acme”.
3. Di bawah Apa yang dapat dilihat, centang hanya area yang diperlukan.
4. Di bawah Apa yang dapat dilakukan, biarkan Hanya baca kecuali jika alat tersebut harus melakukan perubahan. Kunci yang dapat melakukan perubahan dapat mengirim pesan dan mengedit pengaturan Anda.
5. Secara opsional, atur Permintaan per menit (batasnya sendiri, sehingga tidak akan pernah memperlambat integrasi Anda yang lain) dan tanggal Kedaluwarsa pada.
6. Klik Buat kunci dan segera salin. Kunci cakupan hanya ditampilkan sekali; jika Anda kehilangan satu, cabut aksesnya dan buat yang baru.

Anda dapat membuat sebanyak yang Anda butuhkan. Setiap kunci dalam daftar menunjukkan kapan terakhir kali digunakan, dan Cabut kunci akan segera menghentikan fungsinya. Membuat atau mencabut kunci cakupan tidak akan pernah memengaruhi kunci utama Anda. Opsi lengkap, termasuk kunci yang dibatasi pada sub-akun tertentu, ada di halaman kunci API pada referensi API.

URL Dasar #

Semua permintaan API menggunakan alamat web dasar berikut:

https://api.youraiconnector.com/v1/

Autentikasi #

Setiap permintaan harus menyertakan kunci API Anda agar platform mengetahui bahwa itu adalah Anda. Cara termudah adalah dengan menambahkannya di akhir alamat web:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

Anda juga dapat mengirimkan kunci tersebut sebagai header permintaan alih-alih di dalam URL (disarankan untuk produksi, agar kunci tidak muncul di log server):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

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

Mencari panduan pengembang lengkap? Halaman ini adalah pengantar singkat yang mencakup operasi paling umum. Untuk panduan langkah demi langkah yang lengkap — setiap sumber daya, dengan contoh cURL, JavaScript, dan Python — lihat Memulai dengan API dan Referensi API.

Operasi API Umum #

Membuat Kontak #

Permintaan:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Bidang wajib: phoneNumber (dengan kode negara) selalu diperlukan untuk membuat kontak. Alamat email saja tidak cukup — permintaan tanpa nomor telepon yang valid akan ditolak. Email bersifat opsional.

Respons:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Simpan data.contactId — Anda akan membutuhkannya untuk panggilan “Menambahkan Kontak ke Daftar”.

Menambahkan Kontak ke Daftar #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Temukan ID daftar di aplikasi di bawah Kontak → Daftar, dari menu baris daftar (Salin ID daftar).

Memperbarui Kontak #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Hanya kolom yang Anda sertakan yang akan diubah. Ini juga merupakan cara untuk memuat massal nilai kolom kustom setelah impor — lihat Kolom Kustom, Profil Prospek & Catatan. Detail lengkap ada di API Kontak.

Mengirim Pesan (Saluran Kustom) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Menerima Pesan Masuk (Saluran Kustom) #

Terima pesan dari sistem eksternal sebagai saluran kustom. Beginilah cara integrasi seperti GoHighLevel mengirim pesan ke Your AI Connector. Lihat Saluran Kustom untuk detail lengkapnya.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Ikhtisar Operasi yang Tersedia #

Pembatasan Laju (Rate Limiting) #

API menerapkan batas kecepatan untuk memastikan stabilitas platform. Melebihi batas Anda akan mengembalikan 429 Too Many Requests — hentikan permintaan dan coba lagi setelah waktu yang ditunjukkan dalam header respons. Untuk kasus penggunaan volume tinggi (impor massal), gunakan fitur impor bawaan atau kirim email ke hi@youraiconnector.com untuk panduan.

Praktik Terbaik #

• Simpan kunci API Anda dengan aman — gunakan pengelola kata sandi atau konfigurasi sisi server, jangan pernah di kode sisi klien yang dapat dibaca oleh pengunjung peramban.
• Selalu sertakan kode negara pada nomor telepon (+1 untuk AS, +44 untuk Inggris, +31 untuk Belanda).
• Tangani kesalahan dengan baik — periksa kode status dan baca pesan kesalahan apa pun yang dikembalikan.
• Tangani duplikat — nomor telepon duplikat akan mengembalikan { "success": false, "error_code": 409 } alih-alih kontak baru, dengan ID kontak yang sudah ada di contactId.
• Uji dengan kumpulan data kecil sebelum menjalankan operasi massal.

Respons Kesalahan #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Langkah Selanjutnya #

• Webhook — menerima notifikasi real-time dari aplikasi (bagian terpisah dari kunci API Anda).
• Hubungkan Asisten AI (MCP) — gunakan kunci API yang sama untuk membiarkan Claude mengelola akun Anda.
• Formulir Prospek Facebook — gunakan API dengan platform otomatisasi untuk menangkap prospek.
• Integrasi GoHighLevel — contoh integrasi API dua arah yang lengkap.