Sign inGet Started
Mulai sekarang
Panduan
Referensi API
SDK
CLI
Basis Pengetahuan
Changelog

Mengelola grup WhatsApp

Semua yang dilakukan halaman Groups juga bisa dilakukan oleh dua belas operasi di bawah /v1/whatsapp/groups, sehingga seluruh siklus hidup grup muat dalam kode: buat grup, tunggu WhatsApp mengonfirmasinya, bagikan tautan undangannya, putuskan siapa yang boleh masuk, perbarui detail dan pin-nya, lalu hapus ketika percakapan selesai.

Dua hal membentuk setiap panggilan di halaman ini. Tidak ada yang bisa ditambahkan ke grup, jadi tautan undangan adalah satu-satunya cara masuk, dan mengundang orang dilakukan di luar API. Sebagian besar perubahan diselesaikan di WhatsApp, bukan di respons, jadi panggilan yang menerima perubahan bukan panggilan yang memberi tahu Anda bahwa perubahan itu berhasil; Cara perubahan diselesaikan membahasnya sekali untuk setiap operasi yang berlaku.

Grup WhatsApp membahas fungsi grup dan siklus hidup yang sama di dashboard. Mengirim ke grup WhatsApp membahas cara mengirim pesan ke grup.

Prasyarat

Anda memerlukan kunci API dengan akses whatsapp_management: level read untuk pembacaan di halaman ini, level write untuk yang lainnya. Users, teams, and roles membahas cara memberikannya.

Anda juga memerlukan nomor bisnis yang memegang status Official Business Account, yang WhatsApp wajibkan dari administrator grup dan dibahas di Before you create a group. GET /v1/whatsapp/numbers melaporkannya per nomor sebagai is_official_business_account, jadi baca dari sana alih-alih menemukan dari 412. Flag tersebut sesuai meta_synced_at nomor, jadi nomor yang baru terhubung beberapa menit lalu mungkin belum terbaca kembali.

Inisialisasi klien untuk bahasa Anda menggunakan panduan SDK TypeScript, Python, Go, atau PHP. Untuk contoh CLI, instal dan autentikasi CLI. Contoh cURL menyebut host US; jika kunci Anda diawali bk_eu1_, panggil https://eu1.platform.bird.com. SDK membaca region dari kunci Anda, jadi tidak perlu mengatur host.

1. Buat grup

Pembuatan menyebutkan nomor yang mengelola dan subjek, tanpa siapa pun lagi. Dua pilihan bersifat tetap seumur hidup grup dan tidak bisa diubah setelahnya: nomor, dan join_approval_mode, yang menentukan apakah membuka tautan undangan langsung memasukkan seseorang (auto_approve, default) atau mengajukan permintaan yang Anda putuskan (approval_required).

Note: creating a group needs a business number with Official Business Account status, the blue check mark WhatsApp puts next to a business name in the chat. WhatsApp Official Business Account covers what Meta requires and how to request it.

const group = await bird.whatsapp.groups.create({
  whatsapp_number_id: "wan_01krdgeqcxet5s7t44vh8rt9mg",
  subject: "Norwood Fleet — Tuesday route",
  join_approval_mode: "approval_required",
});
console.log(group.id, group.status); // pending; read it back for the invite link

API mengembalikan 202 dengan grup pada status pending dan tanpa invite_link: WhatsApp menerbitkan tautan setelah mengonfirmasi grup. Subjek dapat berisi hingga 128 karakter dan description opsional hingga 2.048 karakter, dan keduanya ditampilkan kepada siapa pun yang membuka tautan, jadi beri nama grup sesuai tujuannya, bukan sebagai referensi internal.

2. Tunggu WhatsApp mengonfirmasinya

Baca ulang grup sampai status-nya meninggalkan pending. Pembacaan menjawab 200 apa pun statusnya, jadi percabangan berdasarkan status, bukan berdasarkan keberhasilan panggilan.

const group = await bird.whatsapp.groups.get("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(group.status, group.invite_link);

Lima status dapat muncul, dan hanya satu di antaranya yang merupakan grup yang bisa Anda gunakan:

StatusArtinya
pendingWhatsApp belum mengonfirmasi grup. invite_link bernilai null dan tidak ada yang bisa dibagikan
activeGrup sudah ada, tautan undangannya berfungsi, dan grup menerima pesan serta perubahan
suspendedWhatsApp menghentikan aktivitas dalam grup. Hanya WhatsApp yang dapat mencabutnya
deletedGrup sudah tidak ada, tetapi tetap dapat dibaca sehingga referensi tersimpan masih dapat diresolusi
failedWhatsApp menolak pembuatan, dan ini bersifat final

failed adalah jalan keluar lain dari pending, dan last_operation.last_error.description memuat alasan dari WhatsApp. Jangan pernah mencoba ulang pembuatan yang gagal terhadap grup tersebut: buat yang baru, dengan mengubah apa yang menjadi keberatan penolakan.

3. Masukkan orang ke dalam grup

Kirim invite_link grup kepada orang yang ingin Anda masukkan, melalui kanal apa pun yang sudah menjangkau mereka. Tidak ada operasi yang menambahkan peserta, jadi tautan adalah satu-satunya cara masuk dan bergabung adalah keputusan mereka. Tautan ini mengizinkan siapa pun yang memilikinya, jadi perlakukan sebagai kredensial: Grup WhatsApp membahas sejauh mana Anda sebaiknya menyebarkannya.

Pada grup auto_approve, siapa pun yang memiliki tautan langsung masuk dan tidak ada yang perlu diputuskan. Pada grup approval_required, membuka tautan memunculkan permintaan bergabung. Tampilkan daftar yang menunggu, lalu putuskan secara berkelompok hingga 50 sekaligus:

const waiting = [];
for await (const request of bird.whatsapp.groups.joinRequests.list(
  "wag_01krdgeqcxet5s7t44vh8rt9mg",
)) {
  waiting.push(request.id);
}
const result = await bird.whatsapp.groups.joinRequests.approve("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  join_request_ids: waiting.slice(0, 50),
});
console.log(result.decided.length, result.failed.length);

WhatsApp memutuskan setiap permintaan secara terpisah, sehingga satu batch dapat diterapkan sebagian: respons memisahkan decided dari failed, dan setiap kegagalan memuat alasan yang diberikan WhatsApp di error.description. Baca respons, bukan kode status. Penolakan sering terjadi karena orang tersebut belum menerima ketentuan terbaru WhatsApp, yang tidak bisa diperbaiki dengan mencoba ulang.

Menyetujui lebih banyak orang daripada kapasitas grup tidak menolak panggilan: permintaan yang muat diputuskan dan sisanya dikembalikan di failed, masing-masing menyatakan persetujuan akan membuat grup melewati batas pesertanya. Penolakan bekerja dengan cara yang sama, melalui POST /v1/whatsapp/groups/{group_id}/join-requests/batch-reject. Permintaan juga meninggalkan daftar saat orang tersebut membatalkannya sendiri, sehingga ID yang valid sesaat lalu bisa mengembalikan 422 E15051 saat Anda menggunakannya.

Angka 50 adalah batas Bird sendiri untuk satu permintaan, bukan batas WhatsApp, sehingga penolakan massal tidak dibatasi oleh kapasitas grup.

Pantau permintaan masuk saat tiba

Subscribe ke whatsapp.group.join_request_created dan whatsapp.group.join_request_revoked untuk mengetahui saat seseorang meminta bergabung dan saat mereka membatalkannya, alih-alih melakukan polling pada daftar. Permintaan yang diajukan dan dibatalkan di antara dua pembacaan daftar tidak meninggalkan jejak, jadi event ini adalah satu-satunya cara untuk melihatnya. Setiap event membawa join_request.id yang digunakan operasi batch, sehingga Anda dapat langsung memutuskan dari situ. Webhook grup WhatsApp menyediakan kedua payload dan setiap field.

Merotasi tautan undangan

Merotasi menerbitkan tautan baru dan menghentikan semua tautan yang dimiliki grup sebelumnya, sehingga siapa pun yang masih memegang tautan lama tidak dapat bergabung. Rotasi tautan saat tautan sudah tersebar lebih luas dari yang Anda inginkan, atau setelah menghapus seseorang yang tidak ingin Anda terima kembali. Tautan baru dikembalikan langsung pada panggilan itu sendiri, yang menjawab 200:

const link = await bird.whatsapp.groups.inviteLink.rotate("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(link.invite_link); // every earlier link has stopped working

Merotasi bukan cara Anda membaca tautan saat ini. Grup menyimpan invite_link-nya, jadi membaca grup adalah cara membacanya.

CLI tidak pernah meminta konfirmasi, jadi perintah destruktifnya menggunakan --yes sebagai gantinya: merotasi tautan, menghapus peserta, menghapus grup, melepas pin pesan, dan menolak permintaan bergabung semuanya ditolak dengan confirmation_required tanpa parameter tersebut.

Cara perubahan diselesaikan

WhatsApp mengonfirmasi sebagian perubahan dalam balasannya dan sebagian lagi melalui webhook, dan kode status menunjukkan jenis mana yang Anda lihat:

OperasiMenjawabTempat hasil akhir diterima
Create, update, delete202last_operation grup, setelah WhatsApp melapor kembali
Menghapus peserta202last_operation milik peserta tersebut di participants
Menyetujui atau menolak permintaan bergabung202decided dan failed pada respons itu sendiri
Rotate, pin, unpin200Respons, yang merupakan perubahan yang sudah diterapkan

Untuk dua baris pertama, 202 berarti permintaan diterima, bukan diterapkan. last_operation.status bernilai pending hingga WhatsApp melapor kembali, biasanya dalam hitungan detik, lalu berubah menjadi success atau failed, dengan last_error.description membawa alasan jika gagal. Baca ulang grup untuk melihat apa yang diterapkan.

Selagi sebuah operasi berstatus pending, perubahan lain pada hal yang sama mengembalikan 409 E15054. Perubahan tingkat grup berbagi last_operation milik grup, sehingga rename yang belum selesai memblokir delete. Setiap peserta memiliki miliknya sendiri, jadi menghapus beberapa orang sekaligus memberi masing-masing state dan kegagalan sendiri, dan hanya penghapusan pending orang tersebut yang memblokir percobaan berikutnya terhadap mereka.

Dua 409 mengawal operasi tulis dan status diperiksa lebih dulu, sehingga grup yang bukan active mengembalikan E15047 apa pun nilai last_operation-nya. Ini penting untuk grup yang masih dalam proses pembuatan, yang berstatus pending pada kedua hitungan sekaligus.

Setiap operasi tulis juga memerlukan header Idempotency-Key. Idempotency membahas cara coba lagi dengan aman.

Mengubah subjek, deskripsi, atau gambar grup

Update mengubah apa yang dilihat peserta di bagian atas grup. Field yang Anda hilangkan dibiarkan apa adanya; kirim null untuk menghapus deskripsi atau gambar, karena string kosong adalah 422, bukan cara kedua untuk menghapus.

const group = await bird.whatsapp.groups.update("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  subject: "Norwood Fleet — Wednesday route",
});
console.log(group.last_operation?.status); // pending until WhatsApp reports back

WhatsApp menerapkan setiap field secara terpisah, sehingga update dapat diterapkan sebagian: satu field ditolak sementara yang lain diterapkan. Saat operasi selesai, last_operation.results membawa satu entri per field yang dikirim update, yang memungkinkan Anda mencocokkan penolakan dengan input yang menyebabkannya.

profile_picture_url merujuk file di media library workspace Anda, bukan alamat apa pun di internet, dan WhatsApp menerima JPEG persegi berukuran minimal 192 kali 192 piksel dan maksimal 5 MB. Menghapusnya menghapus gambar yang disimpan Bird, tetapi WhatsApp tidak memiliki operasi untuk menurunkan foto grup, sehingga peserta tetap melihat foto saat ini sampai gambar lain menggantikannya. Nomor pengelola dan join_approval_mode ditetapkan saat pembuatan dan tidak dapat diubah di sini.

Menghapus peserta

Penghapusan tidak dapat dibatalkan. WhatsApp memblokir orang yang dihapus agar tidak bergabung kembali ke grup melalui tautan undangan, dan blokir mengikuti orangnya bukan tautannya, sehingga merotasi tautan tidak membuat mereka bisa masuk kembali. Tanpa operasi penambahan yang berpasangan dengan ini, tidak ada yang dapat mengembalikan seseorang ke grup ini setelah mereka keluar, dan menghubungi mereka lagi berarti membuat grup baru dan mengundang mereka ke sana.

Sebutkan orang tersebut menggunakan salah satu identifier yang tercantum di participants grup: bsuid mereka, yang dimiliki semua orang, atau phone_number mereka dalam format E.164, yang ada hanya jika WhatsApp membagikannya. Di URL, percent-encode awalan + sebagai %2B kecuali klien Anda melakukannya secara otomatis.

const group = await bird.whatsapp.groups.participants.remove(
  "wag_01krdgeqcxet5s7t44vh8rt9mg",
  "+15550002222",
);
console.log(group.participants?.length);

Penghapusan peserta berstatus pending pada entri mereka sendiri sampai WhatsApp mengonfirmasinya, dan tidak pernah mencapai success: entri yang menghilang dari participants adalah tanda bahwa penghapusan berhasil. Nilai yang merujuk seseorang yang tidak ada di grup mengembalikan 422 E15050.

Menyematkan pesan

Menyematkan menahan salah satu pesan milik grup di bagian atas chat, sehingga seseorang yang bergabung kemudian tidak perlu menggulir untuk menemukan hal yang terus dirujuk dalam percakapan. Pin berlaku selama duration_days, dari 1 hingga 30, dan default-nya 7.

const pin = await bird.whatsapp.groups.pins.create("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  message_id: "wam_01kya19eknftrs2s6p82asmvnh",
  duration_days: 14,
});
console.log(pin.pinned_until);

Pesan harus merupakan pesan yang dimiliki grup ini: pesan di grup lain, atau pesan satu-ke-satu, mengembalikan 422 E15053. Sebuah grup memiliki batas jumlah pin sekaligus, dan menyematkan melebihi batas itu akan melepas pin tertua alih-alih gagal; menyematkan pesan yang sudah disematkan mengganti kedaluwarsanya. Pin yang saat ini aktif di grup ada pada grup itu sendiri, sebagai pinned_messages.

WhatsApp melepas pin pesan secara otomatis setelah harinya berlalu, jadi lepas pin hanya untuk menurunkannya lebih awal. DELETE /v1/whatsapp/groups/{group_id}/pinned-messages/{message_id} menjawab 200, dan mengulanginya aman: pesan milik grup ini yang tidak disematkan tidak mengubah apa pun dan tetap menjawab 200.

Menghapus grup

Menghapus menghilangkan grup di WhatsApp. Semua peserta kehilangan akses, termasuk bisnis Anda, dan tautan undangan berhenti berfungsi. Ini tidak dapat dibatalkan, dan menjalankan percakapan lagi berarti membuat grup baru dan mengirimkan tautannya.

const group = await bird.whatsapp.groups.delete("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(group.last_operation?.status); // pending until WhatsApp confirms it

Grup tetap dapat dibaca setelahnya pada status deleted, sehingga referensi tersimpan tetap dapat di-resolve alih-alih berubah menjadi 404. Grup failed juga dapat dihapus, dan penghapusan itu tidak menjangkau sistem eksternal: pembuatan tidak pernah menghasilkan grup di WhatsApp, jadi membersihkan baris tersebut adalah urusan internal Bird. Setiap status lain menolak dengan 409 E15047.

Melihat daftar grup Anda

Daftar mengembalikan grup yang dibuat workspace Anda, terbaru lebih dulu, sebagai halaman kursor. Filter berdasarkan nomor pengelola (number, sebagai nomor E.164 atau ID wan_), berdasarkan WhatsApp Business Account yang digunakan untuk mengirim (waba), atau berdasarkan status, dengan mengulang parameter untuk mencocokkan beberapa sekaligus. q mencari substring dalam subjek dan deskripsi, tanpa memperhatikan huruf besar-kecil.

for await (const group of bird.whatsapp.groups.list({ status: ["active"] })) {
  console.log(group.id, group.subject, group.participant_count);
}

Grup yang dihapus tetap ada di daftar dengan status deleted, jadi filter berdasarkan status untuk melihat hanya grup yang masih bisa Anda kirimi pesan.

Pemecahan masalah

  • 412 (E15045): Nomor tersebut tidak memiliki status Official Business Account, sehingga WhatsApp tidak mengizinkannya membuat grup. Keputusan ada di tangan WhatsApp: ajukan status tersebut di WhatsApp Manager pada profil nomor, atau buat grup menggunakan nomor yang sudah memilikinya.
  • 404 (E15046): ID tersebut tidak merujuk grup mana pun yang dimiliki workspace ini. Grup milik workspace yang membuatnya, jadi ID dari workspace lain tidak ditemukan di sini.
  • 409 (E15047): Grup berstatus pending, suspended, deleted, atau failed. Hanya grup aktif yang menerima perubahan. Baca grup untuk melihat statusnya.
  • 409 (E15049): Nomor tersebut sudah mengelola 10.000 grup yang diizinkan WhatsApp. Hapus grup yang percakapannya sudah selesai, atau buat grup ini pada nomor lain.
  • 409 (E15054): Perubahan pada grup atau peserta yang sama masih belum selesai. Baca last_operation dan tunggu hingga selesai.
  • 422 (E15050): Path tidak merujuk siapa pun di grup. Baca participants grup dan gunakan bsuid atau phone_number sebagaimana dilaporkan.
  • 422 (E15051): Salah satu ID permintaan bergabung sudah tidak lagi menunggu keputusan. Tampilkan daftar permintaan lagi dan gunakan ID yang dikembalikan.
  • 422 (E15053): Pesan tersebut milik grup lain atau percakapan satu-ke-satu. to.group_id pesan menunjukkan grup mana yang dapat menyematkannya.
  • Grup pending yang tidak pernah menjadi aktif: Bird berhenti menunggu alih-alih membiarkannya pending, dan memindahkan grup ke failed dengan alasan pada last_operation.last_error. Buat pengganti alih-alih mencoba lagi.

Referensi

Bentuk request dan respons lengkap ada di referensi API: create, list, get, update, delete, rotasi tautan undangan, hapus peserta, list, approve dan reject permintaan bergabung, serta pin dan unpin pesan.

Langkah berikutnya

Sumber daya terkait

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Coba praktiknya dan dapatkan ringkasan implementasi