Kirim WhatsApp Otomatis dari PHP dengan Fonnte API: Notifikasi, Webhook Status, dan Jebakannya

Kirim WhatsApp otomatis dari PHP dengan Fonnte API: notifikasi, webhook status, dan retry aman

Pernah kirim paket lewat kurir lalu melihat status “paket sudah masuk gudang”? Status itu belum berarti paket sampai ke tangan penerima. Masih ada perjalanan dari gudang ke kota tujuan, lalu ke kurir terakhir. Hal yang sama berlaku saat Anda memakai Fonnte API PHP untuk mengirim WhatsApp otomatis. Respons "status": true hanya berarti Fonnte menerima pesan Anda, bukan pesan itu sudah muncul di HP pelanggan.

Di tutorial ini kami membangun pengirim notifikasi WhatsApp dari PHP murni dengan cURL, persis pola yang kami jalankan di aplikasi billing ISP. Selain itu, kita membahas token per tenant, normalisasi nomor 08 ke 62, retry yang aman, webhook status untuk tahu pesan benar-benar sampai, dan alternatif tanpa API memakai link wa.me. Semua kode sudah kami uji di server uji terhadap Fonnte tiruan (mock) sehingga tidak ada WhatsApp sungguhan yang terkirim. Namun, angka statistik dan log webhook di artikel ini berasal dari sistem produksi kami, dengan nomor dan ID yang kami sensor.

Diagram alur Fonnte API PHP: aplikasi kirim ke endpoint send, WhatsApp mengantar ke HP, webhook status kembali ke wa_logs
Alur lengkap: request keluar lewat /send, kabar antar kembali lewat webhook.

Cara Kerja Fonnte API PHP Secara Singkat

Fonnte adalah gateway WhatsApp tidak resmi. Anda menautkan nomor WhatsApp sebagai perangkat tertaut (linked device), lalu Fonnte memberi token untuk perangkat itu. Kemudian aplikasi PHP cukup memanggil endpoint HTTP dengan header Authorization berisi token tersebut. Berikut endpoint yang kami pakai sehari-hari.

Endpoint / fiturFungsiCatatan penting
POST /sendKirim pesan ke satu atau banyak nomorField target, message, countryCode, opsional delay
POST /deviceCek status perangkat dan sisa kuotaField device_status (connect/disconnect) dan quota
POST /qrAmbil QR untuk menautkan perangkatBalas device already connect bila sudah tertaut
Webhook Message StatusFonnte memanggil URL Anda saat status pesan berubahSatu-satunya cara resmi tahu pesan sampai, karena API cek status sudah deprecated

Fonnte tidak menyediakan API riwayat pengiriman. Oleh karena itu, aplikasi Anda wajib mencatat sendiri setiap kiriman ke database. Webhook nanti memperbarui catatan ini.

Persiapan: Tabel Token per Tenant dan Log Pesan

Aplikasi billing kami melayani banyak ISP (tenant). Setiap tenant memakai nomor WhatsApp dan token Fonnte miliknya sendiri, jadi token tidak boleh hidup di file konfigurasi global. Kami menyimpannya di tabel wa_settings, lalu semua kiriman masuk ke wa_logs.

CREATE TABLE wa_settings (
  tenant_id    INT UNSIGNED PRIMARY KEY,
  fonnte_token VARCHAR(100) NOT NULL,
  delay        VARCHAR(20)  NOT NULL DEFAULT '60-180',
  aktif        TINYINT(1)   NOT NULL DEFAULT 1
);

CREATE TABLE wa_logs (
  id              BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  tenant_id       INT UNSIGNED NOT NULL,
  event           VARCHAR(40)  NOT NULL,
  phone           VARCHAR(20)  NOT NULL,
  status          ENUM('sent','delivered','read','failed') NOT NULL,
  fonnte_id       VARCHAR(64)  NULL,
  fonnte_state_id VARCHAR(64)  NULL,
  error           VARCHAR(255) NULL,
  created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
  KEY idx_fonnte_id (fonnte_id),
  KEY idx_state_id (fonnte_state_id)
);

Kolom delay menyimpan jeda anti-spam dalam detik, misalnya 60-180 untuk jeda acak. Sementara itu, kolom fonnte_id dan fonnte_state_id menjadi jembatan ke webhook. Kita membahas keduanya di bagian webhook. Terakhir, dua index di bawah tabel membuat pencarian dari webhook tetap cepat walaupun log sudah berisi ribuan baris.

Normalisasi Nomor 08 ke 62

Data pelanggan hampir selalu berantakan. Di billing kami, dari 3.410 pesan yang tercatat, format nomor yang masuk bermacam-macam: 2.342 sudah berawalan 62, 1.022 berawalan 08, 24 berawalan +62, dan 18 baris hanya berisi tanda strip “-” karena operator malas mengosongkan kolom. Karena itu, kita butuh satu fungsi yang merapikan semuanya sebelum memanggil API.

<?php
function normalisasi_nomor(string $nomor): ?string
{
    $angka = preg_replace('/\D/', '', $nomor); // buang +, spasi, strip, titik

    if (str_starts_with($angka, '0')) {
        $angka = '62' . substr($angka, 1);     // 0812... jadi 62812...
    } elseif (str_starts_with($angka, '8')) {
        $angka = '62' . $angka;                // 812... jadi 62812...
    }

    // HP Indonesia: 628 + 7 s.d. 11 digit. Selain itu tolak.
    if (!preg_match('/^628\d{7,11}$/', $angka)) {
        return null;
    }
    return $angka;
}

Pertama, preg_replace membuang semua karakter selain angka. Kemudian awalan 0 berganti menjadi 62, dan nomor yang langsung mulai dari 8 mendapat tambahan 62. Akhirnya, regex terakhir menolak apa pun yang bukan pola HP Indonesia. Hasil uji fungsi ini terlihat di tabel berikut.

InputHasil
0812-3456-78906281234567890
+62 812 3456 78906281234567890
81234567862812345678
-, string kosong, 0812null (tolak)
021-555-1234 (telepon rumah)null (tolak)

Mengembalikan null lebih baik daripada menebak. Jika fungsi asal menambah 62 di depan tanda strip, Fonnte tetap menolak dan kuota Anda bisa ikut terbuang.

Membuat Kelas FonnteClient dengan cURL

Sekarang kita membungkus semua panggilan HTTP ke dalam satu kelas. Dengan begitu, controller tidak perlu tahu detail cURL, dan Anda cukup mengganti URL dasar saat pengujian. Kode kelas ini cukup panjang, jadi kami memecahnya menjadi dua bagian. Simpan keduanya berurutan dalam satu file FonnteClient.php.

Bagian 1: Request dan Retry

<?php
require_once __DIR__ . '/normalisasi.php';

class FonnteClient
{
    // Hanya error yang PASTI terjadi sebelum request sampai ke Fonnte.
    private const ERRNO_AMAN_DIULANG = [CURLE_COULDNT_RESOLVE_HOST, CURLE_COULDNT_CONNECT];

    public array $lastResponse = [];
    public string $lastError = '';

    public function __construct(
        private string $token,
        private string $baseUrl = 'https://api.fonnte.com',
        private int $maxPercobaan = 3
    ) {}

    private function post(string $path, array $fields): ?array
    {
        for ($ke = 1; $ke <= $this->maxPercobaan; $ke++) {
            $ch = curl_init($this->baseUrl . $path);
            curl_setopt_array($ch, [
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_POST           => true,
                CURLOPT_POSTFIELDS     => http_build_query($fields),
                CURLOPT_HTTPHEADER     => ['Authorization: ' . $this->token],
                CURLOPT_CONNECTTIMEOUT => 5,
                CURLOPT_TIMEOUT        => 20,
            ]);
            $body  = curl_exec($ch);
            $errno = curl_errno($ch);
            $error = curl_error($ch);

            if ($errno && in_array($errno, self::ERRNO_AMAN_DIULANG, true) && $ke < $this->maxPercobaan) {
                error_log("Fonnte percobaan $ke gagal ($error), ulangi");
                usleep(500000 * 2 ** ($ke - 1)); // 0,5 dtk lalu 1 dtk
                continue;
            }
            if ($errno) {
                $this->lastError = "cURL error $errno: $error";
                return null;
            }

            $json = json_decode((string) $body, true);
            if (!is_array($json)) {
                $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
                $this->lastError = "Respons bukan JSON (HTTP $code)";
                return null;
            }
            return $this->lastResponse = $json;
        }
        return null;
    }

Method post() mengirim form biasa dengan header token. Selain itu, ia membatasi waktu koneksi 5 detik dan total 20 detik, sehingga halaman billing tidak ikut macet saat Fonnte lambat. Retry hanya terjadi untuk dua jenis error, dan alasannya kita bahas di bagian berikutnya. Perhatikan juga bahwa kode tidak memanggil curl_close(). Sejak PHP 8.0 fungsi itu tidak berefek, dan PHP 8.5 menandainya deprecated.

Bagian 2: Kirim Pesan dan Cek Perangkat

    public function send(string $nomor, string $pesan, string $delay = ''): bool
    {
        $this->lastResponse = [];
        $target = normalisasi_nomor($nomor);
        if ($target === null) {
            $this->lastError = 'Nomor HP tidak valid';
            return false;
        }

        $fields = ['target' => $target, 'message' => $pesan, 'countryCode' => '62'];
        if ($delay !== '' && $delay !== '0') {
            $fields['delay'] = $delay; // contoh "60-180" = jeda acak 60 s.d. 180 detik
        }

        $res = $this->post('/send', $fields);
        if ($res === null) {
            return false;
        }
        if (($res['status'] ?? false) !== true) {
            $this->lastError = $res['reason'] ?? 'Fonnte menolak pesan';
            return false;
        }
        return true;
    }

    public function lastId(): ?string
    {
        $id = $this->lastResponse['id'] ?? null;
        return is_array($id) ? implode(',', $id) : ($id === null ? null : (string) $id);
    }

    public function device(): ?array
    {
        $res = $this->post('/device', []);
        if ($res !== null && empty($res['status'])) {
            $this->lastError = $res['reason'] ?? 'Gagal membaca device';
            return null;
        }
        return $res;
    }
}

Method send() menolak nomor rusak sebelum menyentuh jaringan. Kemudian ia membaca field status dan reason dari respons. Fonnte mengembalikan id berupa array, misalnya ["164192533"], sehingga lastId() mengubahnya menjadi string. Terakhir, device() berguna untuk kartu “Status & Kuota WA” di dashboard tenant.

Retry yang Aman: Kapan Boleh Mengulang?

Retry terdengar sepele, padahal ini bagian paling berbahaya. Jika request sudah sampai ke Fonnte tetapi responsnya hilang di jalan, mengulang request berarti pelanggan menerima pesan dua kali. Lebih buruk lagi, pesan ganda membuat nomor Anda terlihat seperti spammer di mata WhatsApp.

Diagram keputusan retry Fonnte API PHP: ulangi hanya untuk DNS gagal dan koneksi ditolak, jangan untuk timeout dan status false
Hanya error sebelum request terkirim yang aman untuk retry otomatis.

Oleh karena itu, kelas di atas hanya mengulang errno 6 (DNS gagal) dan errno 7 (koneksi gagal). Pada kedua kasus itu request pasti belum sampai ke Fonnte. Sebaliknya, timeout (errno 28) bisa terjadi setelah Fonnte memproses pesan, jadi kita mencatatnya sebagai gagal dan membiarkan operator memutuskan. Begitu pula jawaban "status": false seperti invalid token. Mengulang tidak akan menyembuhkan token yang salah.

Contoh nyatanya terjadi pada 12 Oktober 2026. Resolver DNS server billing kami sempat gagal, dan wa_logs mencatat empat pesan gagal dengan error Could not resolve host: api.fonnte.com. Kode lama tidak punya retry. Dengan kelas baru, gangguan DNS sesaat seperti itu tertutup oleh dua percobaan ulang dengan jeda 0,5 dan 1 detik.

Kirim Notifikasi per Tenant dan Catat ke wa_logs

Fungsi berikut menjadi satu-satunya pintu kirim WA di aplikasi. Ia mengambil token tenant, memilih jeda, mengirim, lalu mencatat hasilnya apa pun yang terjadi.

<?php
require_once __DIR__ . '/FonnteClient.php';

// Pesan yang ditunggu orang di depan layar: kirim tanpa jeda.
const EVENT_SEGERA = ['otp_login', 'invoice_paid'];

