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

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

Dotknięcie otwiera adres w przeglądarce odbiorcy i nic nie wraca do Ciebie przez API. Dotknięcie przycisku linku nie jest zdarzeniem interactive_reply: mapper wiadomości przychodzących, który tworzy interactive_reply, obsługuje tylko dotknięcie przycisku odpowiedzi i dotknięcie wiersza listy, a link cta_url nie ma odpowiadającego kształtu przychodzącego. Możesz śledzić zdarzenia statusu wiadomości wychodzących (whatsapp.sent, whatsapp.delivered i whatsapp.read), ale read_at informuje, że wiadomość została otwarta, a nie że przycisk został dotknięty. Nie ma zdarzenia kliknięcia, znacznika czasu ani sygnału dotknię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

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy