Template WhatsApp

Pengiriman WhatsApp yang dimulai oleh bisnis menggunakan template yang telah disetujui sebelumnya. Template berisi teks tetap dan variabel, sehingga setiap pengiriman hanya perlu menyertakan nilai seperti kode OTP atau nomor pesanan.

Bird menyediakan katalog terkelola, mendaftarkan isinya ke WhatsApp, dan mengirimkannya dari nomor milik Bird sendiri; slug-nya diawali dengan bird_. Workspace yang telah menghubungkan nomornya sendiri juga dapat membuat template di WhatsApp Business Account miliknya. Halaman Approved templates menampilkan setiap template yang dapat dikirim oleh workspace beserta tampilan masing-masing.

Menelusuri template di dashboard

Buka Approved templates di WhatsApp > Approved templates. Your templates berisi template yang dibuat oleh workspace ini; All templates juga mencakup katalog yang dikelola Bird. Cari berdasarkan nama atau filter berdasarkan status dan kategori, lalu beralih antara tampilan kartu dan tampilan daftar dengan tombol di samping filter.

Dalam tampilan daftar, setiap baris menampilkan kolom yang Anda perlukan untuk memilih dan mengirim template:

Status: apakah template secara keseluruhan dapat dikirim. Template katalog terkelola melaporkan active; template milik Anda sendiri melaporkan status persetujuannya. Periksa daftar bahasa untuk memastikan bahasa yang diperlukan tersedia.
Name: label tampilan, dengan slug template di bawahnya. Kirim menggunakan slug.
Languages: bahasa tempat template didaftarkan, seperti bahasa Inggris dan Belanda.
Category: authentication, utility, atau marketing. Kategori menentukan cara WhatsApp memperlakukan pesan, nomor Bird mana yang digunakan untuk mengirim template terkelola, dan, bersama negara tujuan, harga.
WABA: Bird-managed untuk template katalog. Template milik Anda sendiri menampilkan WhatsApp Business Account yang menyimpannya, dan hanya dapat dikirim dari nomor pada akun yang sama.
Updated: waktu terakhir template berubah.

Klik sebuah baris untuk membuka detail template.

Isi sebuah template

Tampilan detail menampilkan isi pesan, variabel, dan tombol dalam pratinjau bergaya WhatsApp.

Detail juga menyediakan contoh cURL untuk POST /v1/whatsapp/messages yang menggunakan host regional dan nilai contoh template. Ganti kunci API, penerima, dan nilai variabel sebelum mengirim.

Contoh ini adalah cara tercepat untuk melihat struktur yang harus dipenuhi sebuah pengiriman. Melalui API, konten yang sama berasal dari versi template (Membaca konten template).

Menampilkan daftar template dari API

GET /v1/whatsapp/templates mengembalikan katalog dengan paginasi berbasis kursor. Permintaan ini memerlukan akses baca whatsapp_management. Gunakan HTTP atau metode permintaan mentah SDK.

type Templates = { data: Array<{ slug: string; status: string }> };

const templates = await bird.request<Templates>({
  method: "GET",
  path: "/v1/whatsapp/templates",
});

templates = client.get("/v1/whatsapp/templates")

var out struct {
	Data []struct {
		Slug   string `json:"slug"`
		Status string `json:"status"`
	} `json:"data"`
}
if err := client.Get(context.Background(), "/v1/whatsapp/templates", &out); err != nil {
	log.Fatal(err)
}

$templates = $bird->get('/v1/whatsapp/templates');

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

Setiap entri mengidentifikasi template, kategorinya, dan bahasa yang tersedia. Untuk konten pesan, baca versi aktif secara terpisah.

Contoh kode

{
  "available_languages": ["en", "es", "pt-BR", "..."],
  "category": "authentication",
  "default_language": "en",
  "description": "One-time passcode",
  "id": "wat_01ky4x8e4genzb7way45txfkm1",
  "languages": {
    "en": { "status": "approved" },
    "es": { "status": "approved" },
    "pt-BR": { "status": "approved" },
    "...": "..."
  },
  "name": "bird_otp",
  "on_missing_language": "fail",
  "scope": "system",
  "slug": "bird_otp",
  "status": "active"
}

Contoh respons ini menyingkat daftar bahasa bird_otp.

Field yang menentukan keberhasilan pengiriman:

slug: handle yang digunakan dalam pengiriman. Slug template terkelola diawali dengan bird_, prefiks yang dicadangkan khusus untuknya.
waba: WhatsApp Business Account yang menyimpan bahasa-bahasa template di Meta, sekaligus akun tempat nomor pengirim harus terdaftar. Field ini tidak ada pada template terkelola karena Bird yang mengelola akunnya.
available_languages: bahasa yang dapat dikirim. Bahasa yang dijeda, dinonaktifkan, diarsipkan, atau dibatasi akan dihapus dari daftar ini.
on_missing_language: apa yang terjadi jika bahasa yang diminta tidak tersedia. Template WhatsApp yang dikelola Bird menggunakan fail, yang menolak pengiriman alih-alih menggantinya dengan bahasa lain.

Status dan status bahasa

Template yang dikelola Bird melaporkan status: active. languages.<tag>.status melaporkan status WhatsApp untuk satu bahasa, misalnya approved, paused, atau disabled.