function kirim_wa(PDO $db, int $tenantId, string $event, string $nomor, string $pesan): bool
{
    $st = $db->prepare('SELECT fonnte_token, delay FROM wa_settings WHERE tenant_id = ? AND aktif = 1');
    $st->execute([$tenantId]);
    $set = $st->fetch();

    $ok = false;
    $id = null;
    $error = 'WhatsApp tenant belum aktif';

    if ($set) {
        $wa    = new FonnteClient($set['fonnte_token'], FONNTE_URL);
        $delay = in_array($event, EVENT_SEGERA, true) ? '' : $set['delay'];
        $ok    = $wa->send($nomor, $pesan, $delay);
        $id    = $wa->lastId();
        $error = $ok ? null : $wa->lastError;
    }

    $log = $db->prepare('INSERT INTO wa_logs (tenant_id, event, phone, status, fonnte_id, error)
                         VALUES (?, ?, ?, ?, ?, ?)');
    $log->execute([$tenantId, $event, $nomor, $ok ? 'sent' : 'failed', $id, $error]);
    return $ok;
}

Semua query memakai prepared statement, jadi aman dari SQL injection. Selain itu, perhatikan konstanta EVENT_SEGERA. Parameter delay di Fonnte menahan setiap pesan, bukan hanya memberi jarak antar pesan dalam satu batch. Akibatnya, OTP dan konfirmasi bayar harus lewat tanpa jeda, sedangkan pengingat tagihan massal tetap memakai jeda anti-ban.

Uji Tanpa Kirim WA Sungguhan: Fonnte Tiruan

Menguji langsung ke Fonnte berarti memotong kuota dan mengganggu nomor orang. Karena itu, kami membuat server tiruan kecil yang meniru bentuk respons Fonnte. Server ini juga meniru dua penolakan yang paling sering kami temui di produksi.

<?php
// Fonnte tiruan untuk uji lokal: php -S 127.0.0.1:8099 mock-fonnte.php
header('Content-Type: application/json');
$token = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
$path  = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
file_put_contents(__DIR__ . '/mock.log', date('H:i:s') . " $path " . json_encode($_POST) . "\n", FILE_APPEND);

if ($token === 'token-mati') {
    exit(json_encode(['reason' => 'request invalid on disconnected device', 'status' => false]));
}
if ($token !== 'token-uji') {
    exit(json_encode(['reason' => 'invalid token', 'status' => false]));
}

if ($path === '/send') {
    exit(json_encode([
        'detail'  => 'success! message in queue',
        'id'      => [(string) random_int(160000000, 169999999)],
        'process' => 'pending',
        'status'  => true,
        'target'  => [$_POST['target'] ?? ''],
    ]));
}
if ($path === '/device') {
    exit(json_encode([
        'device' => '6281200000000', 'device_status' => 'connect', 'expired' => '2026-12-31',
        'messages' => 1234, 'name' => 'CS Billing', 'package' => 'Lite', 'quota' => '11500', 'status' => true,
    ]));
}
http_response_code(404);
echo json_encode(['reason' => 'not found', 'status' => false]);

Server tiruan mencatat setiap request ke mock.log, sehingga Anda bisa memastikan field delay benar-benar ikut atau tidak. Selanjutnya, jalankan server itu dan arahkan aplikasi ke sana lewat variabel FONNTE_URL.

Menjalankan Uji

php -S 127.0.0.1:8099 mock-fonnte.php &

curl -s -X POST http://127.0.0.1:8099/device -H "Authorization: token-uji"
# {"device":"6281200000000","device_status":"connect",...,"quota":"11500","status":true}

FONNTE_URL=http://127.0.0.1:8099 php uji.php

File uji.php memanggil semua fungsi di artikel ini: normalisasi, kirim sukses, token perangkat mati, retry ke port tertutup, dan kirim_wa() dengan database MariaDB sementara. Hasilnya seperti gambar berikut.

Hasil uji Fonnte API PHP terhadap server tiruan: retry dua kali, log wa_logs, dan field delay hanya untuk pengingat
Hasil uji di server uji: retry berhenti setelah 3 percobaan, dan pesan invoice_paid lewat tanpa delay.

Webhook Status: “Sent” Belum Tentu Sampai

Inilah jebakan terbesar. Status sent di log hanya berarti Fonnte menerima request, memotong kuota, dan memberi ID. Pesan bisa saja tertahan selamanya di jalur WhatsApp. Satu-satunya cara tahu kebenarannya adalah webhook Message Status, yang Anda pasang per perangkat di dashboard Fonnte.

Dua Bentuk Payload untuk Satu Pesan

Fonnte mengirim dua bentuk payload. Bentuk pertama membawa id Fonnte plus stateid, yaitu ID pesan di sisi WhatsApp. Bentuk kedua tidak membawa id sama sekali, hanya stateid dan state berupa angka ack WhatsApp. Log asli dari server kami memperlihatkannya dengan jelas.

Log asli webhook Fonnte API PHP: payload dengan id dan status sent, lalu payload tanpa id dengan state 0, 2, dan 3
Tangkapan asli log webhook Fonnte di server billing, nomor perangkat dan ID disensor.

Perhatikan urutannya. Payload pertama datang dua kali, dan ack sempat berhenti di 0 selama tiga menit sebelum melompat ke 2 lalu 3. Jadi, webhook bisa datang berulang dan tidak berurutan. Kode kita harus tahan terhadap keduanya.

Nilai stateArti di WhatsAppStatus di wa_logs
"sent" (teks)Fonnte menerima requestsent
0Tertahan, ikon jam pasirsent
1Sampai di server WhatsApp, satu centangsent
2Sampai di HP, dua centangdelivered
3Dibaca, centang biruread
Negatif atau "failed"Errorfailed

Bagian 1: Kunci Rahasia dan Validasi URL

Webhook ini juga panjang, jadi kami memecahnya menjadi tiga bagian. Simpan ketiganya berurutan dalam satu file webhook-fonnte.php.

<?php
require __DIR__ . '/koneksi.php';
header('Content-Type: application/json');

$kunci = (string) getenv('WA_WEBHOOK_KEY');
if ($kunci === '' || !hash_equals($kunci, (string) ($_GET['key'] ?? ''))) {
    http_response_code(401);
    exit(json_encode(['error' => 'Unauthorized']));
}
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    exit(json_encode(['ok' => true, 'ping' => true])); // validasi URL memakai GET
}

