Mengirim ke grup WhatsApp

Pengiriman grup adalah POST /v1/whatsapp/messages biasa yang to-nya menyebut grup, bukan orang: satu request, satu pesan, dan setiap peserta group chat tersebut menerimanya serta dapat membalas di tempat yang dilihat peserta lain. Yang berubah adalah pelaporannya. Pesan tersebut membawa penghitung berapa banyak peserta yang dijangkau, dan pengiriman dikonfirmasi satu peserta pada satu waktu.

Membuat dan mengelola grup terpisah dari mengirim pesan ke grup. Mengelola grup WhatsApp membahas pembuatan grup melalui API dan membagikan tautan undangannya, dan Grup WhatsApp membahas fungsi grup dan batasan yang diterapkan WhatsApp.

Prasyarat

Anda memerlukan kunci API dengan izin tulis WhatsApp dan ID grup Active (wag_…). Salin dari tab Details di halaman Groups, baca dari to.group_id pada pesan yang masuk melalui grup, atau lihat daftar grup Anda.

Ganti contoh group ID dengan milik Anda. Inisialisasi client untuk bahasa Anda menggunakan panduan SDK TypeScript, Python, Go, atau PHP. Untuk contoh CLI, instal dan autentikasi CLI dengan akses tulis WhatsApp. Gunakan host API untuk region workspace Anda dalam request cURL.

1. Kirim pesan

Masukkan group ID di to dan jangan sertakan from. Grup terikat pada nomor bisnis yang digunakan saat pembuatannya, jadi nomor itu satu-satunya yang bisa mengirim pesan tersebut; menyebut pengirim menghasilkan 422 E15018.

const msg = await bird.whatsapp.send({
  to: "wag_01krdgeqcxet5s7t44vh8rt9mg",
  text: { body: "The route sheet for Tuesday is up." },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="wag_01krdgeqcxet5s7t44vh8rt9mg",
    text={"body": "The route sheet for Tuesday is up."},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:   "wag_01krdgeqcxet5s7t44vh8rt9mg",
	Text: &bird.WhatsAppTextSend{Body: "The route sheet for Tuesday is up."},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$text = (new WhatsAppMessageSendRequestText())
    ->setBody("The route sheet for Tuesday is up.");
$message = $bird->whatsapp->send(
    to: 'wag_01krdgeqcxet5s7t44vh8rt9mg',
    text: $text,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --text 'The route sheet for Tuesday is up.' \
  --to wag_01krdgeqcxet5s7t44vh8rt9mg

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "to": "wag_01krdgeqcxet5s7t44vh8rt9mg",
      "text": { "body": "The route sheet for Tuesday is up." }
    }'

API mengembalikan 202 dengan grup tercantum di to.group_id, status: accepted, dan recipient_count: berapa banyak orang dalam grup saat pengiriman diterima. Jumlah tersebut menjadi penyebut untuk semua hal di langkah 3, dan nilainya tetap pada saat itu. Seseorang yang bergabung melalui tautan undangan sementara pesan sedang dikirim tidak menerimanya dan tidak mengubah jumlah tersebut.

2. Konten yang diterima grup

Grup menerima teks, gambar, video, audio, stiker, dokumen, lokasi, kartu kontak, dan template yang dibuat workspace Anda dalam kategori apa pun kecuali autentikasi. Dua jenis konten ditolak dengan 422 E15052, sebelum pesan dibuat atau dikenakan biaya, karena WhatsApp tidak mengirimkan keduanya ke group chat:

• Apa pun yang interaktif: tombol balas, menu daftar, tombol tautan, carousel, serta permintaan lokasi dan info kontak.
• Template autentikasi. Kirim kode verifikasi sekali pakai langsung ke peserta.

Template yang dikelola Bird dikirim dari nomor milik Bird, yang tidak pernah menjadi nomor tempat grup terikat, sehingga mengirimnya ke grup menghasilkan 422 E15001.

Konten bebas format tetap memerlukan jendela layanan pelanggan yang terbuka, dan grup memiliki jendelanya sendiri: peserta mana pun yang mengirim pesan ke grup membuka satu jendela 24 jam untuk seluruh grup, dan orang tersebut mengirim pesan kepada Anda di luar grup tidak membukanya. Setelah jendela berakhir, template-lah yang menjangkau grup.

3. Ikuti fan-out

Ambil pesan untuk melihat sejauh mana pengirimannya. Tiga penghitung melaporkan fan-out:

Pada pesan grup, status melaporkan titik terjauh yang dicapai setiap penerima: nilainya berubah menjadi delivered hanya setelah delivered_count sama dengan recipient_count, dan tetap sent selama sebagian sudah mengonfirmasi dan sebagian belum. Tidak ada pesan WhatsApp yang memiliki status read, jadi pembacaan dilaporkan melalui read_count dan read_at. delivered_at dan read_at adalah milik penerima pertama, bukan terakhir. failed dan rejected tidak pernah per peserta, karena hanya ada satu serah terima ke WhatsApp dan satu cara penolakan.

Pengiriman ke grup yang belum ada pesertanya tidak membawa penghitung sama sekali, karena tidak ada penyebut untuk dilaporkan, jadi gunakan to.group_id sebagai pembeda pesan grup dari pesan satu-ke-satu, bukan penghitungnya.

Untuk melihat peserta mana yang terkait dengan konfirmasi tertentu, daftar event pesan. Pengiriman grup menghasilkan paling banyak satu whatsapp.delivered dan paling banyak satu whatsapp.read per peserta, masing-masing membawa recipient berisi nomor telepon orang tersebut, user ID cakupan bisnis mereka, atau keduanya. Keduanya tidak dijamin untuk siapa pun: WhatsApp melewatkan tanda terima pengiriman untuk peserta yang sudah melihat chat, dan tanda baca hanya tiba jika mereka membuka pesan. Hitung yang tiba alih-alih menunggu masing-masing satu per peserta, dan baca penghitung untuk totalnya. Event whatsapp.sent tunggal tidak membawa recipient: itu adalah satu-satunya serah terima ke WhatsApp, yang tidak menyebut siapa pun. Webhook whatsapp.delivered dan whatsapp.read membawa field yang sama, dan itulah cara Anda membedakan callback yang tampak identik.

4. Baca percakapan satu grup

Kirim group_id ke daftar pesan untuk thread satu grup, dua arah:

for await (const msg of bird.whatsapp.list({ group_id: "wag_01krdgeqcxet5s7t44vh8rt9mg" })) {
  console.log(msg.id, msg.direction, msg.status);
}

for msg in client.whatsapp.list(group_id="wag_01krdgeqcxet5s7t44vh8rt9mg"):
    print(msg.id, msg.direction, msg.status)

for msg, err := range client.Whatsapp.List(context.Background(), bird.WhatsappListParams{
	GroupID: "wag_01krdgeqcxet5s7t44vh8rt9mg",
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Direction, *msg.Status)
}

foreach ($bird->whatsapp->list(['group_id' => 'wag_01krdgeqcxet5s7t44vh8rt9mg']) as $message) {
    echo $message->getId(), ' ', $message->getDirection(), "\n";
}

bird whatsapp list --group-id wag_01krdgeqcxet5s7t44vh8rt9mg

curl "https://us1.platform.bird.com/v1/whatsapp/messages?group_id=wag_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Pesan grup masuk terbaca dengan peserta penulisnya di from, dan to yang membawa keduanya: nomor bisnis Anda dan group_id, yaitu nomor penerima yang dikualifikasi oleh grup tempat pesan masuk. to maupun from tidak cocok dengan grup, jadi group_id adalah satu-satunya filter yang menyempitkan daftar ke satu grup. Pesan yang sama ada di log WhatsApp di dashboard.

Biaya

Pengiriman grup dikenakan biaya dalam dua komponen yang dijelaskan Mengirim pesan WhatsApp, dengan satu perbedaan pada cara masing-masing dihitung. Biaya Bird dikenakan sekali per pengiriman dan didasarkan pada negara nomor bisnis pengirim, karena grup dapat mencakup beberapa negara dan tidak memiliki satu negara penerima. Bagian Meta bertambah per peserta yang dijangkau pesan, masing-masing dihitung dengan tarif satu-ke-satu biasa untuk negara peserta tersebut, sehingga passthrough_amount bertambah seiring tanda terima mereka tiba. Mulai 1 Oktober 2026, bagian tersebut juga mencakup konten bebas format yang dikirim ke grup, yang dikenakan Meta per peserta yang dijangkau dan diambil dari 1.000 pesan layanan gratis per bulan milik nomor pengirim: Perubahan harga Oktober 2026.

Pemecahan masalah

• 404 (E15046): Group ID tidak merujuk grup mana pun di workspace ini. Grup dimiliki oleh workspace yang membuatnya, jadi ID dari workspace lain tidak ditemukan di sini.
• 409 (E15047): Grup berstatus pending, suspended, deleted, atau failed. Hanya grup Active yang dapat menerima pesan, dan grup tetap pending hingga WhatsApp mengonfirmasinya.
• 422 (E15018): Hapus from. Grup mengirim dari nomor yang digunakan saat pembuatannya.
• 422 (E15052): Konten interaktif, atau template autentikasi. Lihat konten yang diterima grup.
• 422 (E15044): Jendela layanan grup sudah ditutup. Kirim template, atau tunggu peserta menulis ke grup.
• status tertahan di sent: Kurang dari recipient_count peserta yang mengonfirmasi pengiriman. Baca event pesan untuk melihat siapa yang belum.

Langkah berikutnya

• Menerima pesan grup WhatsApp: identifikasi pengirim dan balas ke grup
• Mengelola grup WhatsApp: kelola peserta, tautan undangan, dan permintaan bergabung
• Webhook status pesan: terima pembaruan pengiriman untuk pesan Anda
• ID pengguna cakupan bisnis: identifikasi peserta yang nomor teleponnya tidak Anda miliki