Wyślij pierwszą wiadomość WhatsApp

Wyślij wiadomość WhatsApp na swój telefon za pomocą Bird WhatsApp, a następnie odczytaj ją, aby potwierdzić dostarczenie. Wiadomości inicjowane przez firmę wymagają zatwierdzonego szablonu. Ten przewodnik wysyła wiadomość z zarządzanego katalogu szablonów Bird (np. bird_delivery_update lub bird_otp), który korzysta ze współdzielonego nadawcy WhatsApp zarządzanego przez Bird. Nie musisz wcześniej podłączać konta WhatsApp Business Account ani rejestrować numeru.

Zanim zaczniesz, upewnij się, że portfel Twojej organizacji ma środki. Wysyłki szablonów WhatsApp są opłacane z portfela, a Bird odrzuca wysyłkę, której saldo nie pokrywa, zwracając 402 WalletInsufficientBalance. Doładowanie opisuje strona Metody płatności i portfel.

1. Utwórz klucz API

W panelu przejdź do Platform tools > API keys i utwórz klucz z zakresem whatsapp:write, który obejmuje wysyłanie i odczytywanie wiadomości. Klucze są przypisane do regionu i wyglądają jak bk_us1_... lub bk_eu1_.... Region w prefiksie wskazuje, który host API wywołać: https://us1.platform.bird.com lub https://eu1.platform.bird.com.

Strona API Keys w panelu Bird z listą kluczy, ich zamaskowanym prefiksem, zakresami i czasem ostatniego użycia

Pełny klucz jest wyświetlany tylko raz, podczas tworzenia. Skopiuj go w bezpieczne miejsce, a następnie wyeksportuj na potrzeby przykładów cURL:

Przykład kodu

export BIRD_API_KEY="bk_us1_..."

2. Wyślij wiadomość z szablonu

Wyślij na swój telefon zatwierdzony szablon bird_delivery_update z zarządzanego katalogu Bird albo użyj bird_otp, aby wysłać jednorazowy kod weryfikacyjny. Nazwy zarządzanych szablonów zaczynają się od bird_, a wiadomości są wysyłane ze współdzielonego numeru Bird, więc pomiń from. Zainstaluj Bird SDK dla swojego języka, korzystając z przewodnika SDK. Jeśli używasz karty Bird CLI, najpierw je zainstaluj (curl -fsSL https://cli.bird.com/install.sh | sh) i uwierzytelnij się z uprawnieniami do zapisu (bird auth login --scope whatsapp:write).

W kartach SDK zastąp przykładowy klucz API, a +15551234567 zastąp swoim numerem komórkowym w formacie E.164. CLI korzysta z Twojego logowania, a karta cURL używa BIRD_API_KEY.

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_delivery_update",
    components: [
      {
        type: "body",
        parameters: [
          { type: "text", name: "ref", text: "A1B2C3D4" },
          { type: "text", name: "date", text: "10 Jul 2026" },
        ],
      },
    ],
  },
});

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.send(
            to="+15551234567",
            template="bird_delivery_update",
            components=[
                {
                    "type": "body",
                    "parameters": [
                        {"type": "text", "name": "ref", "text": "A1B2C3D4"},
                        {"type": "text", "name": "date", "text": "10 Jul 2026"},
                    ],
                }
            ],
        )
        print(message.id, message.status)
    except APIError as err:
        print("send failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
		To:       "+15551234567",
		Template: "bird_delivery_update",
		Components: []bird.WhatsAppMessageTemplateComponent{{
			Type: "body",
			Parameters: &[]bird.WhatsAppMessageTemplateComponentParameter{
				{Type: "text", Name: bird.String("ref"), Text: bird.String("A1B2C3D4")},
				{Type: "text", Name: bird.String("date"), Text: bird.String("10 Jul 2026")},
			},
		}},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponent;
use MessageBird\Wire\Model\WhatsAppMessageTemplateComponentParameter;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_delivery_update',
    components: [
        (new WhatsAppMessageTemplateComponent())
            ->setType('body')
            ->setParameters([
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('ref')->setText('A1B2C3D4'),
                (new WhatsAppMessageTemplateComponentParameter())->setType('text')->setName('date')->setText('10 Jul 2026'),
            ]),
    ],
);

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp send \
  --components '[{"parameters":[{"name":"ref","text":"A1B2C3D4","type":"text"},{"name":"date","text":"10 Jul 2026","type":"text"}],"type":"body"}]' \
  --template bird_delivery_update \
  --to +15551234567

curl -X POST https://us1.platform.bird.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+15551234567",
    "template": {
      "slug": "bird_delivery_update",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "name": "ref", "text": "A1B2C3D4" },
            { "type": "text", "name": "date", "text": "10 Jul 2026" }
          ]
        }
      ]
    }
  }'

Jeśli Twój klucz zaczyna się od bk_eu1_, wywołaj zamiast tego https://eu1.platform.bird.com.