Template yang aktif tetap bisa memiliki bahasa yang tidak tersedia. Gunakan available_languages untuk menentukan apakah suatu bahasa dapat dikirim.

Membaca konten template

Konten pesan dimiliki oleh setiap bahasa dalam versi aktif. Baca live_version_id dari template, lalu minta bahasa yang Anda perlukan:

const language = await bird.request({
  method: "GET",
  path: "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
});

language = client.get(
    "/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en"
)

var language map[string]any
if err := client.Get(context.Background(),
	"/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en",
	&language); err != nil {
	log.Fatal(err)
}

$language = $bird->get('/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en');

curl https://us1.platform.bird.com/v1/whatsapp/templates/bird_order_confirmation/versions/{version_id}/languages/en \
  -H "Authorization: Bearer $BIRD_API_KEY"

Referensi template menerima ID slug atau wat_. GET …/versions/{version_id}/languages mencantumkan bahasa-bahasa dalam versi tersebut tanpa kontennya.

Contoh kode

{
  "category": "utility",
  "components": [
    {
      "example_parameters": [
        { "name": "ref", "text": "A1B2C3D4", "type": "text" },
        { "name": "amount", "text": "USD 49.99", "type": "text" }
      ],
      "text": "Your order {{ref}} has been confirmed for a total of {{amount}}. Thanks for shopping with us.",
      "type": "body"
    }
  ],
  "language": "en",
  "status": "approved"
}

Pengiriman mengisi placeholder ini berdasarkan nama. example_parameters mengidentifikasi masing-masing placeholder. Dalam contoh ini, parameters pada pengiriman menerima kunci ref dan amount. Pada template posisional, kuncinya berupa nomor, misalnya 1, dengan dua pengecualian: kode pada template autentikasi menggunakan code, dan sufiks bernomor pada tombol url menggunakan button_url. Tombol berparameter memiliki example_parameters sendiri.

category pada bahasa adalah kategori Meta yang dipakai untuk penetapan harga. Nilainya bisa berbeda dari kategori terdaftar template jika Meta mengklasifikasikan ulang bahasa tersebut.

Daftar variables pada versi merangkum setiap placeholder beserta kunci, tipe, penanda wajib, dan batasannya. Placeholder bernama memakai namanya sebagai kunci. Placeholder posisional memakai nomornya, kecuali kode autentikasi (code) dan sufiks tombol url (button_url). parameters pada pengiriman menerima kunci-kunci ini.

Mengirim dengan template

Sebutkan template di objek template pada pengiriman dan isi variabelnya melalui parameters. Lihat Mengirim pesan WhatsApp untuk payload lengkapnya:

const msg = await bird.whatsapp.send({
  to: "+15551234567",
  template: {
    slug: "bird_otp",
    parameters: { code: "123456" },
  },
});
console.log(msg.id, msg.status);

msg = client.whatsapp.send(
    to="+15551234567",
    template="bird_otp",
    language="en",
    parameters={"code": "123456"},
)
print(msg.id, msg.status)

msg, err := client.Whatsapp.Send(context.Background(), bird.WhatsappSendParams{
	To:         "+15551234567",
	Template:   "bird_otp",
	Language:   "en",
	Parameters: map[string]any{"code": "123456"},
})
if err != nil {
	log.Fatal(err)
}
fmt.Println(msg.Id, *msg.Status)

$message = $bird->whatsapp->send(
    to: '+15551234567',
    template: 'bird_otp',
    language: 'en',
    parameters: ['code' => '123456'],
);
echo $message->getId(), ' ', $message->getStatus();

bird whatsapp send \
  --language en \
  --parameters '{"code":"123456"}' \
  --template bird_otp \
  --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": "+14155550100",
    "template": {
      "slug": "bird_otp",
      "language": "en",
      "parameters": { "code": "481920" }
    }
  }'

Mengirim berdasarkan kategori

Setiap template memiliki salah satu dari tiga kategori Meta. Kategori menentukan apa yang harus Anda lakukan agar pengiriman berhasil, sekaligus biayanya. Membuat atau menyalin template autentikasi milik Anda sendiri memerlukan bisnis terverifikasi, tetapi mengirimnya tidak: bird_otp terkelola milik Bird berada di WhatsApp Business Account milik Bird sendiri dan terkirim tanpa verifikasi dari Anda. Template marketing selalu dikirim dari WhatsApp Business Account milik Anda sendiri, melalui API Meta kedua yang dipilih Bird secara otomatis. Template utility memiliki prasyarat paling sedikit di antara ketiganya.

Template autentikasi: kode verifikasi sekali pakai, tombol salin kode, dan syarat verifikasi untuk membuatnya
Template utility: pembaruan pesanan, pengingat janji temu, dan pemberitahuan akun
Template marketing: pengiriman promosi, akun bisnis yang Anda perlukan, dan ketentuan opt-out

Langkah berikutnya

Mengirim pesan WhatsApp: payload pengiriman lengkap tempat objek template dimasukkan
Panduan template WhatsApp: aturan yang digunakan Meta untuk meninjau template
Template autentikasi: kode verifikasi sekali pakai dan syarat verifikasi bisnis untuk membuatnya
Harga WhatsApp: cara kategori dan negara tujuan menentukan harga

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Coba praktiknya dan dapatkan ringkasan implementasi

Sumber daya terkait