# Przyciski linkowe WhatsApp

Przycisk linkowy umieszcza pod wiadomością WhatsApp jeden klikalny przycisk, który otwiera URL w przeglądarce odbiorcy. Użyj go, gdy kolejny krok znajduje się w sieci, np. strona płatności lub harmonogram warsztatów, a nie w samym czacie. Jeśli odbiorca ma dokonać wyboru wewnątrz WhatsApp, użyj [przycisków odpowiedzi](/docs/guides/whatsapp/message-types/interactive/reply-buttons) lub [menu listy](/docs/guides/whatsapp/message-types/interactive/list-menus).

## Wyślij przycisk linkowy

Ustaw `interactive.type` na `cta_url` z obiektem `body_text` i obiektem `cta_url` zawierającymi `text` i `url` przycisku:

**TypeScript**

```typescript
const msg = await bird.whatsapp.send({
  to: "+16505551234",
  from: "+13124495648",
  interactive: {
    type: "cta_url",
    body_text: "Tap the button below to see the available dates.",
    cta_url: { text: "See dates", url: "https://example.com/workshops?click_id=a1b2c3" },
  },
});
console.log(msg.id, msg.status);
```

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

`from` jest wymagane w każdej wiadomości serwisowej: numer należący do Twojego obszaru roboczego, a nie zarządzany przez Bird. Pełna struktura dodaje opcjonalny nagłówek, stopkę i cytowanie wcześniejszej wiadomości:

```json
{
  "to": "+16505551234",
  "from": "+13124495648",
  "in_reply_to_message_id": "wam_01kya19eknftrs2s6p82asmvnh",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "url": "https://cdn.example.com/banners/workshop.png"
    },
    "body_text": "Tap the button below to see the available dates.",
    "footer_text": "Dates are subject to change.",
    "cta_url": {
      "text": "See dates",
      "url": "https://example.com/workshops?click_id=a1b2c3"
    }
  },
  "tags": [{ "name": "campaign", "value": "autumn-workshops" }],
  "metadata": { "order_id": "A-4192" }
}
```

`in_reply_to_message_id` cytuje wcześniejszą wiadomość w tej samej konwersacji. Zobacz w hubie [cytowanie wiadomości w celu powiązania odpowiedzi](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply), aby dowiedzieć się, jak działa rozwiązywanie i czego może nie wykryć.

Ten typ wysyła dokładnie jeden przycisk `cta_url` i nie może zawierać `buttons`, `list` ani `cards` obok niego. Zobacz w hubie sekcję [przyciski](/docs/guides/whatsapp/message-types/interactive#buttons), aby poznać wspólną strukturę przycisku, z której korzysta również przycisk linkowy karty karuzeli.

## Nagłówki i stopki

Nagłówek jest opcjonalny i przyjmuje jedną z czterech postaci:

```text
"header": { "type": "text",     "text": "New workshop dates" }
"header": { "type": "image",    "url": "https://cdn.example.com/a.png" }
"header": { "type": "video",    "url": "https://cdn.example.com/a.mp4" }
"header": { "type": "document", "url": "https://cdn.example.com/a.pdf" }
```

Nagłówek medialny (`image`, `video` lub `document`) przekazuje plik jako publiczny URL `https`, który WhatsApp pobiera w momencie wysyłki, zamiast przesłanego uchwytu mediów. `footer_text` jest opcjonalna i dodaje wiersz pod przyciskiem.

## Limity

| Pole                      | Ograniczenie                  |
| ------------------------- | ----------------------------- |
| Przyciski `cta_url`       | dokładnie jeden               |
| `cta_url.text` (etykieta) | wymagane, od 1 do 20 znaków   |
| `cta_url.url`             | wymagane, od 1 do 2000 znaków |
| `body_text`               | wymagane, od 1 do 1024 znaków |
| `footer_text`             | opcjonalne, od 1 do 60 znaków |
| `header.text`             | od 1 do 60 znaków             |

Limit 2000 znaków na `url` jest własnym ograniczeniem Bird: Meta nie publikuje limitu długości dla tego pola. `url` sprawdza również `format: uri`, adres bezwzględny ze schematem, ale Bird nie weryfikuje, jaki to schemat: adres `http://` przechodzi walidację Bird, a Meta jest jedynym sędzią, czy wiadomość zostanie doręczona.

## Co zgłasza kliknięcie

Tapnięcie otwiera adres w przeglądarce odbiorcy i nic nie wraca do Ciebie przez API. Tapnięcie przycisku linkowego nie jest `interactive_reply`: mapper przychodzący, który generuje `interactive_reply`, obsługuje tylko tapnięcie przycisku odpowiedzi i tapnięcie wiersza listy, a link `cta_url` nie ma odpowiednika po stronie przychodzącej. Widzisz natomiast zwykły cykl życia wiadomości wychodzącej: statusy `sent`, `delivered` i `read`, ale `read_at` informuje, że wiadomość została otwarta, a nie że przycisk został tapnięty. Nie ma zdarzenia kliknięcia, znacznika czasu ani sygnału tapnięcia per odbiorca z WhatsApp ani z Bird.

Dwa sposoby na uzyskanie atrybucji, skoro sama wysyłka jej nie dostarczy:

- **Zinstrumentuj stronę docelową.** Jedyne dostępne dowody kliknięcia znajdują się na Twoim serwerze docelowym, z URL-a, który przekazałeś.
- **Sam zróżnicuj URL per odbiorca.** `url`, który wysyłasz, jest literalnym ciągiem znaków: Bird przechowuje go i przekazuje do Meta bez zmian, bez podstawiania i bez składni zmiennych. Jest identyczny dla każdego odbiorcy jednej wysyłki, więc atrybucja per odbiorca wymaga wygenerowania własnego parametru zapytania, np. `?click_id=<value>`, i wysłania jednego wywołania `POST /v1/whatsapp/messages` na odbiorcę. Endpoint już przyjmuje pojedynczy `to` na wywołanie, więc jest to kwestia księgowości po Twojej stronie, a nie brakująca funkcja API.

Trzecia opcja istnieje całkowicie poza tym typem: [szablon](/docs/guides/whatsapp/templates) ze zmienną przycisku `url` jest personalizowany per odbiorca przez sam WhatsApp, dostarczany przez komponent `button` wysyłki. Zmienna musi znajdować się na końcu adresu, zapisana jako `{{1}}`, więc może zmieniać końcowy segment ścieżki lub wartość zapytania, ale nigdy hosta ani środka URL-a. Kompromis: szablon daje URL-e per odbiorca i dostarczanie poza oknem obsługi klienta kosztem przeglądu Meta i ustalonej zatwierdzonej struktury, natomiast wysyłka `cta_url` daje swobodną, niewymagającą przeglądu wysyłkę wewnątrz otwartego okna z URL-em, który sam różnicujesz.

## Limity i przypadki brzegowe

- **Okno obsługi klienta musi być otwarte.** Przycisk linkowy to wiadomość serwisowa, dostarczalna tylko wewnątrz otwartego okna; zobacz w hubie [okno obsługi klienta](/docs/guides/whatsapp/message-types#the-customer-service-window). Sprawdzenie okna kończy się przepuszczeniem, więc `202` nie jest dowodem, że okno było faktycznie otwarte w momencie wysyłki.
- **`from` musi być numerem należącym do Twojego obszaru roboczego.** Pominięcie go lub podanie numeru, który nie jest podłączonym nadawcą, jest odrzucane przed utworzeniem wysyłki.
- **URL jest statyczny dla całej wysyłki i identyczny dla każdego odbiorcy.** W tym typie nie ma zmiennej per odbiorca. Zobacz [Co zgłasza kliknięcie](#co-zgłasza-kliknięcie), aby dowiedzieć się, jak mimo to atrybucjonować kliknięcia.
- **Brak sygnału tapnięcia.** Tapnięcie przycisku linkowego nie generuje wiadomości przychodzącej ani zdarzenia webhooka. Nie buduj funkcji, która obiecuje metryki kliknięć wyłącznie na podstawie tego typu.
- **Bird sprawdza kształt URL-a, nie jego schemat.** `url` musi być adresem bezwzględnym ze schematem, ale Bird nie wymaga `https`, a Meta również nie publikuje ograniczenia schematu. Porównaj `url` nagłówka medialnego, który zgodnie z dokumentacją wymaga `https`.
- **URL nagłówka medialnego, którego WhatsApp nie może pobrać, kończy się błędem po zaakceptowaniu wysyłki.** WhatsApp pobiera zasób nagłówka w momencie wysyłki i buforuje go przez 10 minut; podpisany URL musi przetrwać dłużej niż wysyłka, a nieosiągalny URL kończy się błędem asynchronicznie, z `media_rejected` na `last_error` wiadomości.

Żadne z kontroli kształtu wymienionych w tabeli [błędów](/docs/guides/whatsapp/message-types/interactive#errors) w hubie nie może się wywołać dla tego typu: sprawdzają one wiersze listy, tablicę `buttons` lub karty karuzeli, a wiadomość `cta_url` nie ma żadnego z tych trzech elementów. Błąd kształtu, np. etykieta `text` dłuższa niż 20 znaków, wraca jako ogólny błąd walidacji żądania, a nie jeden z tych kodów. Cytat, który się nie rozwiązuje, powoduje odrzucenie żądania przed utworzeniem lub naliczeniem opłaty: `404` [`E15071`](/docs/api/errors/E15071), gdy id wskazuje wiadomość, której ten obszar roboczy nie posiada, `422` [`E15072`](/docs/api/errors/E15072), gdy wskazuje wiadomość, której nie można zacytować. Informacje o błędach, które może napotkać każda wysyłka WhatsApp, zamknięte okno, brakujący lub nieprawidłowy nadawca albo nieprawidłowy odbiorca, znajdziesz w hubie w sekcjach [błędy](/docs/guides/whatsapp/message-types/interactive#errors) i [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp).

## Następne kroki

- [Wiadomości interaktywne WhatsApp](/docs/guides/whatsapp/message-types/interactive): co łączy wszystkie sześć typów interaktywnych
- [Szablony WhatsApp](/docs/guides/whatsapp/templates): zmienna przycisku `url`, którą WhatsApp personalizuje per odbiorca
- [Wysyłanie wiadomości WhatsApp](/docs/guides/whatsapp/sending-whatsapp): koperta żądania, model `202` i bezpieczne ponawianie

## 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)