API Koneksi Saluran #

Panduan ini menunjukkan cara menghubungkan saluran pesan ke akun menggunakan API. Panduan ini ditulis untuk pengembang yang membangun integrasi atau wrapper, sehingga fokus pada permintaan yang tepat, urutan pembuatannya, dan respons yang Anda terima.

Ada satu pola yang perlu Anda pahami sejak awal, karena pola ini berlaku untuk hampir setiap saluran di sini.

Pola hubungkan-lalu-polling #

Sebagian besar saluran tidak dapat dihubungkan dengan satu panggilan API saja. Menghubungkan WhatsApp, Instagram, atau Messenger berarti pemilik akun harus masuk ke akun penyedia mereka sendiri dan menyetujui akses. Tidak ada jalur headless (otomatis sepenuhnya) untuk persetujuan tersebut - orang sungguhan harus membuka URL di browser, atau memindai kode QR dengan ponsel mereka.

Jadi alurnya selalu:

1. Mulai koneksi dengan POST. Respons memberikan Anda URL untuk dibuka, atau kode QR untuk ditampilkan.
2. Serahkan itu kepada pengguna akhir - buka URL di browser mereka, atau tampilkan kode QR di layar untuk mereka pindai.
3. Polling endpoint status dengan GET dalam interval singkat (setiap beberapa detik) hingga status mencapai status terhubung.

Tugas integrasi Anda adalah menjalankan loop tersebut: tampilkan URL atau QR, lalu polling hingga selesai. Rencanakan UI Anda di sekitar polling - spinner dengan pesan “menunggu Anda selesai di browser” berfungsi dengan baik.

Instagram + Messenger (Meta) #

Instagram dan Messenger dihubungkan bersama dalam satu alur, karena keduanya berjalan di Halaman Facebook. Pemilik akun memberikan otorisasi melalui Facebook, Anda mengambil daftar Halaman yang mereka kelola, dan Anda memilih Halaman mana yang akan dihubungkan.

Langkah 1 - Memulai koneksi Instagram + Messenger #

POST /channels/meta/connect

Ini mengembalikan URL persetujuan. Tidak ada kredensial yang dikirim dalam permintaan ini - koneksi diotorisasi sepenuhnya di browser.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/connect?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/connect", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Open data.oauth_url in the end user's browser.

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Open data["oauth_url"] in the end user's browser.

Respons

{
  "success": true,
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "connect_url": "https://api.youraiconnector.com/v1/channels/meta/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Buka oauth_url di browser pengguna akhir agar mereka dapat masuk ke Facebook dan menyetujui akses. Upaya koneksi kedaluwarsa pada expires_at (sekitar 30 menit) - jika sudah lewat, mulai dari awal. Perlakukan state_token sebagai rahasia berumur pendek dan jangan mencatatnya.

Opsi termudah untuk Instagram + Messenger: serahkan connect_url #

Respons tersebut juga menyertakan connect_url siap pakai: halaman yang dihosting yang menjalankan seluruh alur untuk pemegang akun. Mereka membukanya, masuk ke Facebook, dan jika mereka memiliki lebih dari satu Halaman, halaman tersebut akan menampilkan daftar dan membiarkan mereka memilih Halaman mana yang akan dihubungkan - kemudian halaman tersebut melaporkan keberhasilan dengan sendirinya. Berikan tautan ini kepada pemegang akun alih-alih membuka oauth_url sendiri, membuat pemilih Halaman, dan melakukan polling. Tautan ini berfungsi selama sekitar 30 menit (connect_url_expires_at); jika kedaluwarsa, mulai koneksi baru. Langkah-langkah manual di bawah ini ditujukan untuk integrasi yang ingin menjalankan alur dan merender pemilih Halaman sendiri.

Langkah 2 - Lakukan polling status hingga halaman dimuat #

GET /channels/meta/status

Setelah pengguna menyelesaikan login Facebook, lakukan polling pada endpoint ini setiap beberapa detik. Bidang status akan melalui langkah-langkah berikut:

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/status", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
// Poll until data.status === "pages_loaded".

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/channels/meta/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "pages_loaded".

Respons (setelah halaman dimuat)

{
  "success": true,
  "status": "pages_loaded",
  "pages": [
    {
      "id": "1234567890",
      "name": "My Business Page",
      "category": "Local business",
      "instagram_business_account": {
        "id": "17890000000000000",
        "username": "mybusiness"
      }
    }
  ],
  "selected_page": null
}

Langkah 3 - Mencantumkan halaman (opsional) #

Jika Anda lebih suka mengambil daftar Halaman secara terpisah (misalnya, untuk merender pemilih), gunakan:

GET /channels/meta/pages

curl "https://api.youraiconnector.com/v1/channels/meta/pages" \
  -H "X-API-Key: YOUR_API_KEY"

Ini mengembalikan array pages yang sama seperti endpoint status. (Endpoint status sudah menyertakan halaman, jadi panggilan ini hanya untuk kenyamanan.)

Langkah 4 - Pilih halaman untuk dihubungkan #

POST /channels/meta/select-page

Kirim page_id dari Halaman yang dipilih pengguna. Akun Instagram yang ditautkan ke Halaman tersebut akan dihubungkan secara otomatis; Anda hanya memerlukan objek instagram jika ingin mengganti akun Instagram mana yang akan digunakan.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/meta/select-page" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "page_id": "1234567890" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/meta/select-page", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ page_id: "1234567890" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/meta/select-page",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"page_id": "1234567890"},
)
data = res.json()

Respons

{
  "success": true,
  "page_id": "1234567890",
  "instagram_business_account_id": "17890000000000000"
}

Saluran sekarang terhubung. GET /channels/meta/status tindak lanjut akan melaporkan status: "connected".

Mencantumkan kiriman halaman yang terhubung #

GET /channels/meta/posts?platform=instagram

Mengembalikan kiriman terbaru dari halaman yang Anda hubungkan - media Instagram atau kiriman Facebook. Inilah yang Anda gunakan untuk merender pemilih saat Anda menyiapkan Titik Masuk yang bereaksi terhadap komentar pada satu kiriman tertentu.

cURL

curl "https://api.youraiconnector.com/v1/channels/meta/posts?platform=instagram&limit=25" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "connected": true,
  "platform": "instagram",
  "posts": [
    {
      "id": "17900000000000000",
      "caption": "New spring menu is live",
      "thumbnailUrl": "https://scontent.cdninstagram.com/...",
      "permalink": "https://www.instagram.com/p/Cxxxxxxxxxx/",
      "createdAt": "2026-05-02T09:12:00.000Z",
      "mediaType": "REELS"
    }
  ],
  "nextCursor": "QVFIUkxxxxxxxx"
}

mediaType adalah label milik Instagram (REELS, FEED, STORY, atau formatnya - IMAGE, VIDEO, CAROUSEL_ALBUM); untuk Facebook selalu POST. nextCursor adalah null pada halaman terakhir.

Jika tidak ada yang dapat dicantumkan, panggilan tetap mengembalikan 200 dengan connected: false dan array posts kosong, ditambah reason yang memberi tahu Anda alasannya:

Memutuskan koneksi Instagram + Messenger #

DELETE /channels/meta

curl -X DELETE "https://api.youraiconnector.com/v1/channels/meta" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "disconnected": true }

Ini menghentikan perutean masuk untuk Instagram dan Messenger. Ini bersifat idempoten - memanggilnya saat tidak ada yang terhubung akan tetap berhasil.

WhatsApp Business #

Ini menghubungkan nomor WhatsApp Business resmi. Nomor tersebut harus sudah ada di akun sebelum Anda memanggil connect. Seperti Meta, pemegang akun melakukan otorisasi di browser mereka, kemudian Anda melakukan polling hingga nomor tersebut melaporkan ONLINE.

Langkah 1 - Memulai koneksi WhatsApp Business #

POST /channels/whatsapp/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/whatsapp/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155551234" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155551234" }),
});
const data = await res.json();
// Open data.oauth_url in the account holder's browser.

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155551234"},
)
data = res.json()
# Open data["oauth_url"] in the account holder's browser.

Respons

{
  "success": true,
  "status": "pending",
  "oauth_url": "https://www.facebook.com/v21.0/dialog/oauth?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Buka oauth_url di browser pemegang akun untuk melakukan otorisasi. Setelah mereka menyetujui, pendaftaran selesai di latar belakang.

Langkah 2 - Lakukan polling status hingga ONLINE #

GET /channels/whatsapp/connect/{phoneNumber}/status

Lakukan polling ini hingga status bernilai ONLINE.

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp/connect/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp/connect/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp/connect/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Respons

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Bidang status dapat berupa:

live: true berarti status diperiksa terhadap penyedia secara real time; false berarti status berasal dari status cache terakhir.

Memutuskan koneksi nomor WhatsApp Business #

DELETE /channels/whatsapp/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "phone_number": "+14155551234", "disconnected": true }

Nomor itu sendiri tetap ada di akun, sehingga Anda dapat menghubungkannya kembali nanti.

WhatsApp Web #

WhatsApp Web menautkan nomor WhatsApp biasa dengan memindai kode QR, sama seperti menautkan perangkat di aplikasi WhatsApp. Alurnya adalah: mulai sesi, ambil kode QR dan tampilkan, lalu lakukan polling hingga statusnya menjadi connected.

Langkah 1 - Memulai sesi penyandingan WhatsApp Web #

POST /channels/whatsapp-web/connections

cURL

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

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/whatsapp-web/connections", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+15551230000" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+15551230000"},
)
data = res.json()

Respons

{
  "success": true,
  "phone_number": "+15551230000",
  "session_id": "session-id",
  "status": "qr_pending",
  "connect_url": "https://api.youraiconnector.com/v1/channels/whatsapp-web/connect?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000,
  "poll_qr_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/qr",
  "poll_status_path": "/v1/channels/whatsapp-web/connections/%2B15551230000/status"
}

Opsi termudah untuk WhatsApp Web: serahkan connect_url #

Respons tersebut mencakup connect_url siap pakai: halaman yang dihosting yang menampilkan kode QR, menyegarkannya secara otomatis saat berotasi, dan beralih ke pesan sukses saat nomor tersebut ditautkan. Cukup berikan tautan ini kepada pemegang akun (buka di browser, kirimkan kepada mereka, atau tampilkan sebagai QR/tombol) dan minta mereka memindainya dengan WhatsApp - Anda tidak perlu mengambil QR atau melakukan polling apa pun sendiri. Tautan ini berfungsi selama sekitar 30 menit (connect_url_expires_at); jika kedaluwarsa sebelum mereka selesai, mulai koneksi baru untuk mendapatkan yang baru.

Ini adalah jalur yang disarankan jika seseorang dapat membuka tautan. Langkah-langkah manual di bawah ini (mengambil QR sendiri, melakukan polling status) ditujukan untuk integrasi yang ingin merender QR di dalam antarmuka mereka sendiri.

Respons tersebut juga memberikan Anda poll_qr_path dan poll_status_path yang tepat untuk digunakan, sehingga Anda tidak perlu membuatnya sendiri.

Langkah 2 - Mengambil kode QR dan menampilkannya #

GET /channels/whatsapp-web/connections/{phoneNumber}/qr

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/qr" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/qr`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Render data.qr_data_url as an <img src> for the user to scan.

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/qr",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Render data["qr_data_url"] for the user to scan.

Respons

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "qr_pending",
  "qr_code": "2@raw-qr-payload-string...",
  "qr_data_url": "data:image/png;base64,iVBORw0KGgo...",
  "expires_at": "2026-06-10T12:05:00.000Z"
}

Tampilkan QR agar pengguna dapat memindainya dengan ponsel mereka (WhatsApp > Perangkat Tertaut > Tautkan Perangkat):

• qr_data_url adalah gambar yang siap digunakan - masukkan langsung ke dalam <img src>.
• qr_code adalah payload mentah jika Anda lebih suka membuat gambarnya sendiri.

QR tersebut berumur pendek. Jika Anda memanggil ini tepat setelah memulai sesi, Anda mungkin mendapatkan 404 dengan pesan “QR code not available yet” - tunggu sebentar dan coba lagi. Jika Anda mendapatkan 410 (“QR code expired”), mulai ulang koneksi untuk mendapatkan kode baru.

Langkah 3 - Melakukan polling status hingga terhubung #

GET /channels/whatsapp-web/connections/{phoneNumber}/status

cURL

curl "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+15551230000");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "connected" (or "open").

Python

import urllib.parse

phone = urllib.parse.quote("+15551230000")
res = requests.get(
    f"https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "connected" (or "open").

Respons

{
  "success": true,
  "phone_number": "+15551230000",
  "status": "connected",
  "has_qr": false,
  "qr_expires_at": null,
  "last_activity": null,
  "message_count": null,
  "proxy": null,
  "live": true
}

Memutuskan sesi WhatsApp Web #

DELETE /channels/whatsapp-web/connections/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/whatsapp-web/connections/+15551230000" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "phone_number": "+15551230000", "status": "removed" }

Ini akan memutuskan tautan perangkat dan menghapus koneksi. Tindakan ini selalu membersihkan status lokal, sehingga bersifat idempoten meskipun sesi yang mendasarinya sudah tidak ada.

Telegram #

Ketersediaan: Telegram terhubung seperti saluran lainnya dan terbuka untuk setiap akun — Anda tidak perlu mengaktifkannya secara khusus. Endpoint Telegram di bawah ini masih dapat mengembalikan 403 jika Telegram tidak termasuk dalam paket akun, yang dalam kasus tersebut pesan kesalahannya berbunyi "This channel is not included in your current plan. Upgrade to unlock it.".

Telegram menghubungkan akun pribadi melalui nomor telepon ditambah kode login sekali pakai (dan kata sandi dua faktor, jika akun telah mengaturnya). Alurnya adalah: mulai sesi, kirim kode, kirim kata sandi secara opsional, lalu konfirmasi melalui status.

Langkah 1 - Memulai sesi koneksi Telegram #

POST /channels/telegram/connect

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "phone_number": "+14155550100" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/telegram/connect", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone_number: "+14155550100" }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/telegram/connect",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"phone_number": "+14155550100"},
)
data = res.json()

Respons

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "code_required",
  "session_id": "session-id",
  "connect_url": "https://api.youraiconnector.com/v1/channels/telegram/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Dalam mode code, akun menerima kode login di Telegram dan status adalah code_required. (Dalam mode qr, respons juga menyertakan login_token dan qr_url untuk ditampilkan agar dipindai, dan status adalah qr_required.)

Opsi termudah untuk Telegram: serahkan connect_url #

Respons tersebut menyertakan connect_url yang siap pakai: halaman yang dihosting yang menyelesaikan koneksi dengan sendirinya. Dalam mode code, pemilik akun memasukkan kode login - dan kata sandi verifikasi dua langkah jika akun mereka memilikinya. Dalam mode qr, halaman tersebut menampilkan kode QR yang diperbarui secara otomatis untuk dipindai oleh mereka dari aplikasi Telegram. Bagaimanapun, halaman ini melaporkan keberhasilan secara mandiri, jadi Anda cukup memberikan tautan ini kepada pemilik akun alih-alih membangun UI Anda sendiri dan melakukan polling. Tautan ini berfungsi selama sekitar 30 menit (connect_url_expires_at); jika kedaluwarsa, mulai koneksi baru untuk mendapatkan yang baru.

Langkah-langkah manual di bawah ini (mengumpulkan kode sendiri, mengirimkannya, melakukan polling status; atau merender qr_url dan melakukan polling) ditujukan untuk integrasi yang ingin merender UI sendiri.

Langkah 2 - Mengirimkan kode login #

POST /channels/telegram/connect/{phoneNumber}/verify-code

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-code" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "12345" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-code`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ code: "12345" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-code",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"code": "12345"},
)
data = res.json()

Respons

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Jika status adalah connected, Anda selesai. Jika akun mengaktifkan dua faktor, status akan menjadi password_required - lanjutkan ke langkah 3.

Langkah 3 - Mengirimkan kata sandi dua faktor (hanya jika diperlukan) #

POST /channels/telegram/connect/{phoneNumber}/verify-password

Hanya panggil ini saat langkah 2 mengembalikan password_required.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/verify-password" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "password": "the-2fa-password" }'

JavaScript

const phone = encodeURIComponent("+14155550100");
const res = await fetch(
  `https://api.youraiconnector.com/v1/channels/telegram/connect/${phone}/verify-password`,
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ password: "the-2fa-password" }),
  }
);
const data = await res.json();

Python

import urllib.parse

phone = urllib.parse.quote("+14155550100")
res = requests.post(
    f"https://api.youraiconnector.com/v1/channels/telegram/connect/{phone}/verify-password",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"password": "the-2fa-password"},
)
data = res.json()

Respons

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "username": "myhandle"
}

Memeriksa status Telegram #

GET /channels/telegram/connect/{phoneNumber}/status

curl "https://api.youraiconnector.com/v1/channels/telegram/connect/+14155550100/status" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "phone_number": "+14155550100",
  "status": "connected",
  "telegram_user_id": "100000001",
  "live": true
}

status bisa berupa connected, code_required, password_required, initializing, disconnected, not_initialized, atau error.

Memutuskan koneksi Telegram #

DELETE /channels/telegram/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/telegram/+14155550100" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "phone_number": "+14155550100", "status": "removed" }

Idempotent - panggilan berulang akan berhasil.

Instagram (akun pribadi) #

Beta dengan ketersediaan terbatas, diaktifkan per akun. Ini menghubungkan akun Instagram pribadi dengan masuk menggunakan nama pengguna dan kata sandinya (bukan API Bisnis resmi). Jika akun tidak diaktifkan untuk beta, panggilan koneksi akan mengembalikan kesalahan izin.

Karena ini memerlukan login Instagram milik pemegang akun itu sendiri, cara termudah adalah dengan memberikan connect_url yang dihosting kepada mereka dan membiarkan mereka memasukkan kredensial mereka di sana - integrasi Anda tidak akan pernah menangani kata sandi tersebut.

Langkah 1 - Memulai koneksi Instagram (pribadi) #

POST /channels/instagram-private/connect

Kirim Instagram username dan password.

Respons

{
  "success": true,
  "status": "connected",
  "connect_url": "https://api.youraiconnector.com/v1/channels/instagram-private/connect/page?token=eyJhbGciOi...",
  "connect_url_expires_at": 1717000000000
}

Jika akun memiliki autentikasi dua faktor atau Instagram menampilkan pemeriksaan, status akan kembali sebagai two_factor_required atau challenge_required - kirimkan kode ke /connect/{id}/verify-2fa atau /connect/{id}/verify-challenge di bawah, lalu polling /connect/{id}/status hingga connected. {id} adalah nama pengguna Instagram yang dinormalisasi yang dikembalikan sebagai account_id/username dalam respons di atas - gunakan pada setiap langkah di bawah.

Langkah 2 - Kirimkan kode dua faktor (jika diminta) #

POST /channels/instagram-private/connect/{id}/verify-2fa

Hanya panggil ini saat langkah 1 (atau langkah 3) mengembalikan two_factor_required.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-2fa" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Respons

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand"
}

status dapat kembali sebagai connected (selesai), two_factor_required (kode salah, coba lagi), atau challenge_required (Instagram juga meminta kode pemeriksaan - buka langkah 3).

Langkah 3 - Kirimkan kode konfirmasi pemeriksaan (jika diminta) #

POST /channels/instagram-private/connect/{id}/verify-challenge

Hanya panggil ini saat langkah sebelumnya mengembalikan challenge_required. Bentuk permintaan dan respons yang sama seperti langkah 2 di atas.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/verify-challenge" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "123456" }'

Periksa status Instagram (pribadi) #

GET /channels/instagram-private/connect/{id}/status

Polling ini hingga status adalah connected, atau hingga melaporkan kegagalan terminal.

curl "https://api.youraiconnector.com/v1/channels/instagram-private/connect/yourbrand/status" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "account_id": "yourbrand",
  "status": "connected",
  "ig_user_id": "17890000000000000",
  "username": "yourbrand",
  "live": true
}

status bisa berupa connected, two_factor_required, challenge_required, initializing, disconnected, not_initialized, atau error. live: true berarti ini dibaca langsung dari pekerja koneksi alih-alih nilai yang di-cache.

Opsi termudah untuk Instagram (pribadi): serahkan connect_url #

Respons tersebut menyertakan connect_url: halaman yang dihosting tempat pemegang akun memasukkan nama pengguna dan kata sandi Instagram mereka (serta kode 2FA atau pos pemeriksaan jika Instagram memintanya), dan yang melaporkan keberhasilan dengan sendirinya. Kredensial langsung dikirim ke Instagram dan tidak disimpan. Berikan tautan ini kepada pemegang akun alih-alih mengumpulkan kata sandi mereka di UI Anda sendiri. Tautan ini berfungsi selama sekitar 30 menit (connect_url_expires_at).

Putuskan sambungan Instagram (pribadi) #

DELETE /channels/instagram-private/{id}

Idempotent - panggilan berulang akan berhasil.

Sinkronisasi pengikut #

POST /channels/instagram-private/{id}/sync-followers

Memicu sinkronisasi pengikut secara manual untuk akun yang terhubung - pekerjaan yang sama yang berjalan secara otomatis di latar belakang, ditampilkan di sini untuk tindakan “Segarkan pengikut” sesuai permintaan. Ini mengambil daftar pengikut akun saat ini, mencatat siapa pun yang baru, dan (saat kampanye Langsung mengaktifkan penjangkauan pengikut) mengirimkan DM pembuka kepada pengikut baru, hingga batas harian.

curl -X POST "https://api.youraiconnector.com/v1/channels/instagram-private/yourbrand/sync-followers" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "accountId": "yourbrand",
  "totalFollowers": 1204,
  "newFollowers": 6,
  "dmsSent": 6,
  "isBaselineSeed": false
}

Kelima kolom ini adalah satu-satunya tempat di halaman ini yang mengembalikan camelCase alih-alih snake_case - begitulah cara endpoint ini diatur saat ini, bukan kesalahan ketik. isBaselineSeed: true berarti ini adalah sinkronisasi pertama setelah menghubungkan, yang hanya mencatat daftar pengikut awal dan tidak pernah mengirim DM penjangkauan (jadi dmsSent selalu 0 pada proses tersebut).

Panggilan pertama untuk sebuah akun mungkin memakan waktu cukup lama (menelusuri daftar pengikut lengkap); panggilan berikutnya lebih cepat karena hanya pengikut baru yang dibandingkan. 404 berarti akun tidak terhubung; 412 berarti koneksi belum selesai diinisialisasi - tunggu dan coba lagi.

LINE #

LINE adalah saluran paling sederhana untuk dihubungkan karena tidak ada pengalihan browser atau polling. Pelanggan membuat saluran Messaging API di konsol LINE Developers, menyalin dua nilai, dan Anda mengirimkannya dalam satu panggilan. Anda kemudian memberikan kembali URL webhook kepada mereka untuk ditempelkan ke dalam konsol.

Langkah 1 - Hubungkan dengan kredensial saluran #

POST /channels/line

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/line?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    "channel_secret": "CHANNEL_SECRET"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/line", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    channel_access_token: "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
    channel_secret: "CHANNEL_SECRET",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/line",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "channel_access_token": "LONG_LIVED_CHANNEL_ACCESS_TOKEN",
        "channel_secret": "CHANNEL_SECRET",
    },
)
data = res.json()

Respons

{
  "success": true,
  "status": "connected",
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Dua bidang penting untuk apa yang Anda lakukan selanjutnya:

• webhook_url - pelanggan harus menempelkan ini ke dalam bidang Webhook URL saluran LINE mereka di konsol LINE Developers (dan aktifkan “Use webhook”). Sampai mereka melakukannya, tidak ada pesan masuk yang akan diterima. Tampilkan ini kepada mereka dengan jelas.
• chat_mode_ok - ketika false, Akun Resmi berada dalam mode “chat” dan tidak akan menerima atau mengirim pesan sampai diubah ke mode “bot” di LINE Official Account Manager. Batasi proses onboarding Anda pada tanda ini dan beri tahu pelanggan untuk mengubah modenya.

channel_access_token dan channel_secret tidak pernah dikembalikan oleh titik akhir mana pun. Simpan di sisi Anda jika Anda membutuhkannya lagi; jika tidak, tempel ulang dari konsol LINE.

bot_user_id yang dikembalikan di sini adalah pengidentifikasi koneksi yang Anda gunakan dalam panggilan status, verifikasi, dan pemutusan sambungan di bawah.

Langkah 2 - Verifikasi ulang setelah pengaturan webhook #

POST /channels/line/{botUserId}/verify-webhook

Setelah pelanggan selesai mengonfigurasi URL webhook dan beralih ke mode bot, panggil ini untuk memvalidasi ulang token yang tersimpan dan menyegarkan mode obrolan yang di-cache.

curl -X POST "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "token_valid": true,
  "chat_mode": "bot",
  "chat_mode_ok": true,
  "webhook_url": "https://api.youraiconnector.com/line/webhook/..."
}

Jika token_valid adalah false, token akses yang tersimpan tidak lagi terautentikasi - minta pelanggan untuk menerbitkannya kembali di konsol dan panggil POST /channels/line lagi dengan token baru.

Periksa status LINE #

GET /channels/line/{botUserId}/status

curl "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx.../status" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "channel": "line",
  "status": "connected",
  "basic_id": "@mybusiness",
  "display_name": "My Business",
  "picture_url": "https://...",
  "chat_mode": "bot",
  "is_active": true,
  "live": false
}

LINE tidak memiliki feed status langsung, jadi live di sini selalu false - nilai-nilai tersebut mencerminkan status yang ditangkap pada saat terhubung (atau verifikasi terakhir).

Putuskan sambungan LINE #

DELETE /channels/line/{botUserId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/line/Uxxxxxxxx..." \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "status": "removed", "bot_user_id": "Uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }

Viber #

Viber terhubung dengan cara yang sama seperti LINE - tempel token autentikasi bot dari Panel Admin Viber dalam satu panggilan - dengan satu perbedaan yang perlu diketahui: menghubungkan juga MENDAFTARKAN webhook kami pada bot Anda saat itu juga, jadi tidak ada langkah konsol terpisah setelahnya. Itu juga berarti upaya koneksi bisa gagal jika ingress kami tidak dapat menjawab pemeriksaan webhook sinkron Viber, bukan hanya jika token itu sendiri salah.

Langkah 1 - Hubungkan dengan token autentikasi bot #

POST /channels/viber

curl -X POST "https://api.youraiconnector.com/v1/channels/viber?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "auth_token": "444d5555e6666f7777a8888b9999c000" }'

Respons

{
  "success": true,
  "status": "connected",
  "bot_id": "botIdFromViber",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "subscribers_count": 0,
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"]
}

Token autentikasi tidak pernah ditampilkan kembali oleh endpoint mana pun - simpan di sisi Anda jika Anda perlu menempelkannya kembali. bot_id adalah pengidentifikasi koneksi yang digunakan oleh panggilan status, verifikasi, dan pemutusan koneksi di bawah.

Periksa status Viber #

GET /channels/viber/{botId}/status

Melaporkan status koneksi yang tersimpan. Tambahkan ?live=true untuk juga memeriksa ulang bot terhadap Viber dan menyegarkan pendaftaran webhook yang di-cache - berguna sebelum berasumsi bahwa bot yang diam sebenarnya rusak.

curl "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/status?live=true" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "bot_id": "botIdFromViber",
  "channel": "viber",
  "status": "connected",
  "bot_name": "My Business Bot",
  "bot_avatar": "https://...",
  "bot_uri": "mybusinessbot",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "registered_webhook": "https://api.youraiconnector.com/v1/incoming-viber-message/...",
  "webhook_ok": true,
  "subscribers_count": 128,
  "is_active": true,
  "live": true
}

webhook_ok: false berarti webhook bot tidak lagi mengarah ke kami - pesan masuk tidak akan sampai. Ini biasanya berarti alat lain menghubungkan bot yang sama setelahnya (pendaftaran webhook Viber bersifat last-write-wins). Perbaiki dengan panggilan verifikasi ulang di bawah, tidak perlu meminta pelanggan untuk menempelkan kembali token mereka. live adalah false saat respons merupakan status cache terakhir alih-alih pemeriksaan baru terhadap Viber.

Daftarkan ulang webhook #

POST /channels/viber/{botId}/verify-webhook

Tindakan perbaikan untuk webhook_ok: false - mendaftarkan ulang webhook kami pada bot menggunakan token autentikasi yang sudah tersimpan.

curl -X POST "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber/verify-webhook" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "token_valid": true, "webhook_ok": true, "webhook_url": "https://api.youraiconnector.com/v1/incoming-viber-message/...", "event_types": ["delivered", "seen", "failed", "subscribed", "unsubscribed", "conversation_started"] }

token_valid: false berarti token yang tersimpan tidak lagi berfungsi - hubungkan kembali dengan POST /channels/viber dan token baru.

Memutuskan Viber #

DELETE /channels/viber/{botId}

Membatalkan pendaftaran webhook kami di sisi Viber (upaya terbaik) dan menghapus koneksi.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/viber/botIdFromViber" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "status": "removed", "bot_id": "botIdFromViber", "webhook_removed": true }

TikTok #

Ketersediaan: Beta dengan ketersediaan terbatas, diaktifkan per akun. Menghubungkan TikTok akan menghasilkan kesalahan izin sampai akun diaktifkan untuk fitur tersebut.

TikTok Business Messaging adalah saluran OAuth penuh seperti Meta, tetapi lebih sederhana di sisi polling: tidak ada langkah polling status khusus untuk dibangun, karena akun yang terhubung muncul dengan sendirinya setelah TikTok mengalihkan kembali dan koneksi ditulis. Titik akhir status di bawah ini ada untuk mengonfirmasi status sesuai permintaan (alat pendukung, pemeriksaan kesehatan), bukan sebagai sesuatu yang perlu Anda lakukan berulang kali saat menghubungkan.

Langkah 1 - Memulai koneksi TikTok #

POST /channels/tiktok/connect

Tidak memerlukan kredensial - pemegang akun memberikan otorisasi sepenuhnya di browser mereka.

curl -X POST "https://api.youraiconnector.com/v1/channels/tiktok/connect?apiKey=YOUR_API_KEY"

Respons

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://www.tiktok.com/v2/auth/authorize?client_key=...&state=...",
  "state_token": "opaque-one-time-token",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Buka oauth_url di browser pemegang akun agar mereka dapat masuk ke TikTok dan menyetujui akses. Status kedaluwarsa pada expires_at (sekitar 30 menit) - jika sudah lewat, mulai dari awal. Tidak ada pintasan halaman yang dihosting connect_url untuk TikTok; membuka oauth_url sendiri adalah satu-satunya cara.

Memeriksa status TikTok #

GET /channels/tiktok/{openId}/status

openId adalah open_id Akun Bisnis TikTok, yang diketahui setelah callback OAuth dijalankan.

curl "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok/status" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "open_id": "openIdFromTikTok",
  "channel": "tiktok",
  "status": "connected",
  "business_id": "openIdFromTikTok",
  "username": "mybusiness",
  "display_name": "My Business",
  "avatar_url": "https://...",
  "status_reason": null,
  "is_active": true,
  "live": false
}

TikTok tidak memiliki pemeriksaan kesehatan langsung yang murah, jadi live selalu false di sini - kolom-kolom tersebut mencerminkan apa yang ditulis oleh koneksi (atau penyegaran token terakhir). status: "reauth_required" dengan status_reason yang diatur berarti akun perlu melalui proses koneksi lagi; token TikTok disegarkan secara otomatis dalam rotasi tahunan, dan inilah yang muncul jika rotasi tersebut gagal.

Memutuskan TikTok #

DELETE /channels/tiktok/{openId}

curl -X DELETE "https://api.youraiconnector.com/v1/channels/tiktok/openIdFromTikTok" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "status": "removed", "open_id": "openIdFromTikTok" }

GoHighLevel #

GoHighLevel (GHL) adalah integrasi CRM, bukan saluran perpesanan - menghubungkannya tidak akan menghabiskan slot saluran pada paket, karena integrasi ini menggunakan saluran yang sudah ada pada akun alih-alih menambahkan yang baru. Ini juga satu-satunya integrasi di halaman ini yang dapat menampung lebih dari satu koneksi sekaligus: setiap sub-akun GHL (“lokasi”) tempat pelanggan menginstal aplikasi akan mendapatkan entri tersendiri.

Langkah 1 - Memulai koneksi GHL #

POST /channels/ghl/connect

curl -X POST "https://api.youraiconnector.com/v1/channels/ghl/connect?apiKey=YOUR_API_KEY"

Respons

{
  "success": true,
  "status": "pending_authorization",
  "oauth_url": "https://marketplace.gohighlevel.com/oauth/chooselocation?client_id=...&state=...",
  "state_token": "opaque-one-time-token",
  "brand": "dmchamp",
  "expires_at": "2026-06-10T12:30:00.000Z"
}

Buka oauth_url di browser pemilik akun agar mereka dapat memilih lokasi GHL dan menyetujui akses. Status ini akan kedaluwarsa pada expires_at (sekitar 30 menit).

Mencantumkan koneksi GHL #

GET /channels/ghl/status

Tidak seperti saluran lain, ini bukan status satu koneksi saja - ini mencantumkan setiap lokasi yang telah dihubungkan oleh akun tersebut.

curl "https://api.youraiconnector.com/v1/channels/ghl/status" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "connections": [
    {
      "location_id": "abc123location",
      "company_id": "xyz789company",
      "brand": "dmchamp",
      "status": "connected",
      "status_reason": null,
      "scopes": ["conversations.readonly", "conversations.write", "conversations/message.write"],
      "connected_at": "2026-06-01T10:00:00.000Z",
      "conversation_provider_id": "provider-id-in-ghl",
      "trigger_subscriptions": [
        { "id": "sub_1", "key": "InboundMessage", "workflow_id": "wf_123" }
      ]
    }
  ]
}

Memutuskan koneksi lokasi GHL #

DELETE /channels/ghl/{locationId}

Menghapus koneksi di sini, yang akan menghentikan setiap sinkronisasi dan pemicu untuk lokasi tersebut. Ini tidak menghapus instalan aplikasi di sisi GHL - pelanggan harus menghapusnya dari instalasi marketplace GHL mereka jika mereka menginginkannya.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/ghl/abc123location" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "status": "disconnected", "location_id": "abc123location" }

Nomor telepon (beli dan lepas) #

Alih-alih menghubungkan nomor yang sudah ada, Anda dapat membeli nomor baru yang mendukung WhatsApp secara langsung. Cari nomor yang tersedia, beli satu, lalu lakukan polling hingga proses penyediaan selesai.

Langkah 1 - Cari nomor yang tersedia #

GET /phone-numbers/available?country_code=ISO2

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/phone-numbers/available?country_code=US",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/phone-numbers/available",
    params={"country_code": "US"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respons

{
  "success": true,
  "phone_numbers": [
    {
      "phone_number": "+14155551234",
      "purchase_credits": 50,
      "monthly_credits": 50,
      "cost_usd": 1.15
    }
  ]
}

Setiap hasil menunjukkan purchase_credits satu kali dan monthly_credits berulang. Nomor yang disediakan platform berharga setidaknya 50 kredit per bulan, meningkat sesuai harga bulanan operator itu sendiri, yang dibebankan saat pembelian dan pada setiap perpanjangan. Gunakan purchase_credits / monthly_credits yang dikembalikan oleh pencarian; jangan pernah menentukan harga sendiri. Pencarian pertama pada akun baru menyediakan beberapa sumber daya dasar, sehingga mungkin sedikit lebih lambat daripada pencarian berikutnya.

Langkah 2 - Membeli nomor #

POST /phone-numbers

Gunakan phone_number dari hasil pencarian.

cURL

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/phone-numbers", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_number: "+14155551234",
    country_code: "US",
    display_name: "Support line",
  }),
});
const data = await res.json();

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/phone-numbers",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phone_number": "+14155551234",
        "country_code": "US",
        "display_name": "Support line",
    },
)
data = res.json()

Respons

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "whatsapp_status": "PURCHASED",
  "outgoing_status": "PURCHASED",
  "status": "PURCHASED",
  "purchase_credits": 50,
  "monthly_credits": 50
}

Nomor dimulai dalam status PURCHASED. Pendaftaran WhatsApp kemudian berlanjut di latar belakang: PURCHASED -> PENDING -> ONLINE.

Jika pembelian gagal karena alamat bisnis tidak ada atau detail wajib lainnya belum diatur, Anda akan mendapatkan 400 dengan error yang deskriptif. Atur detail yang kurang tersebut dan coba lagi.

Langkah 3 - Lakukan polling hingga ONLINE #

GET /phone-numbers/{phoneNumber}/status

Ini adalah endpoint status nomor telepon bersama - ini berfungsi untuk nomor WhatsApp yang dibeli maupun nomor Anda yang lain yang terhubung.

cURL

curl "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const phone = encodeURIComponent("+14155551234");
const res = await fetch(
  `https://api.youraiconnector.com/v1/phone-numbers/${phone}/status`,
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
// Poll until data.status === "ONLINE".

Python

import urllib.parse

phone = urllib.parse.quote("+14155551234")
res = requests.get(
    f"https://api.youraiconnector.com/v1/phone-numbers/{phone}/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
# Poll until data["status"] == "ONLINE".

Respons

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "status": "ONLINE",
  "status_reason": null,
  "live": true
}

Langkah 4 - Melepaskan nomor #

DELETE /phone-numbers/{phoneNumber}

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "phone_number": "+14155551234", "released": true }

Apa yang dilakukan hal ini bergantung pada milik siapa nomor tersebut.

Untuk nomor yang disewa melalui platform, ini adalah pelepasan yang sebenarnya: pengirim WhatsApp dibatalkan pendaftarannya, nomor dikembalikan ke operator dan dihapus dari akun, masa tunggu 7 hari diterapkan di mana nomor tersebut tidak dapat dibeli kembali oleh siapa pun, dan tidak ada kredit yang dikembalikan.

Untuk nomor yang dibawa sendiri oleh akun (akun Twilio miliknya sendiri, aplikasi Meta atau Akun WhatsApp Business miliknya sendiri, atau gateway SMS Android), panggilan yang sama hanya menghapusnya dari akun tersebut. Tidak ada yang dirilis di penyedia hulu dan tidak ada masa tunggu (cooldown) yang dicatat, sehingga nomor tersebut dapat segera dihubungkan kembali. Registrasi pengirim WhatsApp-nya, jika ada, mungkin bertahan atau tidak: proses penghapusan mencoba menghapus pengirim menggunakan kredensial Twilio yang dikelola platform akun tersebut. Pada akun yang masih menggunakan pengaturan terkelola, kredensial tersebut valid dan pengirim dihapus, sehingga menghubungkan kembali berarti mendaftarkannya lagi. Pada akun yang telah beralih ke Twilio miliknya sendiri, penghapusan tidak dapat diautentikasi, dan pengirim tetap terdaftar di akun tersebut — menghubungkan kembali berarti hanya menyambungkan kembali pengirim yang sudah ada.

Menambahkan nomor yang sudah Anda miliki (BYO) #

POST /phone-numbers/byo

Melewati alur cari-dan-beli di atas sepenuhnya. Gunakan ini saat akun membawa nomornya sendiri (Twilio mereka sendiri, Akun WhatsApp Business Meta mereka sendiri, atau gateway SMS Android) alih-alih menyewa melalui platform. Ini hanya mencatat nomor tersebut - tidak ada kredit yang dibebankan, dan tidak ada yang diprovisikan dengan penyedia di sini. Nomor tetap tidak aktif sampai pemilik akun menyelesaikan OAuth WhatsApp untuk mendaftarkan Pengirim di nomor tersebut (alur yang sama yang dimulai oleh tombol “Bawa nomor Anda sendiri” di dasbor).

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/byo?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155551234",
    "country_code": "US",
    "display_name": "Support line"
  }'

Respons (201 Created):

{
  "success": true,
  "phone_number": "+14155551234",
  "channel": "whatsapp",
  "type": "BYO",
  "whatsapp_status": "ADDED",
  "outgoing_status": "ADDED",
  "is_active": false
}

phone_number yang bukan merupakan nomor E.164 asli (atau yang terlihat seperti nomor tes WhatsApp Meta, yang tidak pernah bisa mengirim pesan ke pelanggan asli) akan mengembalikan 400. Menambahkan nomor yang sudah ada di akun - bahkan jika penulisannya sedikit berbeda, seperti bentuk +52 vs +521 di Meksiko - akan mengembalikan 409 alih-alih membuat baris duplikat.

Menetapkan nomor sebagai utama #

POST /phone-numbers/{phoneNumber}/set-primary

Mengubah satu nomor menjadi is_active: true dan setiap nomor lain di akun menjadi is_active: false, secara atomik - akun tidak akan pernah memiliki dua nomor aktif, atau tidak ada sama sekali, di tengah permintaan. is_active tidak dapat ditetapkan melalui endpoint pembaruan umum dengan sengaja; panggilan khusus ini adalah satu-satunya cara untuk mengubah nomor mana yang menjadi utama.

curl -X POST "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/set-primary" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{
  "success": true,
  "phone_number": {
    "id": "+14155551234",
    "phone_number": "+14155551234",
    "display_name": "Support line",
    "channel": "whatsapp",
    "is_active": true,
    "whatsapp_status": "ONLINE"
  }
}

phone_number di sini adalah objek nomor lengkap (bentuk yang sama yang dikembalikan GET /phone-numbers), bukan hanya string. phoneNumber yang tidak ada di akun akan mengembalikan 404.

Menghapus catatan nomor (tanpa melepaskannya) #

DELETE /phone-numbers/{phoneNumber}/record

Penghapusan biasa atas catatan nomor di akun ini - tidak ada pelepasan atau pembatalan pendaftaran di sisi penyedia, dan tidak ada masa tunggu 7 hari seperti yang berlaku pada langkah pelepasan di atas. Gunakan ini untuk menghapus catatan BYO, WhatsApp Web, Telegram, atau LINE, atau entri yang sudah usang, tanpa melalui alur pelepasan terkelola. Tidak seperti pelepasan, menghapus nomor yang tidak ada di akun adalah 404, bukan keberhasilan senyap.

curl -X DELETE "https://api.youraiconnector.com/v1/phone-numbers/+14155551234/record" \
  -H "X-API-Key: YOUR_API_KEY"

Respons

{ "success": true, "phone_number": "+14155551234", "deleted": true }

Mengarahkan saluran ke kampanye #

Menghubungkan saluran akan memasukkan pesan ke dalam akun. Hal ini tidak menentukan AI Agent mana yang menjawabnya.

Perutean ditangani oleh Entry Points pada AI Agent, bukan oleh kampanye. Setiap saluran memiliki satu Entry Point default saluran yang menamai Agen yang menjawab kontak baru yang tidak dikenal di saluran tersebut:

Sampai sebuah saluran memiliki Titik Masuk (Entry Point), pesan pertama dari seseorang yang belum pernah Anda ajak bicara akan tetap tersimpan, tetapi tidak ada yang mengambilnya dan tidak ada asisten yang membalas. Ini adalah langkah yang paling sering terlewatkan oleh integrasi: menghubungkan Instagram dan membuat Agen saja tidak cukup — Anda juga harus mengarahkan saluran tersebut ke Agen. Kumpulan panggilan lengkap — termasuk satu Agen per nomor WhatsApp, kata kunci, dan aturan komentar — ada di API Titik Masuk.

POST /channels/campaign masih menulis peta perutean kampanye per saluran warisan, yang didokumentasikan di bawah, tetapi peta tersebut tidak lagi dikonsultasikan untuk perutean masuk di akun mana pun; peta tersebut dipertahankan hanya untuk rollback. Jangan membangun aplikasi berdasarkan peta tersebut.

Rute satu atau beberapa saluran (peta perutean kampanye warisan) #

POST /channels/campaign

Bidang permintaan

Slot perutean dan daftar enabled_channels kampanye diperbarui bersamaan dalam satu operasi atomik, sehingga keduanya tidak akan pernah tidak sinkron. Saluran yang sudah diarahkan ke kampanye lain cukup diarahkan ulang ke kampanye ini.

cURL

curl -X POST "https://api.youraiconnector.com/v1/channels/campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
    "channels": ["instagram", "messenger"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/channels/campaign", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "NBCXrhqGPSFsd6MV7pRo",
    channels: ["instagram", "messenger"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/channels/campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
        "channels": ["instagram", "messenger"],
    },
)
data = res.json()

Respons

{
  "success": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo",
  "channels": ["instagram", "messenger"]
}

Apa yang harus dipenuhi agar perutean benar-benar berjalan #

Pada akun yang masih membaca peta perutean kampanye warisan, perutean berhasil sebagai panggilan API tetapi tiga hal pada kampanye menentukan apakah pesan masuk yang sebenarnya akan dijawab. Periksa ketiganya saat saluran yang dirutekan tetap diam.

Pencocokan kata kunci sekarang ada pada Entry Points — buat Entry Point dengan tipe keyword pada AI Agent yang seharusnya menjawab.

Satu kampanye per saluran #

Setiap saluran menampung tepat satu slot perutean warisan. Merutekan kampanye kedua ke saluran yang sama akan mengarahkan ulang slot tersebut secara diam-diam dan mengembalikan 200 — tidak ada kesalahan konflik. Kampanye sebelumnya tetap menangani kontak yang sudah dimilikinya; kampanye tersebut hanya berhenti menerima kontak baru.

Menghapus perutean saluran #

DELETE /channels/campaign/{channel}

Menghapus perutean untuk satu saluran, apa pun kampanye yang saat ini dituju, dan mengeluarkan saluran tersebut dari enabled_channels kampanye itu. Kontak baru yang tidak dikenal pada saluran tersebut tidak lagi diambil oleh kampanye mana pun. Kontak yang sudah ada di dalam kampanye akan tetap berjalan seperti sebelumnya.

curl -X DELETE "https://api.youraiconnector.com/v1/channels/campaign/instagram?apiKey=YOUR_API_KEY"

Respons

{
  "success": true,
  "channel": "instagram",
  "cleared": true,
  "campaign_id": "NBCXrhqGPSFsd6MV7pRo"
}

Ini bersifat idempoten: menghapus saluran yang tidak pernah dirutekan juga akan mengembalikan 200, dengan cleared: false dan campaign_id: null. Titik akhir ini memerlukan fitur kampanye masuk pada paket Anda; tanpanya, Anda akan mendapatkan 403.

Gunakan aplikasi Meta Anda sendiri (Instagram + Messenger) #

Secara default, koneksi Instagram + Messenger berjalan melalui aplikasi Meta platform, sehingga nama aplikasi tersebutlah yang dilihat oleh pemegang akun di layar persetujuan Facebook. Jika Anda ingin layar persetujuan menampilkan merek Anda sebagai gantinya, Anda dapat mendaftarkan aplikasi Meta Anda sendiri dan mengarahkan seluruh alur melaluinya. Setelah dikonfigurasi, ini akan berlaku untuk akun Anda — tidak ada yang berubah dalam panggilan koneksi di atas kecuali branding-nya.

Ini hanya mencakup Instagram + Messenger. Koneksi WhatsApp, WhatsApp Web, Telegram, dan LINE tidak terpengaruh oleh aplikasi Meta kustom.

Apa yang dibutuhkan aplikasi Anda terlebih dahulu #

Ini adalah bagian yang memakan waktu, dan sepenuhnya terjadi di sisi Meta:

1. Sebuah aplikasi dengan tipe Bisnis, dengan produk Messenger dan Instagram ditambahkan.
2. Akses Lanjutan (melalui Tinjauan Aplikasi Meta) untuk: pages_show_list, pages_messaging, pages_manage_metadata, pages_read_engagement, instagram_basic, instagram_manage_messages. Tanpa Akses Lanjutan, hanya orang yang memiliki peran di aplikasi Anda yang dapat menyelesaikan koneksi — koneksi klien Anda akan gagal. Tinjauan Aplikasi biasanya memakan waktu beberapa minggu dan memerlukan Verifikasi Bisnis.
3. Konfigurasi Facebook Login for Business yang dibuat di dalam aplikasi Anda, dengan memberikan izin yang sama. ID konfigurasi numeriknya bersifat per-aplikasi, jadi Anda harus membuat milik Anda sendiri.

Jika aplikasi Anda kehilangan salah satu izin yang diperlukan, koneksi akan gagal pada saat menghubungkan dengan kesalahan yang jelas menyebutkan apa yang hilang (terlihat di polling /status sebagai byo_app_missing_permissions) — alih-alih tampak berhasil namun gagal pada pesan pertama.

Langkah 1 - Simpan aplikasi Anda #

PUT /account-config/meta-app

Ketiganya diperlukan untuk alur Login Facebook. Jika Anda hanya menjalankan jalur push-token Login Instagram yang dijelaskan di bawah, Anda dapat mengabaikannya sepenuhnya.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "1234567890123456",
    "app_secret": "your-app-secret",
    "config_id": "9876543210987654"
  }'

Respons

{
  "success": true,
  "app_id": "1234567890123456",
  "config_id": "9876543210987654",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram": "https://api.youraiconnector.com/v1/incoming-instagram-message/byo/YOUR_ACCOUNT_ID",
    "messenger": "https://api.youraiconnector.com/v1/incoming-messenger-message/byo/YOUR_ACCOUNT_ID"
  }
}

Langkah 2 - Konfigurasikan aplikasi Anda untuk berkomunikasi dengan kami #

Di dasbor aplikasi Meta Anda:

1. Webhook - untuk produk Instagram maupun Messenger, atur URL Callback ke nilai webhook_urls yang cocok dari respons, dan token Verifikasi ke verify_token. Berlanggananlah ke bidang messages, messaging_postbacks, dan comments.
2. URI Pengalihan OAuth yang Valid - tambahkan https://api.youraiconnector.com/v1/auth-meta-callback-handler agar alur persetujuan dapat kembali.