API odpowiada kodem 202 Accepted i utworzoną wiadomością. Jej id zaczyna się od wam_, a jej status ma wartość accepted: Bird przyjął wiadomość i dostarcza ją asynchronicznie. Zachowaj id na potrzeby następnego kroku.

3. Sprawdź status dostarczenia

Pobierz wiadomość według jej identyfikatora wam_. Zastąp WHATSAPP_MESSAGE_ID wartością id z kroku 2, a przykładowy klucz API w zakładkach SDK zastąp własnym:

import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({ apiKey: "bk_XXXXXXXXXXXXXXXXXXXXXXXX" });

const msg = await bird.whatsapp.get("WHATSAPP_MESSAGE_ID");

console.log(msg.id, msg.status);

from bird import APIError, Bird

with Bird(api_key="bk_XXXXXXXXXXXXXXXXXXXXXXXX") as client:
    try:
        message = client.whatsapp.get("WHATSAPP_MESSAGE_ID")
        print(message.id, message.status)
    except APIError as err:
        print("read failed:", err)

package main

import (
	"context"
	"fmt"
	"log"

	bird "github.com/messagebird/bird-sdk-go"
	"github.com/messagebird/bird-sdk-go/option"
)

func main() {
	client, err := bird.NewClient(option.WithAPIKey("bk_XXXXXXXXXXXXXXXXXXXXXXXX"))
	if err != nil {
		log.Fatal(err)
	}

	msg, err := client.Whatsapp.Get(context.Background(), "WHATSAPP_MESSAGE_ID")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(msg.Id, *msg.Status)
}

<?php

declare(strict_types=1);

require __DIR__ . '/../vendor/autoload.php';

use MessageBird\Bird;

$bird = new Bird('bk_XXXXXXXXXXXXXXXXXXXXXXXX');

$message = $bird->whatsapp->get('WHATSAPP_MESSAGE_ID');

echo $message->getId(), ' ', $message->getStatus(), "\n";

bird whatsapp get WHATSAPP_MESSAGE_ID

curl https://us1.platform.bird.com/v1/whatsapp/messages/WHATSAPP_MESSAGE_ID \
  -H "Authorization: Bearer $BIRD_API_KEY"

Pole status informuje, na jakim etapie jest wiadomość:

accepted: Bird przyjął wiadomość i przygotowuje się do przekazania jej do WhatsApp.
sent: WhatsApp zaakceptował wiadomość, a sent_at zapisuje, kiedy to nastąpiło.
delivered: WhatsApp potwierdził dostarczenie na urządzenie odbiorcy, a delivered_at zapisuje, kiedy to nastąpiło. Gdy odbiorca przeczyta wiadomość, ustawiane jest read_at, a status pozostaje delivered.
failed lub rejected: wiadomość nie dotarła do telefonu. last_error podaje przyczynę, a Zdarzenia statusu wiadomości zawierają listę kodów błędów.

Odpytuj API, dopóki status nie przestanie mieć wartości accepted ani sent, albo zasubskrybuj webhooki WhatsApp, aby otrzymywać każdą zmianę statusu dostarczenia i odczytu (whatsapp.sent, whatsapp.delivered, whatsapp.read, whatsapp.failed). Współdzielone numery zarządzane przez Bird służą tylko do wysyłki i nie przekazują odpowiedzi przychodzących do Twojego obszaru roboczego; aby otrzymywać odpowiedzi, podłącz własny numer. Każda wiadomość pojawia się też na stronie Messages wraz z osią czasu zdarzeń.

Napraw nieudaną wysyłkę

402 WalletInsufficientBalance: środki w portfelu nie pokrywają kosztu wiadomości. Doładuj portfel, a następnie wyślij ponownie.
403 InsufficientScope: klucz API nie ma zakresu whatsapp. Zmień zakresy klucza lub utwórz klucz z zakresem whatsapp:write.
422 WhatsAppInvalidRecipient: numer to nie jest prawidłowym numerem telefonu w formacie E.164. Sprawdź początkowy znak +, kod kraju i cyfry numeru abonenta.

Następne kroki

Wysyłanie wiadomości WhatsApp: wysyłaj szablony i dowolne wiadomości serwisowe w 24-godzinnym oknie obsługi klienta.
Szablony WhatsApp: przeglądaj zarządzany katalog (bird_otp, bird_delivery_update i inne) lub utwórz własne szablony.
Połącz numer telefonu: użyj własnego konta WhatsApp Business Account i numeru nadawcy, aby Twój obszar roboczy mógł także odbierać przychodzące odpowiedzi.
Webhooki WhatsApp: odbieraj potwierdzenia doręczenia i odczytu (oraz wiadomości przychodzące, gdy używasz własnego połączonego numeru).
Dokumentacja WhatsApp API: pełny schemat żądań i odpowiedzi.

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

Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy