# Wiadomości interaktywne WhatsApp

Wiadomość interaktywna to tekst treści plus element do kliknięcia przez odbiorcę: przycisk WhatsApp, menu, link, karta lub żądanie lokalizacji albo danych kontaktowych. Tam, gdzie odpowiedź szablonowa wymaga parsowania dowolnego tekstu, menu WhatsApp lub zestaw przycisków WhatsApp daje odbiorcy ustalony zbiór opcji, a tobie zwraca wartość, którą sam zdefiniowałeś. Ta strona opisuje cechy wspólne sześciu typów; strona każdego typu opisuje jego kształt na poziomie protokołu i jego własne ograniczenia.

## Sześć typów

| Typ                                                                                                  | Bird `interactive.type`    | Nagłówek                                    | Stopka | Maks. treści                 |
| ---------------------------------------------------------------------------------------------------- | -------------------------- | ------------------------------------------- | ------ | ---------------------------- |
| [Przyciski odpowiedzi](/docs/guides/whatsapp/message-types/interactive/reply-buttons)                | `button`                   | tekst, obraz, wideo, dokument               | tak    | 1024                         |
| [Menu list](/docs/guides/whatsapp/message-types/interactive/list-menus)                              | `list`                     | tylko tekst                                 | tak    | 4096                         |
| [Przyciski z linkiem](/docs/guides/whatsapp/message-types/interactive/cta-url-buttons)               | `cta_url`                  | tekst, obraz, wideo, dokument               | tak    | 1024                         |
| [Karuzele multimedialne](/docs/guides/whatsapp/message-types/interactive/carousels)                  | `carousel`                 | brak w wiadomości; obraz lub wideo na kartę | nie    | 1024 wiadomość, 160 na kartę |
| [Żądania lokalizacji](/docs/guides/whatsapp/message-types/interactive/location-requests)             | `location_request_message` | brak                                        | nie    | 1024                         |
| [Żądania danych kontaktowych](/docs/guides/whatsapp/message-types/interactive/contact-info-requests) | `request_contact_info`     | brak                                        | nie    | 1024                         |

Każdy typ jest treścią dowolną: można go dostarczyć tylko w otwartym oknie obsługi klienta i nigdy nie podlega weryfikacji przez Meta tak jak szablon.

