Zarządzanie grupami WhatsApp

Wszystko, co robi strona Groups, robi też dwanaście operacji w ramach /v1/whatsapp/groups, więc cały cykl życia grupy mieści się w kodzie: utwórz ją, poczekaj na potwierdzenie od WhatsApp, udostępnij link z zaproszeniem, zdecyduj, kto wchodzi, aktualizuj szczegóły i przypięte wiadomości, a gdy rozmowa się skończy, usuń ją.

Dwie rzeczy kształtują każde wywołanie na tej stronie. Nikogo nie można dodać do grupy, więc link z zaproszeniem to jedyna droga do niej, a samo zapraszanie odbywa się poza API. Większość zmian rozlicza się po stronie WhatsApp, a nie w odpowiedzi, więc wywołanie przyjmujące zmianę nie jest tym, które potwierdza jej zastosowanie; sekcja Jak zmiana się rozlicza opisuje to raz dla każdej operacji, której dotyczy.

Grupy WhatsApp opisują, do czego służy grupa, i ten sam cykl życia w dashboardzie. Wysyłanie do grupy WhatsApp opisuje wysyłanie wiadomości do niej.

Wymagania wstępne

Potrzebujesz klucza API z dostępem whatsapp_management: poziom odczytu dla odczytów na tej stronie, poziom zapisu dla wszystkiego innego. Użytkownicy, zespoły i role opisują, jak go przyznać.

Potrzebujesz też numeru firmowego ze statusem Official Business Account, którego WhatsApp wymaga od administratora grupy; sekcja Zanim utworzysz grupę opisuje, jak go uzyskać. GET /v1/whatsapp/numbers raportuje go dla każdego numeru jako is_official_business_account, więc odczytaj go stamtąd zamiast wykrywać z 412. Flaga odpowiada stanowi z momentu meta_synced_at numeru, więc numer podłączony kilka minut temu może jeszcze nie być odczytany.

Zainicjalizuj klienta dla swojego języka, korzystając z przewodnika SDK dla TypeScript, Python, Go lub PHP. Przykłady CLI znajdziesz w sekcji zainstaluj i uwierzytelnij CLI. Przykłady cURL wskazują host US; jeśli Twój klucz zaczyna się od bk_eu1_, wywołuj https://eu1.platform.bird.com. SDK odczytują region z klucza, więc nie ustawiają hosta.

1. Utwórz grupę

Tworzenie wymaga podania numeru administrującego i tematu, nikogo więcej. Dwa wybory są ustalone na całe życie grupy i nie można ich później zmienić: numer oraz join_approval_mode, który decyduje, czy otwarcie linku z zaproszeniem wpuszcza kogoś od razu (auto_approve, domyślnie), czy zgłasza prośbę, którą rozpatrujesz (approval_required).

Note: creating a group needs a business number with Official Business Account status, the blue check mark WhatsApp puts next to a business name in the chat. WhatsApp Official Business Account covers what Meta requires and how to request it.

const group = await bird.whatsapp.groups.create({
  whatsapp_number_id: "wan_01krdgeqcxet5s7t44vh8rt9mg",
  subject: "Norwood Fleet — Tuesday route",
  join_approval_mode: "approval_required",
});
console.log(group.id, group.status); // pending; read it back for the invite link

group = client.whatsapp.groups.create(
    whatsapp_number_id="wan_01krdgeqcxet5s7t44vh8rt9mg",
    subject="Norwood Fleet — Tuesday route",
    join_approval_mode="approval_required",
)
print(group.id, group.status)  # pending; read it back for the invite link

group, err := client.Whatsapp.Groups.Create(context.Background(), bird.WhatsappGroupsCreateParams{
	WhatsappNumberID: "wan_01krdgeqcxet5s7t44vh8rt9mg",
	Subject:          "Norwood Fleet — Tuesday route",
	JoinApprovalMode: bird.Ptr(bird.WhatsAppGroupJoinApprovalMode("approval_required")),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*group.Id, *group.Status) // pending; read it back for the invite link

$group = $bird->whatsapp->groups->create(
    (new WhatsAppGroupCreate())
        ->setWhatsappNumberId('wan_01krdgeqcxet5s7t44vh8rt9mg')
        ->setSubject('Norwood Fleet — Tuesday route')
        ->setJoinApprovalMode('approval_required'),
);
echo $group->getId(), ' ', $group->getStatus(); // pending

bird whatsapp groups create \
  --whatsapp-number-id wan_01krdgeqcxet5s7t44vh8rt9mg \
  --subject 'Norwood Fleet — Tuesday route' \
  --join-approval-mode approval_required

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/groups" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "whatsapp_number_id": "wan_01krdgeqcxet5s7t44vh8rt9mg",
      "subject": "Norwood Fleet — Tuesday route",
      "join_approval_mode": "approval_required"
    }'

API zwraca 202 z grupą w statusie status pending i bez invite_link: WhatsApp wydaje link dopiero po potwierdzeniu grupy. Temat może mieć do 128 znaków, a opcjonalny description do 2048, i oba są widoczne dla każdego, kto otworzy link, więc nazwij grupę zgodnie z jej przeznaczeniem, a nie jako wewnętrzne odniesienie.

2. Poczekaj, aż WhatsApp ją potwierdzi

Odczytuj grupę, dopóki jej status nie opuści pending. Odczyt odpowiada 200 niezależnie od statusu, więc rozgałęziaj się na podstawie status, a nie na podstawie powodzenia wywołania.

const group = await bird.whatsapp.groups.get("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(group.status, group.invite_link);

group = client.whatsapp.groups.get("wag_01krdgeqcxet5s7t44vh8rt9mg")
print(group.status, group.invite_link)

group, err := client.Whatsapp.Groups.Get(context.Background(), "wag_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
	log.Fatal(err)
}
fmt.Println(*group.Status)
if group.InviteLink != nil {
	fmt.Println(*group.InviteLink)
}

$group = $bird->whatsapp->groups->get('wag_01krdgeqcxet5s7t44vh8rt9mg');
echo $group->getStatus(), ' ', $group->getInviteLink();

bird whatsapp groups get wag_01krdgeqcxet5s7t44vh8rt9mg

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

Mogą pojawić się pięć statusów i tylko jeden z nich oznacza grupę, z którą można pracować:

failed to drugie wyjście z pending, a last_operation.last_error.description zawiera własny powód od WhatsApp. Nigdy nie ponawiaj nieudanego utworzenia na tej samej grupie: zamiast tego utwórz nową, zmieniając to, czego dotyczyło odrzucenie.

3. Wpuść ludzi do grupy

Wyślij invite_link grupy do osób, które chcesz w niej mieć, dowolnym kanałem, który już do nich dociera. Żadna operacja nie dodaje uczestnika, więc link to jedyny sposób wejścia, a dołączenie jest ich decyzją. Link wpuszcza każdego, kto go posiada, więc traktuj go jak dane uwierzytelniające: grupy WhatsApp opisują, jak szeroko go rozpowszechniać.

W grupie auto_approve każdy, kto ma link, jest w środku i nie ma nic do decydowania. W grupie approval_required otwarcie linku tworzy prośbę o dołączenie. Wylistuj oczekujące, a następnie rozpatrz je w partiach do 50:

const waiting = [];
for await (const request of bird.whatsapp.groups.joinRequests.list(
  "wag_01krdgeqcxet5s7t44vh8rt9mg",
)) {
  waiting.push(request.id);
}
const result = await bird.whatsapp.groups.joinRequests.approve("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  join_request_ids: waiting.slice(0, 50),
});
console.log(result.decided.length, result.failed.length);

waiting = [r.id for r in client.whatsapp.groups.join_requests.list("wag_01krdgeqcxet5s7t44vh8rt9mg")]
result = client.whatsapp.groups.join_requests.approve(
    "wag_01krdgeqcxet5s7t44vh8rt9mg",
    join_request_ids=waiting[:50],
)
print(len(result.decided), len(result.failed))

result, err := client.Whatsapp.Groups.JoinRequests.Approve(context.Background(), "wag_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappGroupsJoinRequestsApproveParams{
	JoinRequestIDs: []string{"wgj_01krdgeqcxet5s7t44vh8rt9mg"},
})
if err != nil {
	log.Fatal(err)
}
for _, failure := range *result.Failed {
	fmt.Println(*failure.JoinRequestId, *failure.Error.Description)
}

$result = $bird->whatsapp->groups->joinRequests->approve(
    'wag_01krdgeqcxet5s7t44vh8rt9mg',
    (new WhatsAppGroupJoinRequestDecision())->setJoinRequestIds(['wgj_01krdgeqcxet5s7t44vh8rt9mg']),
);
echo count($result->getDecided() ?? []), ' ', count($result->getFailed() ?? []);

bird whatsapp groups join-requests list wag_01krdgeqcxet5s7t44vh8rt9mg
bird whatsapp groups join-requests approve wag_01krdgeqcxet5s7t44vh8rt9mg \
  --join-request-ids wgj_01krdgeqcxet5s7t44vh8rt9mg

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/groups/wag_01krdgeqcxet5s7t44vh8rt9mg/join-requests/batch-approve" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"join_request_ids": ["wgj_01krdgeqcxet5s7t44vh8rt9mg"]}'

WhatsApp rozpatruje każdą prośbę osobno, więc partia może być zastosowana częściowo: odpowiedź rozdziela decided od failed, a każde niepowodzenie zawiera powód podany przez WhatsApp w error.description. Czytaj odpowiedź, a nie kod statusu. Odrzucenie często dotyczy osoby, która nie zaakceptowała aktualnych warunków WhatsApp, czego ponowna próba nie naprawi.

Zatwierdzenie większej liczby osób, niż grupa może pomieścić, nie odrzuca wywołania: prośby, które się mieszczą, zostają rozpatrzone, a reszta wraca w failed, z informacją, że zatwierdzenie przekroczyłoby limit uczestników. Odrzucanie działa tak samo, przez POST /v1/whatsapp/groups/{group_id}/join-requests/batch-reject. Prośba znika z listy również wtedy, gdy osoba sama ją anuluje, więc ID, które było ważne chwilę temu, może zwrócić 422 E15051, zanim go użyjesz.

Limit 50 to własne ograniczenie Bird na jedno żądanie, a nie WhatsApp, więc seryjne odrzucanie nie jest ograniczone liczbą osób, które grupa może pomieścić.

Obserwuj przychodzące prośby o dołączenie

Zasubskrybuj whatsapp.group.join_request_created i whatsapp.group.join_request_revoked, żeby dowiadywać się, gdy ktoś prosi o dołączenie i gdy anuluje prośbę, zamiast odpytywać listę. Prośba zgłoszona i anulowana między dwoma odczytami listy nie zostawia po sobie śladu, więc te zdarzenia są jedynym sposobem, żeby ją zobaczyć. Każde zdarzenie zawiera join_request.id, który przyjmują operacje wsadowe, więc możesz podejmować decyzję bezpośrednio na jego podstawie. Webhooki grup WhatsApp opisują oba payloady i każde pole.

Rotacja linku zaproszeniowego

Rotacja generuje nowy link i unieważnia każdy dotychczasowy link grupy, więc nikt, kto wciąż ma stary, nie może dołączyć. Wykonaj rotację, gdy link rozprzestrzenił się dalej, niż zamierzałeś, lub po usunięciu kogoś, kogo nie chcesz z powrotem. Nowy link wraca w samym wywołaniu, które odpowiada 200:

const link = await bird.whatsapp.groups.inviteLink.rotate("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(link.invite_link); // every earlier link has stopped working

link = client.whatsapp.groups.invite_link.rotate("wag_01krdgeqcxet5s7t44vh8rt9mg")
print(link.invite_link)  # every earlier link has stopped working

link, err := client.Whatsapp.Groups.InviteLink.Rotate(context.Background(), "wag_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
	log.Fatal(err)
}
fmt.Println(*link.InviteLink) // every earlier link has stopped working

$link = $bird->whatsapp->groups->inviteLink->rotate('wag_01krdgeqcxet5s7t44vh8rt9mg');
echo $link->getInviteLink(); // every earlier link has stopped working

bird whatsapp groups invite-link rotate wag_01krdgeqcxet5s7t44vh8rt9mg --yes

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/groups/wag_01krdgeqcxet5s7t44vh8rt9mg/invite-link/rotate" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Rotacja nie służy do odczytywania bieżącego linku. Grupa zawiera swój invite_link, więc odczyt grupy jest tym odczytem.

CLI nie wyświetla potwierdzeń, więc jego destrukcyjne polecenia wymagają zamiast tego --yes: rotacja linku, usunięcie uczestnika, usunięcie grupy, odpięcie wiadomości i odrzucenie próśb o dołączenie bez niego kończą się odmową z confirmation_required.

Jak zmiana się utrwala

WhatsApp potwierdza część zmian w swojej odpowiedzi, a inne na webhooku, a kod statusu mówi, z którym rodzajem masz do czynienia:

W przypadku pierwszych dwóch wierszy 202 oznacza żądanie przyjęte, nie zastosowane. last_operation.status ma wartość pending, dopóki WhatsApp nie odpowie, zwykle w ciągu sekund, a potem utrwala się jako success lub failed, przy czym last_error.description zawiera przyczynę w przypadku niepowodzenia. Odczytaj grupę ponownie, żeby zobaczyć, co zostało zastosowane.

Gdy operacja ma status pending, kolejna zmiana tego samego elementu zwraca 409 E15054. Zmiany na poziomie grupy współdzielą last_operation grupy, więc trwająca zmiana nazwy blokuje usunięcie. Każdy uczestnik ma własny, więc usuwanie kilku osób naraz daje każdej z nich własny stan i własne niepowodzenie, i tylko oczekujące usunięcie danej osoby blokuje kolejną próbę wobec niej.

Dwa 409 chronią zapisy, a status jest sprawdzany jako pierwszy, więc grupa, która nie jest active, zwraca E15047 niezależnie od tego, co mówi jej last_operation. Ma to znaczenie dla grupy wciąż tworzonej, która jest w stanie oczekiwania pod oboma względami jednocześnie.

Każdy zapis przyjmuje też nagłówek Idempotency-Key. Idempotentność opisuje bezpieczne ponawianie.

Zmiana tematu, opisu lub zdjęcia grupy

Aktualizacja zmienia to, co uczestnicy widzą na górze grupy. Pominięte pola pozostają bez zmian; wyślij null, żeby wyczyścić opis lub zdjęcie, ponieważ pusty ciąg znaków to 422, a nie drugi sposób czyszczenia.

const group = await bird.whatsapp.groups.update("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  subject: "Norwood Fleet — Wednesday route",
});
console.log(group.last_operation?.status); // pending until WhatsApp reports back

group = client.whatsapp.groups.update(
    "wag_01krdgeqcxet5s7t44vh8rt9mg",
    subject="Norwood Fleet — Wednesday route",
)
print(group.last_operation)  # pending until WhatsApp reports back

group, err := client.Whatsapp.Groups.Update(context.Background(), "wag_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappGroupsUpdateParams{
	Subject: bird.Ptr("Norwood Fleet — Wednesday route"),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*group.LastOperation.Status) // pending until WhatsApp reports back

$group = $bird->whatsapp->groups->update(
    'wag_01krdgeqcxet5s7t44vh8rt9mg',
    (new WhatsAppGroupUpdate())->setSubject('Norwood Fleet — Wednesday route'),
);
echo $group->getLastOperation()?->getStatus(); // pending until WhatsApp reports back

bird whatsapp groups update wag_01krdgeqcxet5s7t44vh8rt9mg \
  --subject 'Norwood Fleet — Wednesday route'

curl -X PATCH "https://us1.platform.bird.com/v1/whatsapp/groups/wag_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject": "Norwood Fleet — Wednesday route"}'

WhatsApp stosuje każde pole osobno, więc aktualizacja może być częściowo zastosowana: jedno pole odrzucone, podczas gdy pozostałe wchodzą w życie. Gdy operacja się utrwali, last_operation.results zawiera jeden wpis na każde pole wysłane w aktualizacji, dzięki czemu możesz powiązać odrzucenie z danymi wejściowymi, których dotyczy.

profile_picture_url wskazuje plik w bibliotece mediów Twojego obszaru roboczego, a nie adres w internecie, a WhatsApp przyjmuje kwadratowy JPEG o wymiarach co najmniej 192 na 192 piksele i do 5 MB. Wyczyszczenie usuwa zdjęcie przechowywane przez Bird, ale WhatsApp nie ma operacji usuwania zdjęcia grupy, więc uczestnicy widzą bieżące zdjęcie, dopóki nie zastąpi go inne. Numer administrujący i join_approval_mode są ustalane przy tworzeniu i nie można ich tu zmienić.

Usunięcie uczestnika

Usunięcia nie można cofnąć. WhatsApp blokuje usuniętej osobie dołączenie do grupy za pomocą linku zaproszeniowego, a blokada podąża za osobą, nie za linkiem, więc rotacja linku nie pozwoli jej wrócić. Ponieważ nie ma operacji dodawania stanowiącej parę z tą, nic nie przywróci kogoś do tej grupy po usunięciu, a ponowne dotarcie do niego oznacza utworzenie innej grupy i zaproszenie go do niej.

Wskaż osobę dowolnym identyfikatorem, pod którym wymienia ją participants grupy: jej bsuid, który ma każdy, lub jej phone_number w formacie E.164, który jest obecny tylko wtedy, gdy WhatsApp go udostępnia. W adresie URL zakoduj wiodący + jako %2B, chyba że Twój klient robi to za Ciebie.

const group = await bird.whatsapp.groups.participants.remove(
  "wag_01krdgeqcxet5s7t44vh8rt9mg",
  "+15550002222",
);
console.log(group.participants?.length);

group = client.whatsapp.groups.participants.remove(
    "wag_01krdgeqcxet5s7t44vh8rt9mg",
    "+15550002222",
)
print(len(group.participants or []))

group, err := client.Whatsapp.Groups.Participants.Remove(context.Background(), "wag_01krdgeqcxet5s7t44vh8rt9mg", "+15550002222")
if err != nil {
	log.Fatal(err)
}
if group.Participants != nil {
	fmt.Println(len(*group.Participants))
}

$group = $bird->whatsapp->groups->participants->remove(
    'wag_01krdgeqcxet5s7t44vh8rt9mg',
    '+15550002222',
);
echo count($group->getParticipants() ?? []);

bird whatsapp groups participants remove wag_01krdgeqcxet5s7t44vh8rt9mg +15550002222 --yes

curl -X DELETE "https://us1.platform.bird.com/v1/whatsapp/groups/wag_01krdgeqcxet5s7t44vh8rt9mg/participants/%2B15550002222" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Usunięcie uczestnika ma status pending na jego własnym wpisie, dopóki WhatsApp go nie potwierdzi, i nigdy nie trafia do success: zniknięcie wpisu z participants oznacza, że się powiodło. Wartość wskazująca kogoś, kto nie jest w grupie, zwraca 422 E15050.

Przypięcie wiadomości

Przypięcie utrzymuje jedną z wiadomości grupy na górze czatu, dzięki czemu osoba dołączająca później nie musi przewijać w poszukiwaniu tematu, do którego rozmowa wciąż wraca. Przypięcie trwa duration_days, od 1 do 30, a domyślna wartość to 7.

const pin = await bird.whatsapp.groups.pins.create("wag_01krdgeqcxet5s7t44vh8rt9mg", {
  message_id: "wam_01kya19eknftrs2s6p82asmvnh",
  duration_days: 14,
});
console.log(pin.pinned_until);

pin = client.whatsapp.groups.pins.create(
    "wag_01krdgeqcxet5s7t44vh8rt9mg",
    message_id="wam_01kya19eknftrs2s6p82asmvnh",
    duration_days=14,
)
print(pin.pinned_until)