GET /account-config/meta-app mengembalikan materi pengaturan yang sama kapan saja; DELETE /account-config/meta-app menghapus aplikasi (koneksi di masa mendatang akan kembali ke aplikasi platform — hapus juga langganan webhook di dalam aplikasi Anda).

Langkah 3 - Hubungkan seperti biasa #

Tidak ada hal lain yang berubah. POST /channels/meta/connect (dan halaman connect_url yang dihosting) secara otomatis menggunakan aplikasi Anda untuk akun Anda; uses_byo_meta_app: true respons mengonfirmasi aplikasi mana yang akan ditampilkan oleh layar persetujuan. Pengiriman pesan, pemilihan halaman, dan pemutusan koneksi berfungsi sama persis.

Gunakan aplikasi Login Instagram Anda sendiri (push token) #

Bagian di atas membahas alur Login Facebook, di mana akun terhubung melalui Halaman Facebook. Meta juga menawarkan API Instagram dengan Login Instagram (Login Bisnis untuk Instagram): pemilik akun melakukan autentikasi langsung di Instagram, tanpa melibatkan akun atau Halaman Facebook.

Jika platform Anda sudah menjalankan aplikasi Meta sendiri dengan produk tersebut, Anda sama sekali tidak memerlukan alur OAuth di pihak kami. Klien Anda mengotorisasi aplikasi Anda, dan Anda mengirimkan kredensial yang sudah jadi per akun kepada kami:

1. Anda menyimpan kredensial aplikasi Instagram Anda satu kali (agar kami dapat memverifikasi webhook Anda).
2. Per akun, Anda mengirimkan ID akun profesional Instagram + token pengguna Instagram berumur panjang yang diperoleh aplikasi Anda.
3. Anda mengarahkan webhook pesan Instagram aplikasi Anda ke kami. Peristiwa untuk akun yang tidak pernah Anda kirimkan akan diakui dan diabaikan.
4. Anda memiliki siklus hidup token: segarkan token di sistem Anda sendiri dan kirim setiap token yang telah disegarkan dengan panggilan yang sama. Kami tidak pernah menyegarkan token yang dikirimkan.

Apa yang dibutuhkan aplikasi Anda terlebih dahulu #

• Produk Instagram (“Pengaturan API dengan login Instagram”) ditambahkan ke aplikasi Meta Anda. Produk tersebut memiliki pasangan App ID dan App Secret sendiri, terpisah dari App ID/Secret Facebook — temukan di panel pengaturan produk.
• Akses Lanjutan (melalui Tinjauan Aplikasi Meta) untuk instagram_business_basic dan instagram_business_manage_messages (tambahkan instagram_business_manage_comments jika Anda menggunakan otomatisasi komentar). Tanpanya, hanya orang dengan peran di aplikasi Anda yang dapat mengotorisasinya.

Langkah 1 - Simpan kredensial aplikasi Instagram Anda #

Endpoint yang sama seperti di atas — kirim pasangan Instagram ke PUT /account-config/meta-app. Bidang Facebook tidak diperlukan untuk jalur ini: kirim pasangan tersebut sendiri jika Anda hanya menjalankan Login Instagram, atau bersama dengan bidang Facebook jika Anda menjalankan keduanya. Penyimpanan selalu menjelaskan pengaturan keseluruhan, jadi set mana pun yang Anda tinggalkan akan dihapus.

curl -X PUT "https://api.youraiconnector.com/v1/account-config/meta-app?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instagram_app_id": "1122334455667788",
    "instagram_app_secret": "your-instagram-app-secret"
  }'

Respons — membawa URL webhook Login Instagram (URL instagram dan messenger hanya muncul jika bidang Facebook juga disimpan):

{
  "success": true,
  "instagram_app_id": "1122334455667788",
  "verify_token": "1f4c…a9",
  "webhook_urls": {
    "instagram_login": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
  }
}

Di panel Webhook aplikasi Anda untuk produk Instagram, atur Callback URL ke webhook_urls.instagram_login, Verify token ke verify_token, dan berlangganan ke bidang messages dan comments.

Langkah 2 - Push token per akun #

PUT /channels/instagram-login/token

Bekerja dengan sub_account_id seperti rute lainnya, sehingga kunci agensi dapat menyediakan seluruh armadanya.

curl -X PUT "https://api.youraiconnector.com/v1/channels/instagram-login/token?apiKey=YOUR_AGENCY_KEY&sub_account_id=CLIENT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "ig_user_id": "17841400000000000",
    "access_token": "IGAAR…",
    "expires_at": "2026-11-01T00:00:00Z"
  }'

Respons

{
  "success": true,
  "ig_user_id": "17841400000000000",
  "username": "acme.studio",
  "expires_at": "2026-11-01T00:00:00.000Z",
  "webhook_url": "https://api.youraiconnector.com/v1/incoming-instagram-login-message/byo/YOUR_ACCOUNT_ID"
}

Sebagai bagian dari proses push, kami melanggan aplikasi Anda ke webhook akun tersebut (subscribed_apps dengan token yang dikirimkan), sehingga pesan mulai mengalir tanpa panggilan tambahan di pihak Anda.

Penyegaran - kirim token yang disegarkan ke titik akhir yang sama dengan ig_user_id yang sama; ini memperbarui token dan masa berlaku yang tersimpan di tempat.

Konflik - satu akun Instagram tidak pernah aktif di dua koneksi. Jika akun tersebut sudah terhubung di tempat lain, atau pada akun ini melalui alur Halaman Facebook, push akan mengembalikan 409 yang memberi tahu Anda koneksi mana yang harus diputuskan terlebih dahulu. Koneksi alur Facebook tidak pernah diganti secara otomatis, karena koneksi tersebut mungkin juga melayani Messenger.

Langkah 3 - Putuskan koneksi saat klien keluar #

DELETE /channels/instagram-login/token (autentikasi dan sub_account_id yang sama) berhenti berlangganan webhook dengan upaya terbaik dan menghapus kredensial yang tersimpan. Ini selalu berhasil, bahkan ketika token sudah kedaluwarsa — dan setelah kredensial hilang, peristiwa webhook akun tersebut akan diabaikan.

Tips untuk membangun wrapper yang andal #

• Lakukan polling dengan hati-hati. Setiap beberapa detik sudah cukup. Berhentilah setelah Anda mencapai status terminal (connected / ONLINE, atau status kegagalan), dan tetapkan batas waktu keseluruhan yang masuk akal pada loop (langkah browser/QR akan kedaluwarsa, lihat masing-masing expires_at).
• URL-encode nomor telepon di path. Awalan + harus dikirim sebagai %2B. Endpoint juga dapat memulihkan digit mentah, tetapi encoding adalah default yang aman.
• Jangan pernah mengharapkan rahasia dikembalikan. Token akses, rahasia saluran, dan token halaman diterima atau disimpan tetapi tidak pernah dikembalikan dalam respons apa pun.
• Tangani gerbang otentikasi. 403 berarti akses API tidak ada dalam paket, atau saluran yang Anda hubungkan tidak termasuk dalam paket akun. Lihat Akses API.
• Perhatikan batas kecepatan. Permintaan terautentikasi dibatasi hingga 300 per menit; 429 berarti berhenti sejenak dan coba lagi. Lihat Otentikasi.

Langkah berikutnya #

• Otentikasi - empat bentuk otentikasi yang diterima dan format kesalahan.
• Akses API - membuat dan mengelola kunci API Anda.