# WhatsApp-Link-Buttons

Ein Link-Button platziert einen antippbaren Button unter einer WhatsApp-Nachricht, der eine URL im Browser des Empfängers öffnet. Verwenden Sie ihn, wenn der nächste Schritt im Web liegt, etwa eine Checkout-Seite oder eine Liste von Workshop-Terminen, und nicht im Chat selbst. Für eine Auswahl, die der Empfänger innerhalb von WhatsApp beantwortet, verwenden Sie stattdessen [Antwort-Buttons](/docs/guides/whatsapp/message-types/interactive/reply-buttons) oder [Listenmenüs](/docs/guides/whatsapp/message-types/interactive/list-menus).

## Einen Link-Button senden

Setzen Sie `interactive.type` auf `cta_url` mit einem `body_text`- und einem `cta_url`-Objekt, das `text` und `url` des Buttons enthält:

**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](/de-de/dokumentation/guides/whatsapp/message-types/interactive/cta-url-buttons.ts.md) · [Python](/de-de/dokumentation/guides/whatsapp/message-types/interactive/cta-url-buttons.py.md) · [Go](/de-de/dokumentation/guides/whatsapp/message-types/interactive/cta-url-buttons.go.md) · [PHP](/de-de/dokumentation/guides/whatsapp/message-types/interactive/cta-url-buttons.php.md) · [CLI](/de-de/dokumentation/guides/whatsapp/message-types/interactive/cta-url-buttons.cli.md) · [MCP](/de-de/dokumentation/guides/whatsapp/message-types/interactive/cta-url-buttons.mcp.md) · [cURL](/de-de/dokumentation/guides/whatsapp/message-types/interactive/cta-url-buttons.curl.md)

`from` ist bei jeder Service-Nachricht erforderlich: eine Nummer, die Ihr Workspace besitzt, keine von Bird verwaltete. Die vollständige Struktur fügt einen optionalen Header, Footer und ein Zitat einer früheren Nachricht hinzu:

```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` zitiert eine frühere Nachricht in derselben Konversation. Unter [Nachricht zitieren, um eine Antwort zuzuordnen](/docs/guides/whatsapp/message-types/interactive#quoting-a-message-to-correlate-a-reply) im Hub erfahren Sie, wie die Auflösung funktioniert und was sie übersehen kann.

Dieser Typ sendet genau einen `cta_url`-Button und kann `buttons`, `list` oder `cards` nicht zusätzlich enthalten. Im Abschnitt [Buttons](/docs/guides/whatsapp/message-types/interactive#buttons) des Hubs finden Sie die gemeinsame Button-Struktur, die auch der Link-Button einer Karussell-Karte wiederverwendet.

## Header und Footer

Ein Header ist optional und hat eine von vier Formen:

```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" }
```

Ein Media-Header (`image`, `video` oder `document`) übergibt seine Datei als öffentliche `https`-URL, die WhatsApp beim Senden abruft, statt als hochgeladenes Media-Handle. `footer_text` ist optional und fügt eine Zeile unter dem Button hinzu.

## Grenzen

| Feld                   | Grenze                            |
| ---------------------- | --------------------------------- |
| `cta_url`-Buttons      | genau einer                       |
| `cta_url.text` (Label) | erforderlich, 1 bis 20 Zeichen    |
| `cta_url.url`          | erforderlich, 1 bis 2.000 Zeichen |
| `body_text`            | erforderlich, 1 bis 1.024 Zeichen |
| `footer_text`          | optional, 1 bis 60 Zeichen        |
| `header.text`          | 1 bis 60 Zeichen                  |

Die 2.000-Zeichen-Grenze für `url` stammt von Bird: Meta veröffentlicht kein Längenlimit für dieses Feld. `url` prüft außerdem `format: uri`, eine absolute Adresse mit Schema, aber Bird prüft nicht, welches Schema: Eine `http://`-Adresse besteht die Validierung von Bird, und Meta ist die einzige Instanz, die entscheidet, ob sie zugestellt wird.

## Was ein Klick zurückmeldet

Ein Tippen öffnet die Adresse im Browser des Empfängers, und über die API kommt nichts an Sie zurück. Das Tippen auf einen Link-Button ist kein `interactive_reply`: Der Inbound-Mapper, der `interactive_reply` erzeugt, verarbeitet nur das Tippen auf einen Antwort-Button und eine Listenzeile, und ein `cta_url`-Link hat keine entsprechende Inbound-Struktur. Was Sie sehen, ist der normale ausgehende Lebenszyklus – die Statusmeldungen `sent`, `delivered` und `read` der Nachricht –, aber `read_at` sagt Ihnen, dass die Nachricht geöffnet wurde, nicht dass der Button angetippt wurde. Es gibt kein Klick-Event, keinen Zeitstempel und kein empfängerspezifisches Tipp-Signal von WhatsApp oder von Bird.

Zwei Wege, um eine Zuordnung zu erhalten, da der Versand selbst sie Ihnen nicht liefert:

- **Instrumentieren Sie die Zielseite.** Der einzige verfügbare Klicknachweis liegt auf Ihrem eigenen Zielserver, anhand der URL, die Sie ausgegeben haben.
- **Variieren Sie die URL selbst, pro Empfänger.** Die `url`, die Sie senden, ist ein Literal-String: Bird speichert sie und gibt sie unverändert an Meta weiter, ohne Ersetzung und ohne Variablensyntax. Sie ist für jeden Empfänger eines Versands identisch. Empfängerspezifische Zuordnung bedeutet daher, einen eigenen Query-Parameter zu erzeugen, etwa `?click_id=<value>`, und pro Empfänger einen `POST /v1/whatsapp/messages`-Aufruf auszuführen. Der Endpunkt nimmt bereits einen einzelnen `to` pro Aufruf entgegen, sodass dies Buchhaltung auf Ihrer Seite ist und kein fehlendes API-Feature.

Eine dritte Option liegt ganz außerhalb dieses Typs: Ein [Template](/docs/guides/whatsapp/templates) mit einer `url`-Button-Variable wird von WhatsApp selbst pro Empfänger personalisiert, bereitgestellt über die `button`-Komponente des Versands. Diese Variable muss am Ende der Adresse stehen, geschrieben als `{{1}}`, sodass sie ein abschließendes Pfadsegment oder einen Query-Wert variieren kann, aber niemals den Host oder die Mitte der URL. Der Kompromiss: Ein Template bietet empfängerspezifische URLs und Zustellung außerhalb des Kundenservice-Fensters, erfordert aber Metas Review und eine feste genehmigte Struktur. Ein `cta_url`-Versand bietet dagegen freiformatigen, reviewfreien Versand innerhalb eines offenen Fensters mit einer URL, die Sie selbst variieren.

## Grenzen und Sonderfälle

- **Das Kundenservice-Fenster muss offen sein.** Ein Link-Button ist eine Service-Nachricht und kann nur innerhalb eines offenen Fensters zugestellt werden; siehe [Kundenservice-Fenster](/docs/guides/whatsapp/message-types#the-customer-service-window) im Hub. Die Fensterprüfung schlägt offen fehl, sodass ein `202` kein Beweis dafür ist, dass das Fenster beim Versand tatsächlich offen war.
- **`from` muss eine Nummer sein, die Ihr Workspace besitzt.** Wird sie weggelassen oder eine Nummer angegeben, die kein verbundener Sender ist, wird der Versand vor der Erstellung abgelehnt.
- **Die URL ist für den gesamten Versand statisch und für jeden Empfänger identisch.** Es gibt keine empfängerspezifische Variable bei diesem Typ. Siehe [Was ein Klick zurückmeldet](#was-ein-klick-zurückmeldet) für Möglichkeiten, Klicks dennoch zuzuordnen.
- **Kein Tipp-Signal, niemals.** Das Tippen auf einen Link-Button erzeugt keine Inbound-Nachricht und kein Webhook-Event. Bauen Sie kein Feature, das Klickmetriken allein von diesem Typ verspricht.
- **Bird prüft die Form der URL, nicht ihr Schema.** `url` muss eine absolute Adresse mit Schema sein, aber Bird verlangt kein `https`, und Meta veröffentlicht ebenfalls keine Schema-Einschränkung. Vergleichen Sie das mit `url` eines Media-Headers, für das `https` dokumentiert als erforderlich ist.
- **Eine Media-Header-URL, die WhatsApp nicht abrufen kann, schlägt nach Annahme des Versands fehl.** WhatsApp ruft das Header-Asset beim Senden ab und cacht es 10 Minuten lang; eine signierte URL muss den Versand überdauern, und eine nicht erreichbare URL schlägt asynchron fehl, mit `media_rejected` im `last_error` der Nachricht.

Keine der Strukturprüfungen, die die [Fehlertabelle](/docs/guides/whatsapp/message-types/interactive#errors) des Hubs auflistet, kann bei diesem Typ ausgelöst werden: Sie prüfen die Zeilen einer Liste, ein `buttons`-Array oder die Karten eines Karussells, und eine `cta_url`-Nachricht hat keine dieser drei Strukturen. Ein Formfehler, etwa ein `text`-Label mit mehr als 20 Zeichen, wird als generischer Request-Validierungsfehler zurückgegeben und nicht als einer dieser Codes. Ein Zitat, das sich nicht auflösen lässt, lässt den Request fehlschlagen, bevor etwas erstellt oder berechnet wird: `404` [`E15071`](/docs/api/errors/E15071), wenn die ID keine Nachricht benennt, die dieser Workspace besitzt, `422` [`E15072`](/docs/api/errors/E15072), wenn sie eine benennt, die nicht zitiert werden kann. Für Fehler, die jeder WhatsApp-Versand auslösen kann – ein geschlossenes Fenster, ein fehlender oder ungültiger Sender oder ein ungültiger Empfänger –, siehe [Fehler](/docs/guides/whatsapp/message-types/interactive#errors) und [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp) im Hub.

## Nächste Schritte

- [Interaktive WhatsApp-Nachrichten](/docs/guides/whatsapp/message-types/interactive): was alle sechs interaktiven Typen gemeinsam haben
- [WhatsApp-Templates](/docs/guides/whatsapp/templates): für eine `url`-Button-Variable, die WhatsApp pro Empfänger personalisiert
- [WhatsApp-Nachrichten senden](/docs/guides/whatsapp/sending-whatsapp): der Request-Envelope, das `202`-Modell und sicheres erneutes Versuchen

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