pin, err := client.Whatsapp.Groups.Pins.Create(context.Background(), "wag_01krdgeqcxet5s7t44vh8rt9mg", bird.WhatsappGroupsPinsCreateParams{
	MessageID:    "wam_01kya19eknftrs2s6p82asmvnh",
	DurationDays: bird.Ptr(14),
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(*pin.PinnedUntil)

$pin = $bird->whatsapp->groups->pins->create(
    'wag_01krdgeqcxet5s7t44vh8rt9mg',
    (new WhatsAppGroupPinnedMessageCreate())
        ->setMessageId('wam_01kya19eknftrs2s6p82asmvnh')
        ->setDurationDays(14),
);
echo $pin->getPinnedUntil()?->format(DATE_ATOM);

bird whatsapp groups pins create wag_01krdgeqcxet5s7t44vh8rt9mg \
  --message-id wam_01kya19eknftrs2s6p82asmvnh \
  --duration-days 14

curl -X POST "https://us1.platform.bird.com/v1/whatsapp/groups/wag_01krdgeqcxet5s7t44vh8rt9mg/pinned-messages" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_id": "wam_01kya19eknftrs2s6p82asmvnh", "duration_days": 14}'

Wiadomość musi należeć do tej grupy: wiadomość z innej grupy lub wiadomość jeden-do-jednego zwraca 422 E15053. Grupa może mieć tylko określoną liczbę przypiętych wiadomości jednocześnie, a przypięcie ponad ten limit odpina najstarszą zamiast kończyć się błędem; przypięcie już przypiętej wiadomości zastępuje jej wygaśnięcie. To, co grupa aktualnie ma przypięte, znajduje się na samej grupie jako pinned_messages.

WhatsApp odpina wiadomość samodzielnie po upływie wyznaczonych dni, więc odpinaj tylko po to, żeby usunąć przypięcie wcześniej. DELETE /v1/whatsapp/groups/{group_id}/pinned-messages/{message_id} odpowiada 200, a powtórzenie jest bezpieczne: wiadomość należąca do tej grupy, która nie jest przypięta, niczego nie zmienia i wciąż odpowiada 200.

Usunięcie grupy

Usunięcie usuwa grupę w WhatsApp. Każdy uczestnik traci dostęp, łącznie z Twoją firmą, a link zaproszeniowy przestaje działać. Operacji nie można cofnąć, a wznowienie rozmowy oznacza utworzenie nowej grupy i wysłanie jej linku.

const group = await bird.whatsapp.groups.delete("wag_01krdgeqcxet5s7t44vh8rt9mg");
console.log(group.last_operation?.status); // pending until WhatsApp confirms it

group = client.whatsapp.groups.delete("wag_01krdgeqcxet5s7t44vh8rt9mg")
if group.last_operation:
    print(group.last_operation.status)  # pending until WhatsApp confirms it

group, err := client.Whatsapp.Groups.Delete(context.Background(), "wag_01krdgeqcxet5s7t44vh8rt9mg")
if err != nil {
	log.Fatal(err)
}
fmt.Println(*group.LastOperation.Status) // pending until WhatsApp confirms it

$group = $bird->whatsapp->groups->delete('wag_01krdgeqcxet5s7t44vh8rt9mg');
echo $group->getLastOperation()?->getStatus(); // pending until WhatsApp confirms it

bird whatsapp groups delete wag_01krdgeqcxet5s7t44vh8rt9mg --yes

curl -X DELETE "https://us1.platform.bird.com/v1/whatsapp/groups/wag_01krdgeqcxet5s7t44vh8rt9mg" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Grupa pozostaje czytelna po usunięciu w statusie status deleted, więc zapisane odwołanie do niej wciąż się rozwiązuje zamiast zamieniać w 404. Grupę failed też można usunąć, a ta nie trafia do żadnego zewnętrznego systemu: tworzenie nigdy nie wygenerowało grupy w WhatsApp, więc wyczyszczenie wiersza to wewnętrzne porządki Bird. Każdy inny status odmawia z 409 E15047.

Lista grup

Lista zwraca grupy utworzone w Twoim obszarze roboczym, od najnowszych, jako stronę kursorową. Filtruj po numerze administrującym (number, jako numer E.164 lub identyfikator wan_), po koncie WhatsApp Business Account, z którego wysyła (waba), lub po status, powtarzając parametr, żeby dopasować kilka wartości. q przeszukuje temat i opis pod kątem podciągu, bez rozróżniania wielkości liter.

for await (const group of bird.whatsapp.groups.list({ status: ["active"] })) {
  console.log(group.id, group.subject, group.participant_count);
}

for group in client.whatsapp.groups.list(status=["active"]):
    print(group.id, group.subject, group.participant_count)

for group, err := range client.Whatsapp.Groups.List(context.Background(), bird.WhatsappGroupsListParams{
	Status: []bird.WhatsAppGroupStatus{"active"},
}) {
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(*group.Id, group.Subject, *group.ParticipantCount)
}

foreach ($bird->whatsapp->groups->list(['status' => ['active']]) as $group) {
    echo $group->getId(), ' ', $group->getSubject(), PHP_EOL;
}

bird whatsapp groups list --status active

curl "https://us1.platform.bird.com/v1/whatsapp/groups?status=active" \
  -H "Authorization: Bearer $BIRD_API_KEY"

Usunięta grupa pozostaje na liście ze statusem status deleted, więc filtruj po statusie, żeby widzieć tylko grupy, do których wciąż możesz wysyłać wiadomości.

Rozwiązywanie problemów

• 412 (E15045): Numer nie ma statusu Official Business Account, więc WhatsApp nie pozwoli mu utworzyć grupy. Decyzja należy do WhatsApp: poproś o status w WhatsApp Manager w profilu numeru lub utwórz grupę na numerze, który już go posiada.
• 404 (E15046): Podany identyfikator nie wskazuje żadnej grupy w tym obszarze roboczym. Grupa należy do obszaru roboczego, który ją utworzył, więc identyfikator z innego obszaru roboczego nie zostanie tu znaleziony.
• 409 (E15047): Grupa jest w stanie oczekiwania, zawieszona, usunięta lub zakończona niepowodzeniem. Tylko aktywna grupa przyjmuje zmiany. Odczytaj grupę, żeby sprawdzić jej stan.
• 409 (E15049): Numer administruje już 10 000 grup, które dopuszcza WhatsApp. Usuń grupy, których rozmowa się zakończyła, lub utwórz tę grupę na innym numerze.
• 409 (E15054): Zmiana dotycząca tej samej grupy lub tego samego uczestnika wciąż oczekuje na zakończenie. Odczytaj last_operation i poczekaj, aż się utrwali.
• 422 (E15050): Ścieżka nie wskazuje nikogo w grupie. Odczytaj participants grupy i użyj bsuid lub phone_number w postaci, w jakiej są raportowane.
• 422 (E15051): Jeden z identyfikatorów próśb o dołączenie nie oczekuje już na decyzję. Pobierz listę próśb ponownie i użyj identyfikatorów, które zostaną zwrócone.
• 422 (E15053): Wiadomość należy do innej grupy lub do rozmowy jeden-do-jednego. to.group_id wiadomości wskazuje, która grupa może ją przypiąć.
• Grupa pending, która nigdy nie staje się aktywna: Bird rezygnuje z oczekiwania zamiast zostawiać ją w stanie oczekującym i przenosi grupę do failed z przyczyną w last_operation.last_error. Utwórz zastępczą grupę zamiast ponawiać próbę.

Referencja

Pełne kształty żądań i odpowiedzi znajdują się w referencji API: create, list, get, update, delete, rotacja linku zaproszeniowego, usunięcie uczestnika, lista, zatwierdzenie i odrzucenie próśb o dołączenie oraz przypięcie i odpięcie wiadomości.

Następne kroki

• Grupy WhatsApp: czym jest grupa i ten sam cykl życia w panelu
• Wysyłanie do grupy WhatsApp: adresowanie grupy, wymagania i potwierdzenia dostarczenia per uczestnik
• Odbieranie wiadomości z grupy WhatsApp: który uczestnik napisał wiadomość i odpowiadanie do grupy
• Business-scoped user IDs: identyfikator uczestnika, gdy nie masz numeru telefonu
• Idempotentność: ponawianie zapisu, który mógł już zostać przyjęty