List menu WhatsApp

GitHub

List menu muncul sebagai tombol yang bisa diketuk di bawah pesan WhatsApp dan terbuka menjadi baris-baris yang dikelompokkan ke dalam section, sehingga penerima memilih satu dari sekumpulan pilihan yang lebih panjang alih-alih mengetik teks bebas. Gunakan list menu jika pilihan lebih dari tiga; untuk tiga atau kurang, reply button adalah bentuk yang lebih sederhana.

Atur interactive.type ke list, dengan body_text dan objek list yang memuat button_text serta minimal satu section:

const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "list",
    body_text: "Which shipping option do you prefer?",
    list: {
      button_text: "Shipping options",
      sections: [
        {
          title: "As soon as possible",
          rows: [{ slug: "priority_express", text: "Priority Mail Express" }],
        },
      ],
    },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+16505551234",
    from_="+13124495648",
    interactive={
        "type": "list",
        "body_text": "Which shipping option do you prefer?",
        "list": {
            "button_text": "Shipping options",
            "sections": [
                {
                    "title": "As soon as possible",
                    "rows": [{"slug": "priority_express", "text": "Priority Mail Express"}],
                }
            ],
        },
    },
)
print(msg.id, msg.status)

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
	if err != nil {
		log.Fatal(err)
	}
	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:   "+16505551234",
		From: "+13124495648",
		Interactive: &bird.WhatsAppInteractiveSend{
			Type:     "list",
			BodyText: "Which shipping option do you prefer?",
			List: &bird.WhatsAppInteractiveListSend{
				ButtonText: "Shipping options",
				Sections: []bird.WhatsAppInteractiveListSectionSend{
					{
						Title: "As soon as possible",
						Rows: []bird.WhatsAppInteractiveListRowSend{
							{Slug: "priority_express", Text: "Priority Mail Express"},
						},
					},
				},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

$interactive = (new WhatsAppMessageSendRequestInteractive())
    ->setType('list')
    ->setBodyText('Which shipping option do you prefer?')
    ->setList(
        (new WhatsAppInteractiveSendList())
            ->setButtonText('Shipping options')
            ->setSections([
                (new WhatsAppInteractiveListSectionSend())
                    ->setTitle('As soon as possible')
                    ->setRows([
                        (new WhatsAppInteractiveListRowSend())
                            ->setSlug('priority_express')
                            ->setText('Priority Mail Express'),
                    ]),
            ]),
    );

$message = $bird->whatsapp->send(
    to: '+16505551234',
    from: '+13124495648',
    interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --from +13124495648 \
  --interactive '{"body_text":"Which shipping option do you prefer?","list":{"button_text":"Shipping options","sections":[{"rows":[{"slug":"priority_express","text":"Priority Mail Express"}],"title":"As soon as possible"}]},"type":"list"}' \
  --to +16505551234

curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+16505551234",
    "from": "+13124495648",
    "interactive": {
      "type": "list",
      "body_text": "Which shipping option do you prefer?",
      "list": {
        "button_text": "Shipping options",
        "sections": [
          {
            "title": "As soon as possible",
            "rows": [{ "slug": "priority_express", "text": "Priority Mail Express" }]
          }
        ]
      }
    }
  }'

from wajib ada di setiap service message: nomor milik workspace Anda, bukan nomor yang dikelola Bird. Bentuk lengkapnya menambahkan header teks opsional, footer, kutipan pesan sebelumnya, section kedua, dan deskripsi baris:

Contoh kode

{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Choose a shipping option" },
    "body_text": "Which shipping option do you prefer?",
    "footer_text": "Lucky Shrub",
    "list": {
      "button_text": "Shipping options",
      "sections": [
        {
          "title": "As soon as possible",
          "rows": [
            {
              "slug": "priority_express",
              "text": "Priority Mail Express",
              "description": "Next day to 2 days"
            }
          ]
        },
        {
          "title": "I can wait a bit",
          "rows": [
            {
              "slug": "ground_advantage",
              "text": "Ground Advantage",
              "description": "2 to 5 days"
            }
          ]
        }
      ]
    }
  },
  "tags": [{ "name": "flow", "value": "shipping-choice" }],
  "metadata": { "order_id": "A1B2C3" }
}

in_reply_to_message_id mengutip pesan sebelumnya dalam percakapan yang sama. Lihat bagian hub mengutip pesan untuk mengorelasikan balasan untuk cara resolusi bekerja dan apa yang bisa terlewat.

List menu menggunakan list.sections alih-alih objek button bersama; lihat bagian buttons di hub untuk cara tipe lain menggunakan bentuk tersebut.

Section dan baris

list.button_text adalah label pada tombol yang membuka menu, maksimal 20 karakter. Mengetuknya membuka menu: setiap section ditampilkan di bawah title-nya sendiri, dan setiap baris dalam section menampilkan label text dengan description opsional di bawahnya, dalam huruf lebih kecil. title section wajib diisi meskipun menu hanya memiliki satu section, karena WhatsApp tetap menampilkannya di atas baris-baris section tersebut.

slug pada baris adalah handle Anda sendiri untuk baris itu, tidak pernah ditampilkan ke penerima. Hanya text yang ditampilkan di chat, dan slug dikembalikan persis sama pada balasan, round trip yang sama seperti yang dijelaskan hub untuk button. Tidak ada validasi karakter di slug: isi apa pun yang dibutuhkan routing Anda di sana.

Batas

Field	Batas
Section per pesan	1 sampai 10
Baris per section	1 sampai 10
Baris di semua section	10, total
`title` section	wajib, 1 sampai 24 karakter
`slug` baris	wajib, 1 sampai 200 karakter, karakter apa pun
`text` baris (label)	wajib, 1 sampai 24 karakter, unik di seluruh pesan
`description` baris	opsional, maksimal 72 karakter
`list.button_text`	wajib, 1 sampai 20 karakter
`body_text`	wajib, 1 sampai 4096 karakter
`footer_text`	opsional, maksimal 60 karakter
`header.text`	1 sampai 60 karakter

Dua dari batas ini mudah salah baca.

Batas baris adalah sepuluh di seluruh section, bukan sepuluh per section. Setiap section secara independen memperbolehkan hingga 10 baris, tetapi pesan secara keseluruhan tetap maksimal 10 baris total. Tiga section masing-masing 4 baris lolos setiap pemeriksaan per-section namun tetap melebihi total, yang diterapkan terpisah dari hitungan per-section dan mengembalikan E15055 dengan pesan yang menyebutkan berapa baris yang sebenarnya dikirim.

body_text adalah satu-satunya yang mempertahankan 4096 karakter penuh. Setiap tipe interaktif lain mempersempit body-nya menjadi 1024; list menu adalah satu-satunya yang diizinkan WhatsApp menggunakan panjang penuh, jadi gunakan list menu ketika pilihan membutuhkan konteks lebih dari sekadar prompt singkat.

Membaca pilihan

Ketukan baris tiba sebagai pesan masuk tersendiri, membawa interactive_reply:

Contoh kode

{
  "id": "wam_01kyb2m4xq7whs0d8n3prv6tez",
  "direction": "inbound",
  "from": { "phone_number": "+16505551234" },
  "to": { "phone_number": "+13124495648" },
  "status": "received",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive_reply": {
    "type": "list",
    "list": {
      "slug": "priority_express",
      "text": "Priority Mail Express",
      "description": "Next day to 2 days"
    }
  },
  "created_at": "2026-08-25T09:04:11Z"
}

