Wysyłanie do grupy WhatsApp

Wysyłka grupowa to zwykłe żądanie POST /v1/whatsapp/messages, w którym to wskazuje grupę zamiast osoby: jedno żądanie, jedna wiadomość, a każdy uczestnik tego czatu grupowego ją otrzymuje i może odpowiedzieć tak, że pozostali to widzą. Zmienia się raportowanie. Wiadomość zawiera liczniki pokazujące, ilu uczestników ją otrzymało, a dostarczenie jest potwierdzane osobno dla każdego uczestnika.

Tworzenie grupy i zarządzanie nią to osobne działania od wysyłania do niej wiadomości. Zarządzanie grupami WhatsApp opisuje tworzenie grupy przez API i udostępnianie linku z zaproszeniem, a Grupy WhatsApp opisuje, do czego służy grupa i jakie limity nakłada WhatsApp.

Wymagania wstępne

Potrzebujesz klucza API z uprawnieniem do zapisu WhatsApp oraz ID grupy w stanie Active (wag_…). Skopiuj je z karty Details grupy na stronie Groups, odczytaj z to.group_id wiadomości odebranej przez grupę albo wyświetl listę swoich grup.

Zastąp przykładowe ID grupy własnym. Zainicjalizuj klienta dla swojego języka zgodnie z przewodnikiem SDK dla TypeScript, Python, Go lub PHP. Dla przykładów CLI zainstaluj i uwierzytelnij CLI z dostępem do zapisu WhatsApp. W żądaniach cURL użyj hosta API odpowiedniego dla regionu obszaru roboczego.

1. Wyślij wiadomość

Umieść ID grupy w to i pomiń from. Grupa jest powiązana z numerem firmowym, z którym została utworzona, więc tylko z tego numeru wiadomość może zostać wysłana; podanie nadawcy zwraca 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 zwraca 202 z grupą na to.group_id, status: accepted i recipient_count: liczbę osób w grupie w momencie przyjęcia wysyłki. Ta liczba jest mianownikiem dla wszystkiego w kroku 3 i jest ustalona w tym momencie. Osoba, która dołączy przez link z zaproszeniem, gdy wiadomość jest w trakcie dostarczania, nie otrzyma jej i nie zmieni tej liczby.

2. Co grupa przyjmuje

Grupa przyjmuje tekst, obrazy, wideo, audio, naklejki, dokumenty, lokalizację, wizytówki kontaktów oraz szablon stworzony w Twoim obszarze roboczym w dowolnej kategorii poza uwierzytelnianiem. Dwa rodzaje treści są odrzucane z 422 E15052, zanim wiadomość zostanie utworzona lub naliczona opłata, ponieważ WhatsApp nie dostarcza żadnego z nich do czatu grupowego:

• Treści interaktywne: przyciski odpowiedzi, menu list, przyciski z linkiem, karuzele oraz żądania lokalizacji i danych kontaktowych.
• Szablon uwierzytelniania. Zamiast tego wyślij jednorazowy kod weryfikacyjny bezpośrednio do uczestnika.

Szablon zarządzany przez Bird jest wysyłany z numeru należącego do Bird, który nigdy nie jest numerem powiązanym z grupą, więc zaadresowanie go do grupy zwraca 422 E15001.

Treść w formie swobodnej nadal wymaga otwartego okna obsługi klienta, a grupa ma własne: wiadomość dowolnego uczestnika wysłana do grupy otwiera jedno 24-godzinne okno dla całej grupy, a wiadomość tej samej osoby wysłana do Ciebie poza grupą nie otwiera go. Gdy okno wygaśnie, do grupy dotrze tylko szablon.

3. Śledź rozsyłanie

Pobierz wiadomość, aby sprawdzić, jak daleko dotarła. Trzy liczniki raportują rozsyłanie:

W wiadomości grupowej status raportuje najdalszy punkt, do którego dotarł każdy odbiorca: zmienia się na delivered dopiero gdy delivered_count zrówna się z recipient_count, a pozostaje sent, gdy część potwierdziła, a część nie. Żadna wiadomość WhatsApp nie ma statusu read, więc odczytanie jest śledzone przez read_count i read_at. delivered_at i read_at odnoszą się do pierwszego odbiorcy, nie ostatniego. failed i rejected nigdy nie są per uczestnik, ponieważ jest jedno przekazanie do WhatsApp i jeden sposób, w jaki może zostać odrzucone.

Wysyłka do grupy, do której nikt jeszcze nie dołączył, nie zawiera żadnych liczników, bo nie ma mianownika do zaraportowania. Traktuj to.group_id, a nie liczniki, jako to, co odróżnia wiadomość grupową od wiadomości jeden-do-jednego.

Aby sprawdzić, którego uczestnika dotyczy potwierdzenie, wyświetl zdarzenia wiadomości. Wysyłka grupowa rozdziela się na co najwyżej jedno zdarzenie whatsapp.delivered i co najwyżej jedno zdarzenie whatsapp.read na uczestnika, każde z polem recipient zawierającym numer telefonu tej osoby, jej identyfikator użytkownika w zakresie firmy lub oba. Żadne z nich nie jest gwarantowane: WhatsApp pomija potwierdzenie dostarczenia dla uczestnika, który już przegląda czat, a odczyt pojawia się tylko wtedy, gdy otworzy wiadomość. Zliczaj to, co przychodzi, zamiast czekać na jedno zdarzenie każdego typu na uczestnika, a sumy odczytuj z liczników. Pojedyncze zdarzenie whatsapp.sent nie zawiera pola recipient: to jest jedno przekazanie do WhatsApp, które nie wskazuje nikogo. Webhooki whatsapp.delivered i whatsapp.read zawierają to samo pole, dzięki któremu odróżnisz identycznie wyglądające callbacki.

4. Odczytaj konwersację jednej grupy

Przekaż group_id do listowania wiadomości, aby uzyskać wątek jednej grupy w obu kierunkach:

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"

Przychodząca wiadomość grupowa jest odczytywana z uczestnikiem, który ją napisał, w from i z to, który zawiera zarówno Twój numer firmowy, jak i group_id: numer, który ją odebrał, kwalifikowany przez grupę, przez którą przyszła. Ani to, ani from nie pasuje do grupy, więc group_id jest jedynym filtrem zawężającym listę do jednej grupy. Te same wiadomości są w logu WhatsApp w dashboardzie.

Koszt

Wysyłka grupowa jest rozliczana w dwóch składnikach opisanych w Wysyłanie wiadomości WhatsApp, z jedną różnicą w wycenie każdego z nich. Opłata Bird jest naliczana raz za wysyłkę i wyceniana na podstawie kraju numeru firmowego, z którego wiadomość wyszła, ponieważ grupa może obejmować kilka krajów i nie ma jednego kraju odbiorcy. Udział Meta nalicza się na uczestnika, do którego wiadomość dotarła, każdy wyceniany według zwykłej stawki jeden-do-jednego dla kraju tego uczestnika, więc passthrough_amount rośnie w miarę napływania potwierdzeń. Od 1 października 2026 ten udział obejmuje też treść w formie swobodnej wysłaną do grupy, którą Meta nalicza na uczestnika, do którego dotarła, i odlicza z puli 1000 darmowych wiadomości serwisowych miesięcznie przypisanych do numeru wysyłającego: Zmiany cenowe od października 2026.

Rozwiązywanie problemów

• 404 (E15046): ID grupy nie wskazuje żadnej grupy w tym obszarze roboczym. Grupa należy do obszaru roboczego, który ją utworzył, więc ID z innego obszaru roboczego nie zostanie tu znalezione.
• 409 (E15047): Grupa jest w stanie oczekiwania, zawieszona, usunięta lub w stanie błędu. Wiadomość można wysłać tylko do grupy w stanie Active, a grupa pozostaje w stanie oczekiwania, dopóki WhatsApp jej nie potwierdzi.
• 422 (E15018): Usuń from. Grupa wysyła z numeru, z którym została utworzona.
• 422 (E15052): Treść interaktywna lub szablon uwierzytelniania. Zobacz co grupa przyjmuje.
• 422 (E15044): Okno obsługi grupy jest zamknięte. Wyślij szablon lub poczekaj, aż uczestnik napisze do grupy.
• status utknął na sent: Mniej niż recipient_count uczestników potwierdziło dostarczenie. Odczytaj zdarzenia wiadomości, aby sprawdzić, kto nie potwierdził.

Następne kroki

• Odbieranie wiadomości grupowych WhatsApp: identyfikuj nadawcę i odpowiadaj do grupy
• Zarządzanie grupami WhatsApp: zarządzaj uczestnikami, linkami z zaproszeniami i prośbami o dołączenie
• Webhooki statusu wiadomości: otrzymuj aktualizacje dostarczenia swoich wiadomości
• Identyfikatory użytkowników w zakresie firmy: identyfikuj uczestnika, którego numeru telefonu nie masz