Kembali ke landing page

Penjelasan Teknis WhatsApp Webhook

Halaman ini menjelaskan arsitektur webhook WhatsApp di sistem toko_kopi, termasuk endpoint masuk, cara membedakan provider Wablas dan Meta Cloud API, serta plugin channel untuk Fonnte, Twilio, Baileys, MessageBird, dan Vonage, bentuk payload, proses verifikasi, dan alur pesan sampai masuk ke chatbot.

Buka Dashboard Admin Pengaturan WhatsApp Arsitektur Multi-Channel

1. Endpoint Utama

Provider WhatsApp legacy masuk lewat satu endpoint yang sama:

https://botlelang.com/toko_kopi/public/api/whatsapp/webhook.php

Untuk konfigurasi per cabang, sistem juga mendukung URL khusus cabang:

https://botlelang.com/toko_kopi/public/api/whatsapp/webhook.php?branch=<BRANCH_ID>

URL khusus cabang paling aman dipakai untuk provider legacy seperti Wablas karena branch bisa diikat langsung dari query string.

Fonnte, Twilio, dan Vonage sekarang memakai endpoint plugin channel per cabang di /api/channel/webhook.php.

2. File Teknis yang Terlibat

  • Endpoint webhook: public/api/whatsapp/webhook.php
  • Factory provider: app/WhatsAppProviders/ProviderFactory.php
  • Adapter Meta Cloud API: app/WhatsAppProviders/MetaCloudApiProvider.php
  • Plugin channel Fonnte: plugins/fonnte-whatsapp/FonnteWhatsAppChannel.php
  • Plugin channel Twilio: plugins/twilio-whatsapp/TwilioWhatsAppChannel.php
  • Plugin channel Baileys: plugins/baileys-whatsapp/BaileysWhatsAppChannel.php
  • Plugin channel MessageBird: plugins/messagebird-whatsapp/MessageBirdWhatsAppChannel.php
  • Plugin channel Vonage: plugins/vonage-whatsapp/VonageWhatsAppChannel.php
  • Engine chatbot: app/Services/ChatbotEngine.php

Halaman ini ditautkan dari landing page dan halaman pengaturan WhatsApp supaya tim admin bisa berpindah dari setup ke dokumentasi teknis dengan cepat.

Untuk skenario satu cabang membuka WhatsApp, Telegram, dan Discord sekaligus, lihat juga halaman arsitektur multi-channel.

3. Alur Masuk Pesan

  • Provider mengirim request ke endpoint webhook.
  • Sistem mendeteksi provider dari query string, header, atau struktur payload.
  • Adapter provider memverifikasi request bila perlu.
  • Payload dinormalisasi ke format internal: from, message, raw.
  • Pesan masuk ke ChatbotEngine untuk diproses sebagai order, pertanyaan, promo, atau checkout.
  • Balasan dikirim lagi lewat adapter provider yang sama.

4. Format Payload Fonnte

Deteksi Fonnte dilakukan saat payload memiliki field sender.

{ "sender": "6281234567890", "message": "pesan 2 latte", "device": "6281234567891" }
  • sender: nomor WhatsApp customer
  • message: isi pesan yang dikirim customer
  • device: nomor atau device branch yang menerima pesan

Di implementasi saat ini, Fonnte tidak memakai signature verification yang ketat. Validasi utamanya adalah setting provider aktif dan API key tersedia.

5. Format Payload Meta Cloud API

Deteksi Meta dilakukan saat payload memiliki entry[0].changes.

{ "object": "whatsapp_business_account", "entry": [{ "changes": [{ "field": "messages", "value": { "messages": [{ "from": "6281234567890", "type": "text", "text": { "body": "pesan 1 americano" } }] } }] }] }
  • messages[0].from: nomor customer
  • messages[0].text.body: isi pesan

6. Format Payload Twilio

Twilio mengirim webhook dalam format application/x-www-form-urlencoded. Field utama yang dipakai adalah From, To, Body, dan AccountSid.

From=whatsapp:%2B6281234567890 To=whatsapp:%2B14155238886 Body=pesan%201%20latte AccountSid=ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Provider Twilio di project ini mengirim balasan lewat REST API Messages dan dapat memverifikasi header X-Twilio-Signature bila Auth Token diisi.