$data    = json_decode(file_get_contents('php://input'), true) ?: $_POST;
$id      = $data['id'] ?? null;
$stateId = $data['stateid'] ?? null;
$state   = $data['state'] ?? $data['status'] ?? null;
if (($id === null && $stateId === null) || $state === null || $state === '') {
    exit(json_encode(['ok' => false, 'skipped' => 'tanpa id/state']));
}

Fonnte tidak menandatangani payload, jadi URL webhook membawa kunci rahasia di query string, misalnya ?key=.... Kemudian hash_equals() membandingkan kunci tanpa bocor lewat selisih waktu. Satu hal lagi: Fonnte memvalidasi URL dengan request GET. Karena itu, request selain POST harus mendapat balasan 200, kalau tidak dashboard Fonnte menolak URL Anda.

Bagian 2: Menerjemahkan State

function status_dari_state(int|string $state): ?string
{
    if (is_numeric($state)) {
        $ack = (int) $state; // ack WhatsApp berupa angka
        return match (true) {
            $ack < 0   => 'failed',
            $ack >= 3  => 'read',      // centang biru
            $ack === 2 => 'delivered', // dua centang, sampai di HP
            default    => 'sent',      // 0 tertahan, 1 baru sampai server WA
        };
    }
    return match (strtolower(trim($state))) {
        'pending', 'queued', 'process', 'sent' => 'sent',
        'delivered' => 'delivered',
        'read' => 'read',
        'failed', 'error', 'cancel', 'expired', 'reject' => 'failed',
        default => null,
    };
}

Fungsi ini menerima angka maupun teks, lalu mengubahnya ke empat status milik kita. Perhatikan bahwa ack 0 dan 1 tetap bernilai sent. Keduanya belum membuktikan pesan sampai di HP penerima. PHP mengizinkan fungsi ini berada di tengah file karena ia terdefinisi di level teratas.

Bagian 3: Status Hanya Boleh Maju

$kolom = $id !== null ? 'fonnte_id' : 'fonnte_state_id';
$st = $db->prepare("SELECT id, status, error FROM wa_logs WHERE $kolom = ? ORDER BY id DESC LIMIT 1");
$st->execute([(string) ($id ?? $stateId)]);
$row = $st->fetch();
if (!$row) {
    exit(json_encode(['ok' => false, 'skipped' => 'pesan tidak dikenal']));
}

