Cara membiarkan pengguna Anda menghubungkan akun WhatsApp, Instagram dan TikTok ke aplikasi Anda
Untuk membiarkan pengguna Anda menghubungkan akun WhatsApp, Instagram dan TikTok ke aplikasi Anda, buat sesi koneksi dengan Partner API easyCoexistence dan arahkan pengguna ke url yang di-hosting. Di sana mereka menghubungkan nomor WhatsApp melalui Embedded Signup dari Meta, atau masuk ke Instagram, Facebook, TikTok, YouTube, LinkedIn dan saluran lainnya, lalu kembali ke redirect_url Anda dengan id koneksi atau saluran yang baru. Tautan berlaku selama satu jam.
Berapa lama tautan koneksi berlaku; setelah itu sesi terbaca kedaluwarsa dan diperlukan tautan baru.
Sesi koneksi yang boleh terbuka bersamaan untuk satu akun, berdampingan dengan batas 100 sesi baru per jam.
Sesi dibuat, dibuka, terhubung, dibatalkan, atau kedaluwarsa, sebagaimana dilaporkan oleh GET /connect-sessions/:id.
URL callback alternatif terpanjang yang diterima Meta untuk mengarahkan webhook pesan nomor WhatsApp ke tempat lain.
Bagaimana cara kerja tautan koneksi?
Seperti halaman checkout. Backend Anda membuat sesi, antarmuka Anda mengirim pelanggan ke url-nya, pelanggan terhubung di halaman di easycoexistence.com, lalu browser kembali ke redirect_url Anda. Backend Anda kemudian mengonfirmasi hasilnya dan mengambil kredensial koneksi baru, semuanya dengan API key Anda.
Apa saja yang ada dalam permintaan?
Badan JSON yang dikirim ke https://easycoexistence.com/api/v1/connect-sessions, dengan API key Anda sebagai Bearer token. Hanya redirect_url yang wajib:
redirect_url: URL https tempat pelanggan mendarat setelahnya.- channel: whatsapp, sebagai default, atau jaringan sosial yang terbuka untuk akun Anda, dengan nama huruf kecilnya, seperti instagram, tiktok atau youtube.
external_ref: id Anda sendiri untuk pelanggan ini, hingga 200 karakter.partner_name: nama yang ditampilkan halaman yang di-hosting, hingga 80 karakter; secara default nama akun Anda.webhook_urlbersamawebhook_verify_token: hanya untuk nomor, dan selalu bersamaan. Meta mengirim pesan nomor tersebut ke sana sejak saat terhubung.
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"redirect_url": "https://app.example.com/connect/return",
"external_ref": "customer_4821",
"partner_name": "ClinicApp",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"webhook_verify_token": "another-long-random-string"
}'Apa yang dikembalikan?
Respons 201 berisi sesi. Kirim pelanggan ke url, dan simpan id, yang diawali cs_, untuk mencari sesi nanti. expires_at jatuh satu jam setelah pembuatan, dan connection_id atau channel_id terisi setelah pelanggan terhubung, bergantung pada saluran sesi. GET /connect-sessions/:id mengembalikan bentuk yang sama kapan saja.
{
"id": "cs_…",
"url": "https://easycoexistence.com/connect/cs_…",
"channel": "whatsapp",
"status": "created",
"external_ref": "customer_4821",
"connection_id": null,
"channel_id": null,
"token_ready": false,
"redirect_url": "https://app.example.com/connect/return",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"last_error": null,
"expires_at": "2026-10-31T15:00:00.000Z",
"opened_at": null,
"finished_at": null,
"created_at": "2026-10-31T14:00:00.000Z"
}Kesalahan apa saja yang bisa dikembalikan saat membuat sesi?
Setiap kesalahan memiliki badan yang sama, yaitu objek dengan code dan message, dan message menjelaskan apa yang perlu diperbaiki. Pembuatan sesi dapat mengembalikan:
- 400
invalid_jsonatauinvalid_request: badan bukan objek JSON, atau sebuah field gagal validasi, sepertiredirect_urlyang bukan https. - 400
channel_unavailable: saluran tidak terbuka untuk akun ini; message mencantumkan yang tersedia. - 401 unauthorized: API key hilang atau tidak valid.
- 402
billing_required: akun belum memiliki kartu, dan semua yang terhubung melaluinya ditagihkan kepadanya. - 429
cap_reached: sudah ada 50 sesi terbuka; tunggu hingga sebagian selesai atau kedaluwarsa. - 429
rate_limited: lebih dari 100 sesi dalam jam ini; message menyebutkan berapa lama harus menunggu.
Ke mana pelanggan mendarat setelahnya?
Pada redirect_url Anda, dengan hasilnya ditambahkan ke query string. Hasil yang sama ada pada sesi, yang dibaca backend Anda dengan GET /connect-sessions/:id:
- session: id sesi, cs_ diikuti karakter acak.
- status: connected, atau cancelled ketika pelanggan memilih Batal dan kembali.
external_ref: id Anda untuk pelanggan, jika sesi membawanya.connection_id: id nomor baru, untuk /connections.channel_id: id akun sosial baru, untuk /channels.
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…Status apa saja yang bisa dimiliki sebuah sesi?
Lima. GET /connect-sessions/:id melaporkan status saat ini, dengan opened_at, finished_at, dan last_error, yang menjelaskan mengapa percobaan terakhir gagal:
- created: dibuat oleh backend Anda, belum dibuka.
- opened: pelanggan telah memuat halaman yang di-hosting.
- connected: nomor atau akun sosial terhubung, dan id-nya ada pada sesi.
- cancelled: pelanggan keluar melalui Batal dan kembali.
- expired: satu jam habis sebelum sesi selesai.
Berapa lama tautan berlaku?
Satu jam sejak dibuat. Setelah itu halaman yang di-hosting memberi tahu pelanggan bahwa tautan telah kedaluwarsa, dengan tombol kembali ke redirect_url Anda bertanda status=cancelled, dan sesi terbaca expired. Sebuah akun dapat menahan 50 sesi terbuka dan membuat 100 per jam, karena Meta menghitung setiap onboarding pertama terhadap batas tingkat aplikasi yang dibagi oleh semua akun.
Apa fungsi external_ref?
Ini mengaitkan setiap koneksi dengan pelanggan Anda. Nilai yang Anda kirim disimpan pada nomor atau saluran yang dibuat sesi, ditambahkan ke redirect, dan disertakan dalam setiap event status tentangnya, sehingga GET /connections?external_ref=customer_4821 dan GET /channels?external_ref=customer_4821 mencantumkan apa yang telah dihubungkan pelanggan tersebut. Masuk dengan Facebook atau LinkedIn dapat membawa beberapa Page sekaligus: redirect menyebut yang pertama, dan filter mencantumkan sisanya. Gunakan id yang stabil dari basis data Anda sendiri, bukan email yang bisa berubah.
Bagaimana jika pelanggan membatalkan atau masuk gagal?
Bergantung di mana kejadiannya, dan sesi menyimpan catatannya:
- Popup Meta gagal atau ditutup: pelanggan menekan Connect lagi di halaman yang sama selama tautan masih terbuka.
- Masuk sosial dibatalkan atau ditolak: pelanggan kembali ke halaman yang di-hosting beserta alasannya dan dapat mencoba lagi hingga tautan kedaluwarsa.
- Akun sudah terhubung melalui akun easyCoexistence lain:
last_errormenyatakannya, dan pelanggan masuk dengan akun yang berbeda. - Pelanggan memilih Batal dan kembali:
redirect_urlAnda menerima status=cancelled dan sesi ditutup, jadi buat sesi baru untuk mencoba lagi. - Tautan kedaluwarsa: buat sesi baru.
Bagaimana jika nomor terhubung tanpa token pelanggan?
Meta kadang menyelesaikan Embedded Signup tanpa menerbitkan token bisnis milik pelanggan. Halaman yang di-hosting kemudian meminta satu kali lagi, yang memakan beberapa detik. Jika pelanggan melewatkannya, sesi terbaca connected dengan token_ready false dan URL event Anda menerima connection.token_missing: nomor tersebut menerima pesan, karena id-nya valid, tetapi tidak dapat mengirim hingga sesi koneksi baru menghubungkannya kembali dan menerbitkan token.
Bagaimana jika webhook_url gagal pemeriksaan Meta?
Nomor tetap terhubung. Meta memeriksa webhook_url dengan jabat tangan GET, yang dilewati endpoint Anda dengan mengembalikan hub.challenge ketika hub.verify_token cocok. Jika gagal, last_error pada sesi diawali dengan webhook_url was not applied dan memuat alasan dari Meta, dan PUT /connections/:id/webhook menetapkan tujuan setelah endpoint merespons. Jika diatur dalam 24 jam setelah terhubung, nomor tersebut tetap menerima impor satu kali atas kontak dan, jika pelanggan setuju untuk membagikannya, riwayat chat.
Apa yang dilihat pelanggan?
Halaman di easycoexistence.com dengan nama Anda dari partner_name, dan tidak ada akun, email, atau kartu yang perlu diisi. Untuk nomor WhatsApp, halaman menampilkan daftar periksa kelayakan singkat, lalu popup Meta dan kode QR untuk dipindai dengan aplikasi WhatsApp Business. Untuk akun sosial, halaman menampilkan satu tombol, seperti Continue with TikTok, yang membuka layar persetujuan jaringan itu di tab yang sama, sehingga juga berfungsi di ponsel.
Kesalahan umum
- Hanya mempercayai query string. Siapa pun dapat mengetik status=connected ke dalam URL, jadi konfirmasi dengan GET /connect-sessions/:id dari backend Anda sebelum menandai pelanggan sebagai terhubung.
- Menanamkan tautan dalam iframe. Kirim pelanggan ke sana dengan redirect atau tab baru, karena begitulah halaman yang di-hosting dan masuk yang dibukanya dimaksudkan untuk berjalan.
- Membuat tautan di muka. Setiap tautan berlaku selama satu jam dan setiap tautan yang terbuka dihitung terhadap batas 50, jadi buat sesi ketika pelanggan hendak terhubung.
- Mengirim webhook_url lebih dari 200 karakter. Meta menerima URL callback alternatif hingga 200 karakter, sehingga yang lebih panjang tidak diterapkan dan nomor terhubung tanpanya.
easyCoexistence menghubungkan nomor WhatsApp pelanggan Anda serta akun Instagram, Facebook, TikTok, YouTube dan LinkedIn mereka, dan saluran lainnya, ke perangkat lunak Anda melalui satu tautan yang di-hosting, lalu memberikan backend Anda kredensial, webhook, dan event status bertanda tangan untuk setiap koneksi. US$ 9 hingga US$ 0,75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Bisakah satu tautan koneksi digunakan dua kali?
Tidak. Tautan selesai dengan satu nomor, atau dengan satu masuk sosial, yang di Facebook atau LinkedIn dapat membawa beberapa Page. Setelah itu tautan terbaca connected, jadi buat sesi baru untuk koneksi berikutnya.
Bisakah saya mengirim tautan melalui email atau chat?
Bisa, selama pelanggan membukanya dalam satu jam. ID sesi di URL adalah yang memberi wewenang pada halaman, jadi kirim setiap tautan hanya kepada pelanggan yang dibuatkannya.
Apakah halaman yang di-hosting berfungsi di ponsel?
Masuk sosial berfungsi, karena dibuka di tab yang sama. Nomor WhatsApp paling baik dihubungkan dari komputer: di ponsel, popup Meta terbuka sebagai tab baru, dan ponsel itu sendiri diperlukan untuk memindai kode QR.
Bagaimana saya tahu pelanggan sudah terhubung tanpa polling?
Atur URL event status di dasbor pada Profile, Developers. easyCoexistence kemudian mengirim connection.connected atau channel.connected, bertanda tangan dan membawa external_ref Anda, segera setelah koneksi dibuat.
Lanjut membaca
Hubungkan saluran pertama Anda dalam dua menit.
Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.
- Gratis 3 hari
- Batalkan kapan saja
- Hanya API resmi
- Dipantau 24/7
Diverifikasi pada