Invio a un gruppo WhatsApp

Un invio di gruppo è una normale POST /v1/whatsapp/messages il cui to indica un gruppo invece di una persona: una richiesta, un messaggio, e ogni partecipante di quella chat di gruppo lo riceve e può rispondere dove gli altri lo vedono. Ciò che cambia è il reporting. Il messaggio include contatori che indicano quanti lo hanno ricevuto, e la consegna viene confermata un partecipante alla volta.

Creare e amministrare un gruppo è un'operazione separata dall'invio di messaggi. Gestire i gruppi WhatsApp spiega come crearne uno tramite API e come distribuire il link di invito, mentre Gruppi WhatsApp descrive a cosa serve un gruppo e i limiti che WhatsApp impone.

Prerequisiti

Servono una chiave API con permesso di scrittura WhatsApp e l'ID di un gruppo Active (wag_…). Copialo dalla scheda Details del gruppo nella pagina Groups, leggilo da to.group_id su un messaggio arrivato tramite il gruppo, oppure elenca i tuoi gruppi.

Sostituisci l'ID di gruppo di esempio con il tuo. Inizializza il client per il tuo linguaggio usando la guida SDK per TypeScript, Python, Go o PHP. Per gli esempi CLI, installa e autentica la CLI con accesso in scrittura WhatsApp. Usa l'host API per la tua regione dello spazio di lavoro nelle richieste cURL.

1. Invia il messaggio

Inserisci il group ID in to e ometti from. Un gruppo è associato al numero business con cui è stato creato, quindi quel numero è l'unico da cui il messaggio può uscire; specificare un mittente restituisce una 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." }
    }'

La API restituisce 202 con il gruppo riportato su to.group_id, status: accepted e recipient_count: quante persone erano nel gruppo quando l'invio è stato accettato. Quel conteggio è il denominatore per tutto ciò che segue nello step 3, ed è fissato in quel momento. Chi si unisce tramite il link di invito mentre il messaggio è in transito non lo riceve e non modifica il conteggio.

2. Cosa accetta un gruppo

Un gruppo accetta testo, immagini, video, audio, sticker, documenti, una posizione, schede contatto e un template creato nel tuo spazio di lavoro in qualsiasi categoria tranne autenticazione. Due tipi di contenuto vengono rifiutati con una 422 E15052, prima che il messaggio venga creato o addebitato, perché WhatsApp non consegna nessuno dei due a una chat di gruppo:

• Qualsiasi contenuto interattivo: pulsanti di risposta, menu a lista, pulsanti con link, caroselli e le richieste di posizione e informazioni di contatto.
• Un template di autenticazione. Invia invece il codice di verifica monouso direttamente al partecipante.

Un template gestito da Bird viene inviato da un numero di proprietà di Bird, che non è mai il numero associato al gruppo, quindi indirizzarlo a un gruppo restituisce una 422 E15001.

Il contenuto in formato libero richiede comunque una finestra di servizio clienti aperta, e un gruppo ne ha una propria: qualsiasi partecipante che scrive al gruppo apre un'unica finestra di 24 ore per l'intero gruppo, mentre un messaggio che quella persona ti invia al di fuori del gruppo non la apre. Una volta scaduta la finestra, solo un template può raggiungere il gruppo.

3. Segui il fan-out

Recupera il messaggio per vedere fino a dove è arrivato. Tre contatori riportano il fan-out:

In un messaggio di gruppo, status riporta il punto più avanzato raggiunto da tutti i destinatari: passa a delivered solo quando delivered_count è uguale a recipient_count, e resta sent finché alcuni hanno confermato e altri no. Nessun messaggio WhatsApp ha uno stato read, quindi la lettura è read_count e read_at. delivered_at e read_at sono quelli del primo destinatario, non dell'ultimo. failed e rejected non sono mai per partecipante, perché c'è un solo passaggio a WhatsApp e un solo modo in cui può essere rifiutato.

Un invio a un gruppo a cui nessuno si era ancora unito non include alcun contatore, poiché non c'è un denominatore da riportare, quindi usa to.group_id anziché i contatori per distinguere un messaggio di gruppo da uno one-to-one.

Per vedere a quale partecipante si riferisce una conferma, elenca gli eventi del messaggio. Un invio a un gruppo si distribuisce in al massimo un whatsapp.delivered e al massimo un whatsapp.read per partecipante, ciascuno con recipient contenente il numero di telefono di quella persona, il suo ID utente con ambito business, o entrambi. Nessuno dei due è garantito per chiunque: WhatsApp salta la conferma di consegna per un partecipante che sta già guardando la chat, e una lettura arriva solo se apre il messaggio. Conta ciò che arriva invece di attendere uno di ciascun tipo per partecipante, e leggi i contatori per i totali. Il singolo evento whatsapp.sent non contiene recipient: è l'unico passaggio a WhatsApp, che non nomina nessuno. I webhook whatsapp.delivered e whatsapp.read contengono lo stesso campo, ed è così che distingui callback altrimenti identiche.

4. Leggi la conversazione di un gruppo

Passa group_id a list messages per il thread di un gruppo, in entrambe le direzioni:

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"

Un messaggio di gruppo in entrata viene restituito con il partecipante che lo ha scritto su from, e un to che include sia il tuo numero business sia group_id: il numero che lo ha ricevuto, qualificato dal gruppo attraverso cui è arrivato. Né to né from corrispondono a un gruppo, quindi group_id è l'unico filtro che restringe la lista a un singolo gruppo. Gli stessi messaggi si trovano nel log WhatsApp nella dashboard.

Costo

Un invio di gruppo viene addebitato nelle due componenti descritte in Invio di messaggi WhatsApp, con una differenza nel prezzo di ciascuna. La tariffa di Bird viene addebitata una sola volta per l'invio e calcolata in base al paese del numero business da cui è partito, perché un gruppo può coprire più paesi e non ha un singolo paese destinatario. La quota di Meta matura per ogni partecipante raggiunto dal messaggio, ciascuno tariffato alla normale tariffa one-to-one del proprio paese, quindi passthrough_amount cresce man mano che le ricevute arrivano. Dal 1° ottobre 2026 quella quota copre anche il contenuto in formato libero inviato al gruppo, che Meta addebita per partecipante raggiunto attingendo ai 1.000 messaggi di servizio gratuiti mensili del numero mittente: Modifiche tariffarie di ottobre 2026.

Risoluzione dei problemi

• 404 (E15046): il group ID non corrisponde a nessun gruppo di questo spazio di lavoro. Un gruppo appartiene allo spazio di lavoro che lo ha creato, quindi un ID proveniente da un altro spazio di lavoro non viene trovato qui.
• 409 (E15047): il gruppo è in attesa, sospeso, eliminato o fallito. Solo un gruppo Active può ricevere messaggi, e un gruppo resta in attesa finché WhatsApp non lo conferma.
• 422 (E15018): rimuovi from. Il gruppo invia dal numero con cui è stato creato.
• 422 (E15052): contenuto interattivo o un template di autenticazione. Vedi cosa accetta un gruppo.
• 422 (E15044): la finestra di servizio del gruppo è chiusa. Invia un template, oppure attendi che un partecipante scriva al gruppo.
• status bloccato su sent: meno di recipient_count partecipanti hanno confermato la consegna. Leggi gli eventi del messaggio per vedere chi manca.

Prossimi passi

• Ricezione dei messaggi di gruppo WhatsApp: identificare il mittente e rispondere al gruppo
• Gestione dei gruppi WhatsApp: gestire partecipanti, link di invito e richieste di adesione
• Webhook sullo stato dei messaggi: ricevere aggiornamenti sulla consegna dei propri messaggi
• ID utente con ambito business: identificare un partecipante di cui non si ha il numero di telefono