7. Format Payload Baileys Bridge

Baileys bukan provider native PHP. Ia harus berjalan sebagai service Node.js yang meneruskan pesan ke endpoint plugin channel branch ini.

{ "bridge": "baileys", "from": "6281234567890", "message": "pesan 1 americano" }

Balasan dari PHP dikirim kembali ke service bridge melalui setting outbound_url plugin, lalu service Node Baileys yang meneruskannya ke WhatsApp.

8. Format Payload MessageBird

MessageBird Conversations API mengirim webhook JSON saat ada pesan masuk dengan type message.created dan direction received.

{ "type": "message.created", "message": { "id": "msg_id_xxx", "direction": "received", "type": "text", "source": "6281234567890", "content": { "text": "pesan 1 latte" } } }
  • message.source: nomor WhatsApp customer
  • message.content.text: isi pesan

Plugin channel MessageBird membaca payload type=message.created. Signature webhook diverifikasi via HMAC-SHA256 menggunakan Signing Key dari dashboard MessageBird.

9. Format Payload Vonage

Vonage Messages API mengirim webhook JSON untuk pesan WhatsApp masuk dengan field channel=whatsapp.

{ "channel": "whatsapp", "message_type": "text", "text": "pesan 1 americano", "from": "6281234567890", "to": "6281234567891", "message_uuid": "uuid-xxx", "timestamp": "2024-01-01T10:00:00Z" }
  • from: nomor customer
  • text: isi pesan

Vonage menggunakan Basic Auth (API Key:API Secret) untuk pengiriman pesan. Verifikasi webhook dilakukan via header X-Nexmo-Signature atau X-Vonage-Signature dengan HMAC-SHA256.

10. Verifikasi Meta Cloud API

Meta membutuhkan verifikasi webhook lewat request GET dengan parameter challenge:

GET /api/whatsapp/webhook.php?hub_mode=subscribe&hub_verify_token=TOKEN&hub_challenge=12345

Sistem akan:

  • mencari webhook_token yang cocok di branch_whatsapp_settings
  • mengembalikan hub_challenge bila token valid
  • mengembalikan HTTP 403 bila token salah

11. Signature / Security

Untuk Meta, sistem mendukung pengecekan X-Hub-Signature-256 bila api_secret diisi.

MessageBird menggunakan HMAC-SHA256 dari gabungan timestamp, URL, dan SHA256(body) via header MessageBird-Signature. Vonage menggunakan HMAC-SHA256 dari body raw via header X-Nexmo-Signature atau X-Vonage-Signature.

Bila api_secret kosong, webhook tetap diterima agar setup lebih fleksibel saat tahap integrasi awal.

Rekomendasi production: selalu isi api_secret untuk Meta, MessageBird, dan Vonage agar request bisa diverifikasi dengan HMAC SHA-256.

12. Normalisasi Internal

Setelah payload lolos verifikasi, setiap provider diubah ke bentuk internal yang seragam seperti ini:

[ 'from' => '6281234567890', 'message' => 'pesan 1 latte', 'raw' => [ ...original payload... ] ]

Format inilah yang kemudian dikirim ke engine chatbot, jadi skill order, promo, dan cart tidak perlu tahu pesan itu datang dari Fonnte atau Meta.

13. Kaitan dengan Dashboard

  • Branch admin: atur provider, nomor WA, API key, secret, dan verify token dari halaman pengaturan WhatsApp cabang.
  • Super admin: bisa melihat dan mengatur semua provider di seluruh cabang.
  • Webhook token: terutama penting untuk Meta Cloud API.
  • Nomor WA branch: dipakai untuk pencocokan request provider ke cabang yang tepat.

14. Checklist Setup

  • Pastikan branch sudah aktif.
  • Pilih provider WhatsApp yang benar di dashboard.
  • Isi nomor WhatsApp branch.
  • Isi api_key sesuai provider.
  • Untuk Meta, isi juga api_secret dan webhook_token.
  • Untuk MessageBird, isi api_key (Access Key), api_secret (Signing Key), dan Channel ID di section plugin MessageBird.
  • Untuk Vonage, isi api_key dan api_secret dari dashboard Vonage.
  • Daftarkan URL webhook ke provider.
  • Uji kirim pesan masuk dan cek apakah balasan bot muncul.