$baru = status_dari_state($state);
$rank = ['failed' => 0, 'sent' => 1, 'delivered' => 2, 'read' => 3];
$maju = $baru !== null && ($baru === 'failed' || $rank[$baru] > $rank[$row['status']]);

$status = $maju ? $baru : $row['status'];
$error  = $maju ? ($baru === 'failed' ? substr((string) ($data['reason'] ?? 'gagal'), 0, 255) : null) : $row['error'];

$up = $db->prepare('UPDATE wa_logs SET fonnte_state_id = COALESCE(fonnte_state_id, ?),
                    status = ?, error = ? WHERE id = ?');
$up->execute([$stateId, $status, $error, $row['id']]);
echo json_encode(['ok' => true, 'status' => $status]);

Payload pertama menemukan baris lewat fonnte_id dan menyimpan stateid. Setelah itu, payload tanpa id menemukan baris yang sama lewat fonnte_state_id. Selain itu, status hanya bergerak maju, sehingga ack 2 yang terlambat tidak menurunkan status read. Nama kolom berasal dari dua pilihan tetap, jadi interpolasi $kolom tetap aman.

Uji Webhook dengan curl

U="http://127.0.0.1:8098/?key=rahasia-uji-123"
curl -s -X POST -H "Content-Type: application/json" \
  -d '{"id":"161305441","state":"sent","stateid":"3EB0AB12CD34EF56","status":"sent"}' "$U"
# {"ok":true,"status":"sent"}
curl -s -X POST -H "Content-Type: application/json" -d '{"state":3,"stateid":"3EB0AB12CD34EF56"}' "$U"
# {"ok":true,"status":"read"}
curl -s -X POST -H "Content-Type: application/json" -d '{"state":2,"stateid":"3EB0AB12CD34EF56"}' "$U"
# {"ok":true,"status":"read"}   <- ack terlambat tidak menurunkan status

Untuk kunci rahasia, Anda tidak perlu konfigurasi baru. Kami menurunkannya dari kunci aplikasi yang sudah ada: substr(hash('sha256', $encryptionKey . '|fonnte-wa-status'), 0, 32). Dengan cara ini, satu URL webhook berlaku untuk semua perangkat tenant, karena ID pesan Fonnte unik secara global.

Contoh Kasus Nyata dari Billing ISP

Sejak 29 Juni sampai 2 November 2026, billing kami mencatat 3.410 pesan WhatsApp. Gambar berikut merangkum status akhirnya langsung dari tabel wa_logs produksi.

Statistik asli wa_logs Fonnte API PHP: jumlah pesan sent, delivered, read, failed, dan daftar alasan gagal
Tangkapan asli query wa_logs di server billing produksi, nama database disensor.

Kasus 1: Log Bilang Terkirim, Pelanggan Tidak Menerima Apa-Apa

Pada Juli 2026, salah satu ISP pengguna billing kami mengeluh pengingat tagihan tidak pernah sampai. Padahal log menulis “sent”, perangkat berstatus connect, dan kuota terus berkurang. Webhook akhirnya membuka fakta: ack berhenti di 0 selamanya. Penyebabnya adalah broadcast 100 pesan serentak tanpa jeda beberapa hari sebelumnya. Akibatnya, WhatsApp membatasi nomor itu di jalur perangkat tertaut selama lima hari, sementara HP-nya sendiri tetap normal. Itulah alasan 339 pesan bulan Juli masih berstatus sent. Pelajarannya, jangan pernah broadcast tanpa jeda.

Kasus 2: OTP Selalu Kedaluwarsa

Kasus kedua lebih halus. Pelanggan portal mengeluh OTP login “tidak masuk”. Ternyata tenant itu memasang jeda 180–360 detik, sehingga Fonnte menahan OTP 3–6 menit, sedangkan OTP hanya berlaku 5 menit. Log menulis sent dalam 0,3 detik, jadi kode billing terlihat bersih. Solusinya adalah daftar EVENT_SEGERA yang sudah Anda lihat di atas.

Kasus 3: Perangkat Terputus Diam-Diam

Error paling sering di log kami adalah request invalid on disconnected device, sebanyak 52 kali. Biasanya HP pemilik nomor mati, logout, atau kehabisan baterai. Karena itu, kami menampilkan hasil device() di dashboard tenant agar mereka tahu sebelum pelanggan protes.

Alternatif Tanpa API: Link wa.me Click-to-Chat

Tidak semua pesan perlu otomatis. Untuk mengirim link tagihan satu per satu, operator cukup menekan tombol yang membuka WhatsApp miliknya sendiri. Cara ini tidak memotong kuota Fonnte dan tidak menambah risiko nomor terkena pembatasan.

<?php
require_once __DIR__ . '/normalisasi.php';

function link_wa(string $nomor, string $pesan): ?string
{
    $target = normalisasi_nomor($nomor);
    if ($target === null) {
        return null;
    }
    return 'https://wa.me/' . $target . '?text=' . rawurlencode($pesan);
}

echo link_wa('0812-3456-7890', "Halo Budi,\nTagihan INV-2611-001 Rp 150.000 & jatuh tempo 20 Nov.");
// https://wa.me/6281234567890?text=Halo%20Budi%2C%0ATagihan%20INV-2611-001%20Rp%20150.000%20%26%20jatuh%20tempo%2020%20Nov.

Fungsi ini memakai ulang normalisasi_nomor(), karena wa.me hanya menerima format 62 tanpa tanda plus. Kemudian rawurlencode() mengubah baris baru menjadi %0A dan tanda & menjadi %26, sehingga isi pesan tidak terpotong. Di HP, link ini membuka aplikasi WhatsApp, sedangkan di desktop ia membuka WhatsApp Web.

AspekFonnte APILink wa.me
Otomatis tanpa operatorYaTidak, operator menekan kirim
Memotong kuotaYaTidak
Risiko nomor terkena pembatasanAda, terutama saat massalSangat kecil, sama seperti chat manual
Cocok untukOTP, notifikasi bayar, pengingat terjadwalLink tagihan, follow-up personal

Kesalahan Umum

  • Menganggap status: true sebagai bukti sampai. Itu hanya tanda terima. Pasang webhook dan tampilkan badge “Antrian”, “Sampai”, “Dibaca” secara terpisah.
  • Retry semua error. Timeout bisa terjadi setelah pesan terkirim, jadi retry otomatis berisiko membuat pesan ganda.
  • Broadcast ratusan pesan tanpa jeda. Nomor bisa terkena pembatasan perangkat tertaut. Nomor perdana baru yang langsung masuk ke gateway malah lebih cepat terkena.
  • Memasang delay untuk semua pesan. OTP dan konfirmasi bayar ikut tertahan beberapa menit.
  • Lupa mendaftarkan IP server baru. Jika perangkat Fonnte memakai pembatasan IP, /device tetap sukses tetapi /send membalas unauthorized token usage.
  • Mematikan verifikasi SSL. Opsi CURLOPT_SSL_VERIFYPEER => false sering muncul di contoh internet. Biarkan default agar token tidak bocor lewat serangan man-in-the-middle.
  • Menaruh token di repository. Simpan token per tenant di database atau environment, bukan di kode.
  • Endpoint webhook menolak GET. Dashboard Fonnte lalu menganggap URL Anda tidak valid.

Kesimpulan

Mengirim WhatsApp lewat Fonnte API PHP itu mudah, tetapi membuatnya andal butuh beberapa lapis. Pertama, rapikan nomor sebelum mengirim. Kedua, bungkus cURL dalam satu kelas dengan timeout dan retry yang hanya mengulang error sebelum request terkirim. Ketiga, catat setiap kiriman sendiri, lalu biarkan webhook memperbarui statusnya, karena “sent” belum berarti sampai. Selain itu, bedakan pesan mendesak dari pesan massal agar delay tidak merusak OTP. Terakhir, ingat bahwa semua gateway WhatsApp tidak resmi membawa risiko pembatasan nomor. Jadi, gunakan link wa.me untuk pesan personal, dan pertimbangkan WhatsApp Cloud API resmi bila volume Anda sudah besar.

Baca Juga

Referensi: Dokumentasi API Fonnte, PHP Manual: cURL, PHP Manual: curl_errno, PHP Manual: hash_equals.

Tinggalkan Balasan

Alamat email Anda tidak akan dipublikasikan. Ruas yang wajib ditandai *