Jendela 24 jam & template (FAQ)

WhatsApp membagi pesan keluar menjadi dua mode: free-form (pesan biasa saat jendela percakapan masih terbuka) dan template (struktur yang harus disetujui Meta terlebih dahulu). Sebagian besar pertanyaan berulang di support pada akhirnya tentang perbedaan ini. Halaman ini FAQ singkat — bagikan link ini saat rekan atau pelanggan bertanya lagi.

Ringkasan satu kalimat

Jika pelanggan mengirim pesan ke Anda dalam 24 jam terakhir, Anda boleh kirim teks/media/interaktif biasa. Jika tidak, wajib pakai template yang sudah disetujui — lalu tunggu pelanggan membalas baru jendela 24 jam terbuka lagi.

Salah paham yang paling sering

Mengirim template tidak membuka jendela 24 jam. Template hanya sampai ke HP pelanggan; jendela baru terbuka setelah pelanggan membalas (pesan masuk dari mereka). Sebelum ada balasan, kiriman free-form (text, media, interaktif) tetap ditolak dengan outside_24h_window / Meta 131047 — meskipun template Anda sudah terkirim dan terbaca.

Apa itu jendela 24 jam?

Meta menyebutnya customer service window (kadang disebut “sesi 24 jam” atau “conversation window”). Ini timer 24 jam bergulir yang hanya dimulai saat pelanggan mengirim pesan masuk ke nomor WhatsApp Anda — bukan saat Anda mengirim template keluar.

Saat jendela terbuka:

• Anda boleh kirim pesan free-form: text, image, video, audio, document, dan sebagian besar tipe interaktif (tombol, list, reply button, dll.).
• Setiap pesan masuk baru dari pelanggan memperpanjang timer — jendela tetap terbuka 24 jam lagi sejak pesan itu.

Saat jendela tertutup (tidak ada pesan pelanggan dalam 24 jam terakhir):

• Meta menolak kiriman free-form dengan error 131047 (Re-engagement message required).
• Kirimdev menampilkan kode stabil outside_24h_window pada pesan gagal dan di webhook.

Jendela dihitung per nomor pelanggan + nomor WhatsApp Business Anda, bukan global untuk seluruh akun.

Bagaimana tahu jendela masih terbuka?

Tempat	Yang perlu dicek
Dashboard Kirimdev (Inbox)	Buka percakapan. Header chat menampilkan countdown saat jendela terbuka, atau badge “24h closed” jika sudah tertutup. Composer nonaktif untuk kiriman free-form saat tertutup.
Public API	GET /v1/{phone_number_id}/conversations/{id} memuat last_inbound_at. Jika timestamp itu kurang dari 24 jam yang lalu, jendela terbuka. Kirimdev tidak mengekspos boolean terpisah — hitung dari last_inbound_at atau tunggu Meta menerima/menolak kiriman.
Setelah kiriman gagal	Status pesan failed dengan error.code: "outside_24h_window" (Meta provider_code: 131047). Lihat Menangani kiriman gagal.

Note

last_inbound_at bernilai null sampai pelanggan mengirim minimal satu pesan ke nomor Anda. Sebelum itu jendela tertutup — kontak pertama wajib lewat template (atau pelanggan yang harus chat duluan).

Apa yang boleh dikirim saat jendela terbuka vs tertutup?

Jendela	Tipe pesan yang diizinkan	Contoh
Terbuka (pelanggan chat dalam 24 jam)	Free-form: teks, media, interaktif, voice note	Balasan support, update pesanan sebagai teks biasa, quick-reply button
Tertutup	Hanya template (type: "template")	“Pesanan Anda dikirim”, OTP, promo re-engagement, outreach pertama

Setelah Anda kirim template, jendela masih tertutup sampai pelanggan membalas. Jangan langsung lanjut dengan teks free-form — tunggu pesan masuk dulu (atau cek last_inbound_at / badge di Inbox).

Mengirim teks free-form saat jendela tertutup tidak masuk antrean diam-diam — Meta menolak dan pesan berstatus failed dengan outside_24h_window. Jangan retry payload yang sama; ganti ke template.

Apa itu message template?

Template adalah struktur pesan yang didaftarkan dan disetujui Meta sebelum bisa dikirim di luar jendela 24 jam (atau sebagai pesan pertama ke kontak baru). Template berisi:

• Header tetap (opsional — teks, gambar, video, dokumen)
• Body berparameter ({{1}}, {{2}}, atau named params)
• Footer (opsional, statis)
• Tombol (opsional — URL, quick reply, copy code, Flow)

Saat mengirim, Anda pilih name + language template lalu isi parameter runtime. Kirimdev meneruskan payload ke Meta apa adanya.

Template bukan fitur tambahan — ini satu-satunya cara mengirim pesan saat jendela tertutup. Template tidak membuka jendela; hanya balasan pelanggan yang membukanya. Setelah 24 jam tanpa balasan, Anda kirim template lagi (cara standar untuk notifikasi transaksional seperti update pengiriman).

Bagaimana cara template disetujui?

1. Buat template di Meta WhatsApp Manager, dashboard Kirimdev, atau lewat POST /v1/{phone_number_id}/templates (lihat Create templates atau Changelog create template).
2. Meta mereview (menit hingga 48 jam; kategori marketing bisa lebih lama).
3. Status menjadi approved — baru bisa dikirim. Daftar template lewat GET /v1/{phone_number_id}/templates.

Sebelum status approved, kiriman gagal dengan error terkait template (template_not_found, template_not_approved, atau Meta 132001).

Kirim template

Contoh payload untuk body saja dan komponen lanjutan. → Kirim template

Buat lewat API

Submit programatik + header gambar via URL publik. → Create templates

Broadcast skala besar

Template sama, banyak penerima — tier limit berlaku. → Resep broadcast

FAQ — skenario umum

Saya sudah kirim template. Kenapa teks free-form masih gagal?

Karena pelanggan belum membalas. Template keluar tidak membuka jendela 24 jam — hanya pesan masuk dari pelanggan yang membukanya. Setelah template terkirim, jendela tetap tertutup sampai mereka reply (tap quick reply, ketik balasan, dll.). Baru setelah itu Anda bisa kirim text / media / interaktif selama 24 jam ke depan.

Di dashboard: badge “24h closed” dan composer nonaktif = belum ada balasan. Di API: last_inbound_at belum berubah / masih lebih dari 24 jam.

Pelanggan membalas kemarin. Boleh kirim teks biasa hari ini?

Boleh, jika pesan masuk terakhir mereka kurang dari 24 jam yang lalu. Jika sudah lebih dari 24 jam, pakai template — meskipun minggu lalu Anda sempat chat panjang.

Saya sudah kirim template. Bisa langsung kirim teks free-form?

Tidak. Lihat jawaban di atas — wajib tunggu balasan pelanggan dulu. Mengirim template lalu langsung type: "text" akan gagal dengan outside_24h_window jika belum ada inbound baru.

Pesan pertama ke kontak baru — template atau teks?

Template (kecuali pelanggan chat duluan). Cold outreach dengan type: "text" gagal dengan outside_24h_window atau tidak pernah masuk jendela terbuka karena last_inbound_at masih null.

Kenapa teks di dashboard berhasil tapi API dapat 131047?

Aturan sama di semua tempat. Penyebab umum:

• Anda uji di percakapan yang jendelanya masih terbuka di dashboard, tapi integrasi API menarget kontak berbeda atau thread lama dengan last_inbound_at yang sudah kedaluwarsa.
• Selisih jam jarang jadi masalah; jendela berdasarkan timestamp server pada webhook inbound.

Bandingkan last_inbound_at pada conversation id yang persis Anda kirimi.

Apakah template sama dengan broadcast?

Tidak. Template adalah format pesan yang disetujui WhatsApp. Broadcast (di dashboard Kirimdev) adalah kampanye yang mengirim template yang sudah disetujui ke banyak penerima sekaligus. Lihat Lihat panduan Broadcast.

Marketing vs utility template — apakah beda?

Ya, untuk kebijakan dan billing. Meta menetapkan kategori (mis. marketing, utility, authentication). Template marketing review lebih ketat dan bisa wajib opt-in penerima; Kirimdev bisa mengembalikan marketing_opted_out jika kontak opt-out. Template utility / transaksional (update pesanan, reminder janji) cocok untuk alur pasca-pembelian. Pilih kategori jujur di WhatsApp Manager — template salah kategori bisa ditolak atau di-pause.

Apakah template berbayar?

Meta menagih WABA Anda sesuai aturan percakapan / template — bukan Kirimdev. Anda perlu metode pembayaran valid di Meta Business Suite. Lihat Setup pembayaran WhatsApp Business.

Kiriman gagal dengan template_params_mismatch

Jumlah atau tipe parameter tidak cocok dengan template yang disetujui (mis. template punya {{1}} dan {{2}} tapi Anda kirim satu parameter). Ambil definisi template lewat GET /v1/{phone_number_id}/templates/{name} dan samakan strukturnya. Ini bug di sisi pemanggil — perbaiki parameter sebelum retry.

Kiriman gagal dengan template_not_found / 132001

Biasanya kode bahasa salah (id vs id_ID) atau template belum approved untuk nama tersebut. Daftar bahasa yang disetujui lewat GET /v1/{phone_number_id}/templates.

Cheat sheet kode error

Gejala	Kirimdev error.code	Meta provider_code	Solusi
Free-form setelah 24 jam tanpa balasan (atau setelah template tanpa balasan)	outside_24h_window	131047	Kirim template jika perlu; tunggu pelanggan balas — baru free-form OK
Template belum approved / bahasa salah	template_not_found	132001	Cek GET .../templates; pakai name + language yang approved
Jumlah/tipe parameter salah	template_params_mismatch	bervariasi	Samakan komponen template
Billing Meta belum disetup	kegagalan terkait billing	bervariasi	Setup pembayaran

Katalog async lengkap: Menangani kiriman gagal dan Errors.

Alur yang disarankan (integrasi)

Ada pesan masuk pelanggan? ──ya──► Jendela terbuka 24 jam ──► free-form OK
        │
        tidak (atau >24 jam sejak inbound terakhir)
        │
        ▼
Kirim template approved ──► (jendela MASIH tertutup) ──► pelanggan balas ──► jendela terbuka ──► free-form OK

import { Kirim, KirimError } from '@kirimdev/sdk'

const kirim = new Kirim({ apiKey: process.env.KIRIM_KEY! })
const phone = kirim.phoneNumbers(process.env.PHONE_ID!)

try {
  await phone.messages.send({
    messaging_product: 'whatsapp',
    to: '+628123456789',
    type: 'text',
    text: { body: 'Pesanan Anda sudah dikirim.' },
  })
} catch (err) {
  if (err instanceof KirimError && err.code === 'outside_24h_window') {
    await phone.messages.send({
      messaging_product: 'whatsapp',
      to: '+628123456789',
      type: 'template',
      template: {
        name: 'order_shipped',
        language: 'id',
        components: [
          {
            type: 'body',
            parameters: [{ type: 'text', text: 'Andi' }],
          },
        ],
      },
    })
  } else {
    throw err
  }
}

Caution

Contoh di atas: setelah kirim template fallback, jangan langsung kirim teks lagi — tunggu webhook pesan masuk dari pelanggan. Untuk alur berbasis webhook, branch berdasarkan message.error.code di event message.status, bukan try/catch di POST awal.

Dokumen terkait

• Kirim teks — pesan free-form (jendela harus terbuka)
• Kirim template — referensi payload template
• Kirim OTP — template AUTHENTICATION + tombol url
• Menangani kiriman gagal — matriks retry untuk outside_24h_window
• Resep order shipped — contoh template end-to-end
• API — Daftar template

Kirim template

Panduan kiriman gagal