slug yang Anda atur pada baris yang dipilih dikembalikan persis sama, sehingga Anda bisa langsung melakukan branching berdasarkan nilainya. description hadir hanya jika baris tersebut memilikinya. Anda melihat balasan ini melalui daftar pesan atau GET /v1/whatsapp/messages/{id}; lihat bagian hub membaca balasan untuk alur lengkapnya.

Batas dan kasus khusus

Customer service window harus terbuka. List menu adalah service message, hanya dapat dikirim di dalam window yang terbuka; lihat bagian hub customer service window. Pemeriksaan window bersifat fail-open, sehingga 202 bukan bukti bahwa window benar-benar terbuka saat pengiriman dilakukan.
from harus berupa nomor milik workspace Anda. Mengosongkannya, atau menyebutkan nomor yang bukan sender terhubung, akan ditolak sebelum pengiriman dibuat.
Header hanya berupa teks, dan header media gagal sebagai error generik. List adalah satu-satunya tipe interaktif yang header-nya tidak bisa membawa gambar, video, atau dokumen. Mengirimnya tetap tidak mengembalikan kode error spesifik WhatsApp: permintaan gagal pada validasi umum, sehingga developer yang men-debug berdasarkan kode error hanya melihat bahwa validasi permintaan gagal dan harus membaca detailnya untuk menemukan masalah header.
Batas baris lintas section adalah jebakan. Batas per-section dan total seluruh pesan sama-sama maksimal 10, sehingga terlihat seperti angka yang sama ditulis dua kali. Keduanya tidak bersifat aditif: menu yang lolos setiap pemeriksaan per-section tetap bisa melebihi total, dan hanya total-lah yang diterapkan.
Label baris harus unik di seluruh pesan, bukan hanya dalam satu section. Dua baris dengan label text yang sama, meskipun di section berbeda, ditolak dengan E15056. Ini adalah aturan Bird sendiri, bukan aturan yang dinyatakan Meta: balasan menyebutkan label yang diketuk, sehingga duplikat membuat jawaban ambigu, dan nilai slug yang berbeda di bawahnya tidak membantu menyelesaikannya.
Penolakan dari sisi Meta di luar pemeriksaan Bird sendiri bersifat samar dan bisa tiba terlambat. Pemeriksaan jumlah baris dan label duplikat oleh Bird menangkap dua kesalahan paling umum sebelum apa pun dibuat. Apa pun yang ditolak Meta di luar itu muncul setelah 202, pada last_error pesan, bukan pada panggilan pengiriman itu sendiri.

Kutipan yang tidak dapat di-resolve menggagalkan permintaan sebelum apa pun dibuat atau ditagih: 404 E15071 jika id tidak merujuk pesan mana pun di workspace ini, 422 E15072 jika id merujuk pesan yang tidak bisa dikutip. Untuk error yang bisa terjadi pada pengiriman WhatsApp mana pun, seperti window tertutup, sender tidak ada atau tidak valid, atau penerima tidak valid, lihat bagian hub errors dan Mengirim pesan WhatsApp.

Langkah selanjutnya

Pesan interaktif WhatsApp: kesamaan yang dimiliki keenam tipe interaktif
Reply button: untuk tiga pilihan atau kurang
Mengirim pesan WhatsApp: envelope permintaan, model 202, dan coba lagi yang aman

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

Coba praktiknya dan dapatkan ringkasan implementasi

Mengirim list menu

Section dan baris

Batas

Membaca pilihan

Batas dan kasus khusus

Langkah selanjutnya

Sumber daya terkait