Wiadomości interaktywne to treść dowolna, więc obowiązuje reguła okna obsługi klienta: zobacz [okno obsługi klienta](/docs/guides/whatsapp/message-types#the-customer-service-window), aby dowiedzieć się, co to oznacza i co zwraca zamknięte okno.

Każde interaktywne wysłanie wymaga też `from`, numeru należącego do twojego obszaru roboczego. Numery zarządzane przez Bird nie obsługują tej funkcji, więc do interaktywnego wysłania potrzebujesz najpierw podłączonego własnego numeru.

## Gałąź treści interaktywnej

`interactive` to jedno z wzajemnie wykluczających się pól treści w `POST /v1/whatsapp/messages`, obok `template`, `text`, `image` i pozostałych: dokładnie jedno może być obecne w wysyłce. Wewnątrz `interactive` pole `type` wskazuje, który z sześciu wariantów to jest, a pole tego wariantu zawiera resztę (`buttons`, `list`, `cta_url` lub `cards`). Schemat blokuje pola każdego innego wariantu, więc mieszanie dwóch wariantów w jednej wysyłce kończy się błędem walidacji, zanim żądanie dotrze do handlera.

Kopertę żądania, model odpowiedzi `202` i bezpieczne ponawianie znajdziesz na stronie [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp), a nie na tej stronie.

Oto minimalna wiadomość interaktywna: dwa przyciski WhatsApp w wysyłce z przyciskami odpowiedzi, po jednym języku naraz.

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+15551234567",
  from: "+13124495648",
  interactive: {
    type: "button",
    body_text: "Your gardening workshop is scheduled for 9am tomorrow.",
    buttons: [
      { type: "quick_reply", quick_reply: { slug: "change-booking", text: "Change" } },
      { type: "quick_reply", quick_reply: { slug: "cancel-booking", text: "Cancel" } },
    ],
  },
});
console.log(msg.id, msg.status);
```

Examples: [TypeScript](/pl-pl/dokumentacja/guides/whatsapp/message-types/interactive.ts.md) · [Python](/pl-pl/dokumentacja/guides/whatsapp/message-types/interactive.py.md) · [Go](/pl-pl/dokumentacja/guides/whatsapp/message-types/interactive.go.md) · [PHP](/pl-pl/dokumentacja/guides/whatsapp/message-types/interactive.php.md) · [CLI](/pl-pl/dokumentacja/guides/whatsapp/message-types/interactive.cli.md) · [MCP](/pl-pl/dokumentacja/guides/whatsapp/message-types/interactive.mcp.md) · [cURL](/pl-pl/dokumentacja/guides/whatsapp/message-types/interactive.curl.md)

## Przyciski

Cztery z sześciu typów umieszczają przycisk i wszystkie korzystają z tego samego kształtu: obiektu z dyskryminatorem, którego `type` to `quick_reply` lub `cta_url`, każdy z własnym zagnieżdżonym polem o tej samej nazwie. Przycisk `quick_reply` zawiera `slug` i `text`; przycisk `cta_url` zawiera `text` i `url`. Które typy akceptują który kształt przycisku:

- **Przyciski odpowiedzi** wysyłają tylko przyciski `quick_reply`, od 1 do 3.
- **Przyciski z linkiem** wysyłają dokładnie jeden przycisk `cta_url`.
- **Karuzele multimedialne** umieszczają przyciski na każdej karcie: albo jeden przycisk `cta_url`, albo do trzech przycisków `quick_reply`, przy czym każda karta w karuzeli musi być zgodna.
- **Menu list** używają wierszy wewnątrz sekcji zamiast tego obiektu przycisku; szczegóły na ich własnej stronie.

Pole `slug` przycisku `quick_reply` to twój własny identyfikator tego przycisku. Nigdy nie jest pokazywane odbiorcy; widoczna jest tylko etykieta `text`, a `slug` jest zwracane dosłownie w odpowiedzi. To właśnie ten obieg pozwala powiązać odpowiedź z przyciskiem, który ją wywołał, dlatego warto powiedzieć o tym raz, tutaj, a nie na każdej stronie poszczególnego typu.

## Odczytywanie odpowiedzi

Naciśnięcie przycisku lub wybranie wiersza z menu wysyła osobną wiadomość przychodzącą z obiektem `interactive_reply`. `interactive_reply.type` to `button` lub `list`; niezależnie od wartości, zagnieżdżony obiekt zawiera zadeklarowane przez ciebie `slug` i `text`, czyli klikniętą etykietę, którą odbiorca faktycznie widział. Dwa typy żądań, żądania lokalizacji i żądania danych kontaktowych, odpowiadają inaczej: odpowiedź na żądanie lokalizacji to zwykła przychodząca wiadomość [lokalizacji](/docs/guides/whatsapp/message-types/interactive/location-requests), a odpowiedź na żądanie danych kontaktowych to przychodząca [wizytówka](/docs/guides/whatsapp/message-types/interactive/contact-info-requests), a nie `interactive_reply`.

Odpowiedź dociera do ciebie przez listę wiadomości i `GET /v1/whatsapp/messages/{id}`, tak samo jak każda przychodząca wiadomość WhatsApp. Aby reagować na nią w momencie nadejścia zamiast odpytywać, zasubskrybuj webhook `whatsapp.received`: jego payload zawiera `interactive_reply`, więc już wskazuje kliknięty przycisk lub wiersz. [Odbieranie interaktywnych odpowiedzi](/docs/guides/whatsapp/receiving-whatsapp/interactive-replies) opisuje kształt odczytu kliknięcia, payload webhooka i kliknięcia docierające na innej gałęzi.

## Cytowanie wiadomości w celu powiązania odpowiedzi

`in_reply_to_message_id` w wysyłce cytuje wcześniejszą wiadomość z tej samej konwersacji, a każda wiadomość, wysłana lub odebrana, zwraca je przy odczycie. To jedno pole dla obu kierunków.

Korelacja, którą to daje, jest asymetryczna. Kliknięcie przycisku WhatsApp lub wiersza menu niesie własne `context` od Meta, więc `in_reply_to_message_id` wskazuje wiadomość, która je zaoferowała. Udostępniona wizytówka nie niesie żadnego `context`, więc nie wskazuje niczego: odpowiedź na żądanie danych kontaktowych korelujesz po `from` i czasie, nie po tym polu.

Rozwiązywanie odbywa się przez magazyn kontekstu wiadomości, a brak dopasowania **pomija** pole zamiast je zgłaszać. Na poziomie protokołu jest to nieodróżnialne od odpowiedzi, która niczego nie dotyczy. Integracja wymagająca niezawodnej korelacji nie powinna polegać wyłącznie na tym polu: dodaj własne `metadata` do wysyłki i dopasowuj po nim.

Okno, w którym wiadomość pozostaje cytowalna, jest ograniczone do 15 dni; po tym czasie wysyłka kończy się błędem `404` [`E15071`](/docs/api/errors/E15071), ponieważ Bird nie przechowuje już identyfikatora dostawcy potrzebnego do cytatu. Strona [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp#quoting-a-message) opisuje pole po stronie wysyłki: jego długość, rozwiązywanie i kształt żądania.

## Błędy

Trzy kody błędów dotyczą wyłącznie treści interaktywnej. Każdy z nich uruchamia się tylko dla typów, które mają sprawdzane pole, dlatego czwarta kolumna wskazuje, które typy mogą faktycznie go wywołać.

| Kod                                                                            | Status | Co go wywołuje                                                                            | Dotyczy                                                                                                       |
| ------------------------------------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [E15055 `WhatsAppInteractiveLimitExceeded`](/docs/api/errors/E15055)           | 422    | Wiadomość przekracza limit dla swojego typu; aktualnie ponad 10 wierszy w sekcjach listy. | Tylko menu list                                                                                               |
| [E15056 `WhatsAppInteractiveDuplicateLabel`](/docs/api/errors/E15056)          | 422    | Dwa przyciski lub wiersze w tej samej wiadomości mają tę samą etykietę.                   | Każdy typ z etykietowanymi przyciskami lub wierszami: przyciski odpowiedzi, menu list, karuzele multimedialne |
| [E15059 `WhatsAppInteractiveCarouselButtonsMismatch`](/docs/api/errors/E15059) | 422    | Karty karuzeli nie mają jednakowych przycisków.                                           | Tylko karuzele multimedialne                                                                                  |

Każde interaktywne wysłanie może też trafić na błędy wspólne dla każdej wysyłki WhatsApp: zamknięte okno obsługi klienta, brakujący lub nieprawidłowy nadawca, nieprawidłowy odbiorca albo niejednoznaczna treść. Są one wspólne dla wszystkich typów treści WhatsApp, nie tylko dla wiadomości interaktywnych; zobacz [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp), aby poznać tę listę bez jej powielania tutaj.

## Następne kroki

- [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp): koperta żądania, model `202` i bezpieczne ponawianie
- [Zdarzenia WhatsApp](/docs/guides/whatsapp/events): śledź dostarczenie wiadomości przez API lub webhooki
- [Szablony WhatsApp](/docs/guides/whatsapp/templates): wiadomości, które nadal możesz wysłać po zamknięciu okna

## Related resources

- [Connecting WhatsApp to Bird: from buying a number to a live channel](/learn/whatsapp/connecting-whatsapp-to-bird) (video)
- [What is the 24-hour customer service window on WhatsApp?](/explained/whatsapp/what-is-the-24-hour-customer-service-window) (answer)
- [WhatsApp message builder](/tools/whatsapp-message-builder) (tool)
- [WhatsApp](/products/whatsapp) (product)

[Get an implementation brief](/learn/workspace?topic=whatsapp)