Menu a lista WhatsApp

GitHub

Un menu a lista si presenta come un pulsante toccabile sotto un messaggio WhatsApp e si espande in righe raggruppate per sezioni, così il destinatario sceglie da un insieme più ampio di opzioni invece di digitare testo libero. Usalo quando le scelte sono più di tre; per tre o meno, i pulsanti di risposta sono la forma più semplice.

Imposta interactive.type a list, con un body_text e un oggetto list contenente button_text e almeno una sezione:

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 è obbligatorio in ogni messaggio di servizio: un numero di proprietà del tuo spazio di lavoro, non uno gestito da Bird. La forma completa aggiunge un'intestazione di testo opzionale, un piè di pagina, la citazione di un messaggio precedente, una seconda sezione e una descrizione di riga:

Esempio di codice

{
  "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 cita un messaggio precedente nella stessa conversazione. Consulta nella guida centrale citare un messaggio per correlare una risposta per capire come funziona la risoluzione e cosa può perdere.

Un menu a lista usa list.sections invece dell'oggetto pulsante condiviso; consulta la sezione pulsanti della guida centrale per capire come gli altri tipi usano quella forma.

Sezioni e righe

list.button_text è l'etichetta sul pulsante che apre il menu, fino a 20 caratteri. Toccandolo si apre il menu: ogni sezione appare sotto il proprio title, e ogni riga in una sezione mostra la propria etichetta text con l'opzionale description sotto, in carattere più piccolo. Il title di una sezione è obbligatorio anche quando il menu ha una sola sezione, perché WhatsApp lo mostra sopra le righe di quella sezione in ogni caso.

Il slug di una riga è il tuo identificativo per quella riga, mai mostrato al destinatario. Solo text appare nella chat, e il slug viene restituito esattamente nella risposta, lo stesso ciclo di andata e ritorno descritto nella guida centrale per i pulsanti. Nessuna validazione viene fatta sui caratteri di slug: inserisci quello che serve al tuo routing.

Limiti

Campo	Limite
Sezioni per messaggio	Da 1 a 10
Righe per sezione	Da 1 a 10
Righe in tutte le sezioni	10, totale
`title` della sezione	obbligatorio, da 1 a 24 caratteri
`slug` della riga	obbligatorio, da 1 a 200 caratteri, qualsiasi carattere
`text` della riga (etichetta)	obbligatorio, da 1 a 24 caratteri, univoco nell'intero messaggio
`description` della riga	opzionale, fino a 72 caratteri
`list.button_text`	obbligatorio, da 1 a 20 caratteri
`body_text`	obbligatorio, da 1 a 4096 caratteri
`footer_text`	opzionale, fino a 60 caratteri
`header.text`	Da 1 a 60 caratteri

Due di questi limiti sono facili da fraintendere.

Il tetto di righe è dieci in tutte le sezioni, non dieci per sezione. Ogni sezione consente fino a 10 righe indipendentemente, ma il messaggio nel suo insieme non supera mai le 10 righe totali. Tre sezioni da 4 righe ciascuna passano ogni controllo per sezione ma superano il totale, che viene applicato separatamente dal conteggio per sezione e restituisce E15055 con un messaggio che indica quante righe l'invio conteneva effettivamente.

body_text è l'unico che mantiene i 4096 caratteri completi. Ogni altro tipo interattivo riduce il corpo a 1024; un menu a lista è l'unico che WhatsApp consente di usare per l'intera lunghezza, quindi sceglilo quando la scelta ha bisogno di più contesto di un breve prompt.

Leggere la scelta

Il tocco su una riga arriva come messaggio in ingresso a sé stante, contenente interactive_reply:

Esempio di codice

{
  "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"
}

Il slug impostato sulla riga scelta torna esattamente, così puoi usarlo direttamente per il branching. description è presente solo quando la riga ne conteneva uno. Questa risposta è visibile nella lista messaggi o tramite GET /v1/whatsapp/messages/{id}; consulta nella guida centrale leggere una risposta per il percorso completo.

Limiti e casi limite

La finestra di assistenza clienti deve essere aperta. Un menu a lista è un messaggio di servizio, recapitabile solo all'interno di una finestra aperta; consulta la finestra di assistenza clienti nella guida centrale. Il controllo della finestra fallisce in modo permissivo, quindi un 202 non è prova che la finestra fosse effettivamente aperta al momento dell'invio.
from deve essere un numero di proprietà del tuo spazio di lavoro. Ometterlo, o indicare un numero che non è un mittente connesso, viene rifiutato prima che l'invio venga creato.
L'intestazione è solo testo, e un'intestazione multimediale fallisce con un errore generico. Un menu a lista è l'unico tipo interattivo la cui intestazione non può contenere un'immagine, un video o un documento. Inviarne uno comunque non restituisce un codice di errore specifico di WhatsApp: fallisce la validazione generale della richiesta, quindi uno sviluppatore che cerca per codice di errore vede solo che la richiesta non ha superato la validazione e deve leggere i dettagli per trovare l'intestazione.
Il tetto di righe tra le sezioni è la trappola. I limiti per sezione e il totale del messaggio hanno entrambi un massimo di 10, quindi sembrano lo stesso numero ripetuto due volte. Non sono cumulativi: un menu che supera ogni controllo per sezione può comunque eccedere il totale, e solo il totale viene effettivamente applicato.
Le etichette delle righe devono essere univoche nell'intero messaggio, non solo all'interno di una sezione. Due righe con la stessa etichetta text, anche in sezioni diverse, vengono rifiutate con E15056. Questa è una regola di Bird, non una dichiarata da Meta: la risposta riporta l'etichetta toccata, quindi un duplicato renderebbe la risposta ambigua, e valori slug distinti sottostanti non aiutano a risolverla.
Un rifiuto lato Meta oltre i controlli di Bird è vago e può arrivare in ritardo. I controlli di Bird sul conteggio delle righe e sulle etichette duplicate intercettano i due errori più comuni prima che qualsiasi cosa venga creata. Tutto ciò che Meta rifiuta oltre a questo emerge dopo il 202, nello last_error del messaggio, anziché nella chiamata di invio stessa.

Una citazione che non si risolve fa fallire la richiesta prima che qualsiasi cosa venga creata o addebitata: 404 E15071 quando l'id non corrisponde a nessun messaggio presente in questo spazio di lavoro, 422 E15072 quando indica un messaggio che non può essere citato. Per gli errori che qualsiasi invio WhatsApp può incontrare, come una finestra chiusa, un mittente mancante o non valido, o un destinatario non valido, consulta nella guida centrale errori e Invio di messaggi WhatsApp.

Passaggi successivi

Messaggi interattivi WhatsApp: cosa condividono tutti e sei i tipi interattivi
Pulsanti di risposta: per tre o meno scelte
Invio di messaggi WhatsApp: la struttura della richiesta, il modello 202 e i tentativi sicuri

Continua con la documentazione, le guide e gli esempi per questo argomento.

Prova l'esercitazione e ottieni un brief di implementazione

Inviare un menu a lista

Sezioni e righe

Limiti

Leggere la scelta

Limiti e casi limite

Passaggi successivi

Risorse correlate