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 lub menu listy.
Wyślij przycisk linkowy
Ustaw interactive.type na cta_url z obiektem body_text i obiektem cta_url zawierającymi text i url przycisku:
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);msg = client.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"},
},
)
print(msg.id, msg.status)package main
import (
"context"
"fmt"
"log"
"os"
bird "github.com/messagebird/bird-sdk-go"
"github.com/messagebird/bird-sdk-go/option"
)
func main() {
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
To: "+16505551234",
From: "+13124495648",
Interactive: &bird.WhatsAppInteractiveSend{
Type: "cta_url",
BodyText: "Tap the button below to see the available dates.",
CtaUrl: &bird.WhatsAppInteractiveCtaUrlSend{Text: "See dates", Url: "https://example.com/workshops?click_id=a1b2c3"},
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)
}$interactive = (new WhatsAppMessageSendRequestInteractive())
->setType('cta_url')
->setBodyText('Tap the button below to see the available dates.')
->setCtaUrl(
(new WhatsAppInteractiveSendCtaUrl())
->setText('See dates')
->setUrl('https://example.com/workshops?click_id=a1b2c3'),
);
$message = $bird->whatsapp->send(
to: '+16505551234',
from: '+13124495648',
interactive: $interactive,
);
echo $message->getId(), ' ', $message->getStatus();bird whatsapp send \
--from +13124495648 \
--interactive '{"body_text":"Tap the button below to see the available dates.","cta_url":{"text":"See dates","url":"https://example.com/workshops?click_id=a1b2c3"},"type":"cta_url"}' \
--to +16505551234{
"name": "whatsapp_send",
"arguments": {
"from": "+13124495648",
"interactive": {
"body_text": "Tap the button below to see the available dates.",
"cta_url": {
"text": "See dates",
"url": "https://example.com/workshops?click_id=a1b2c3"
},
"type": "cta_url"
},
"to": "+16505551234"
}
}curl -X POST "https://{region}.platform.bird.com/v1/whatsapp/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"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"
}
}
}'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:
Przykład kodu
{
"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, 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, 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:
Przykład kodu
"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 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. 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, 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 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, gdy id wskazuje wiadomość, której ten obszar roboczy nie posiada, 422 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 i Wysyłanie wiadomości WhatsApp.
Następne kroki
- Wiadomości interaktywne WhatsApp: co łączy wszystkie sześć typów interaktywnych
- Szablony WhatsApp: zmienna przycisku url, którą WhatsApp personalizuje per odbiorca
- Wysyłanie wiadomości WhatsApp: koperta żądania, model 202 i bezpieczne ponawianie
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikConnecting WhatsApp to Bird: from buying a number to a live channelZrozum koncepcjęWhat is the 24-hour customer service window on WhatsApp?Użyj narzędziaWhatsApp message builderPoznaj możliwościWhatsApp
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy