Dokumentasi - Ping! Chatbot AI & WhatsApp CRM

📋 Introduction

Ping! is a smart WhatsApp CRM platform that combines marketing tools, customer communication management, and AI technology—all in one dashboard.

Built with a user-friendly SaaS concept, Ping! empowers small businesses and entrepreneurs to manage customer interactions independently, efficiently, and at scale.

More than just a tool, Ping! also opens up new business opportunities for its users and is designed to be expandable through plugins and future feature integrations—similar to modular systems like WordPress and modern CMS platforms.

Main Modules

In the current version, Ping! includes 6 main modules:

✅ WhatsApp Chatbot (Unofficial & Official API) – For broadcasts, auto-replies, notifications, and chat handling
✅ Broadcast Scheduler – Send promotional messages via WhatsApp safely and gradually (anti-ban system)
✅ AI Chatbot (Powered by ChatGPT 4.0) – Auto-replies 24/7 even when your team is offline
✅ Website Live Chat Plugin – Add a chat widget to your site without any coding
✅ Webhook Integration – Connect with external platforms like Scalev and Lynk for automated workflows
✅ Customer Management – Comprehensive CRM features for managing customer relationships

💡 Note: Each module will continue to evolve based on user needs, market trends, and feedback from our community—through a voting system on our upcoming official forum.

🚀 Getting Started

Langkah 1: Dapatkan Webhook URL

Masuk ke halaman Settings di aplikasi Ping, lalu salin Webhook URL Anda:

Login ke aplikasi Ping
Buka menu Settings (/app/settings)
Salin Webhook URL yang ditampilkan
URL akan berbentuk: https://chat.ping.co.id/webhook/{business_id}

Langkah 2: Konfigurasi di Scalev/Lynk

Masukkan Webhook URL ke dalam pengaturan webhook di aplikasi Scalev atau Lynk Anda.

Langkah 3: Buat Webhook Rule

Buat rule untuk menentukan kapan dan bagaimana sistem akan merespon webhook yang masuk:

Buka menu Webhook Integrasi → Rules
Klik Tambah Rule
Isi form sesuai kebutuhan Anda
Simpan rule

Untuk API

Setiap penggunaan API memerlukan Device ID. Anda dapat menyalin Device ID di menu device pada bagian Action. Contoh Device ID sebagai berikut:

03359ec3-2052-43ff-9495-6155b8cab4cc

Cara Mendapatkan Device ID:

Cara Mendapatkan Device ID

Cara Mendapatkan API Key:

Cara Mendapatkan API Key

🔗 Konsep Webhook

Webhook adalah cara untuk aplikasi eksternal (seperti Scalev atau Lynk) mengirimkan notifikasi real-time ke aplikasi Ping ketika suatu event terjadi.

Flow Webhook

1. Event terjadi di Scalev/Lynk (contoh: order baru dibuat)
2. Scalev/Lynk mengirim HTTP POST request ke Webhook URL Ping
3. Ping menerima payload dan memvalidasi business_id
4. Sistem mengecek apakah ada rule yang sesuai dengan kondisi payload
5. Jika ada rule yang match, sistem akan mengeksekusi action (kirim WhatsApp)
6. Hasil eksekusi dicatat di Webhook Logs

🔗 Webhook URL

Format URL

POST https://chat.ping.co.id/webhook/{business_id}

Dimana {business_id} adalah UUID unik dari business Anda.

Request Headers

Header	Value	Required
`Content-Type`	`application/json`	✅ Ya
`User-Agent`	`Scalev-Webhook/1.0` atau `Lynk-Webhook/1.0`	❌ Tidak

Response Format

Success (200 OK):

{
  "status": "success",
  "message": "Webhook processed successfully",
  "rule_matched": true
}

Error (400/403/500):

{
  "status": "error",
  "message": "Error message",
  "error_code": "ERROR_CODE"
}

📦 Payload Scalev

Scalev mengirimkan payload dengan struktur berikut:

{
  "event": "order.created",
  "unique_id": "event_I7fkiBF4YksYDsKbVe5ZOEyZ",
  "timestamp": "2025-01-29T20:28:25.046183Z",
  "data": {
    "order_id": "250130JQHFZG",
    "status": "pending",
    "payment_status": "unpaid",
    "payment_method": "bank_transfer",
    "total_quantity": 1,
    "net_revenue": "149724.00",
    "gross_revenue": "168724.00",
    "destination_address": {
      "name": "Example Person",
      "phone": "628112345678",
      "email": "testing@example.com",
      "address": "This is not a real address.",
      "city": "Kota Surabaya",
      "province": "Jawa Timur"
    },
    "business": {
      "username": "username"
    },
    "store": {
      "name": "Example Store"
    }
  }
}

Field Penting Scalev

Field	Path	Deskripsi
Event	`event`	Nama event (contoh: order.created, order.deleted)
Order ID	`data.order_id`	ID unik order
Status Order	`data.status`	Status order (pending, confirmed, shipped, dll)
Status Pembayaran	`data.payment_status`	Status pembayaran (unpaid, paid, dll)
Nomor Telepon	`data.destination_address.phone`	Nomor telepon customer
Nama Customer	`data.destination_address.name`	Nama penerima

📦 Payload Lynk

Lynk mengirimkan payload dengan struktur berikut:

{
  "event": "payment.received",
  "data": {
    "message_action": "SUCCESS",
    "message_code": "0",
    "message_data": {
      "refId": "13f8d23beeb2aacbbc01c94060cc88d7",
      "createdAt": "2025-04-10T14:30:45",
      "customer": {
        "name": "Lynk User",
        "email": "user@lynk.id",
        "phone": "0812345677889"
      },
      "totals": {
        "grandTotal": 72000,
        "totalPrice": 25000,
        "totalAddon": 50000,
        "discount": 0,
        "totalShipping": 0
      },
      "items": [
        {
          "title": "Digital Produk",
          "price": 25000,
          "qty": 1
        }
      ]
    }
  }
}

Field Penting Lynk

Field	Path	Deskripsi
Event	`event`	Nama event (contoh: payment.received)
Reference ID	`data.message_data.refId`	ID referensi pembayaran
Waktu Pembayaran	`data.message_data.createdAt`	Timestamp pembayaran
Nomor Telepon	`data.message_data.customer.phone`	Nomor telepon customer
Nama Customer	`data.message_data.customer.name`	Nama customer
Grand Total	`data.message_data.totals.grandTotal`	Total pembayaran

⚙️ Membuat Webhook Rules

Webhook Rules menentukan kapan dan bagaimana sistem akan merespon webhook yang masuk.

Langkah-langkah Membuat Rule

Buka halaman Webhook Rules: Menu Webhook Integrasi → Rules
Klik "Tambah Rule"
Isi Form:
- Nama Rule: Nama untuk identifikasi rule (contoh: "Notifikasi Order Baru Scalev")
- Source: Pilih sumber webhook (Scalev, Lynk, atau Custom)
- Kondisi (JSON): Tentukan kondisi kapan rule akan dijalankan
- Template Pesan WhatsApp: Pesan yang akan dikirim ke customer
- Field Nomor Telepon: Path ke field nomor telepon di payload
- WhatsApp Device: Pilih device yang akan digunakan untuk mengirim pesan
- Status Rule: Aktifkan atau nonaktifkan rule
Simpan Rule

💡 Tips: Gunakan tombol Generator untuk membuat kondisi dan template pesan dengan mudah tanpa menulis JSON manual.

🔍 Kondisi & Trigger

Kondisi menentukan kapan rule akan dijalankan. Sistem mendukung berbagai operator untuk evaluasi kondisi.

Format Kondisi (JSON)

{
  "operator": "AND",
  "rules": [
    {
      "field": "event",
      "operator": "equals",
      "value": "order.created"
    },
    {
      "field": "data.payment_status",
      "operator": "equals",
      "value": "paid"
    }
  ]
}

Operator Logika

Operator	Deskripsi
`AND`	Semua kondisi harus terpenuhi
`OR`	Salah satu kondisi terpenuhi

Operator Perbandingan

Operator	Deskripsi	Contoh
`equals`	Sama dengan	`"event" equals "order.created"`
`not_equals`	Tidak sama dengan	`"status" not_equals "cancelled"`
`contains`	Mengandung teks	`"name" contains "Product"`
`exists`	Field ada / tidak kosong	`"phone" exists`
`greater_than`	Lebih besar dari	`"total" greater_than 100000`
`less_than`	Lebih kecil dari	`"quantity" less_than 10`

Contoh Kondisi

Contoh 1: Trigger ketika order baru dibuat

{
  "operator": "AND",
  "rules": [
    {
      "field": "event",
      "operator": "equals",
      "value": "order.created"
    }
  ]
}

Contoh 2: Trigger ketika pembayaran sudah dibayar

{
  "operator": "AND",
  "rules": [
    {
      "field": "event",
      "operator": "equals",
      "value": "order.created"
    },
    {
      "field": "data.payment_status",
      "operator": "equals",
      "value": "paid"
    }
  ]
}

💬 Template Pesan WhatsApp

Template pesan mendukung placeholder yang akan diganti dengan data dari payload.

Format Placeholder

Gunakan format {{path}} untuk menambahkan data dinamis ke pesan:

Halo {{data.destination_address.name}}, terima kasih sudah order {{data.order_id}}.
Total pembayaran Anda adalah Rp {{data.net_revenue}}.

Placeholder Scalev

Placeholder	Deskripsi
`{{data.order_id}}`	Order ID
`{{data.destination_address.name}}`	Nama Penerima
`{{data.destination_address.phone}}`	Nomor Telepon
`{{data.net_revenue}}`	Total Harga (Net)
`{{data.status}}`	Status Order

Placeholder Lynk

Placeholder	Deskripsi
`{{data.message_data.refId}}`	Reference ID
`{{data.message_data.customer.name}}`	Nama Customer
`{{data.message_data.totals.grandTotal}}`	Grand Total

Contoh Template

Halo {{data.destination_address.name}},

Terima kasih sudah melakukan pemesanan di toko kami!

📦 Order ID: {{data.order_id}}
💰 Total: Rp {{data.net_revenue}}
📊 Status: {{data.status}}

Kami akan segera memproses pesanan Anda.
Tim Customer Service

📊 Monitoring Webhook Logs

Semua webhook yang diterima akan dicatat di Webhook Logs untuk monitoring dan debugging.

Akses Webhook Logs

Buka menu Log Reports → Webhook Logs
Anda akan melihat daftar semua webhook yang diterima

Informasi di Logs

Kolom	Deskripsi
Waktu	Timestamp ketika webhook diterima
Source	Sumber webhook (Scalev, Lynk, atau Custom)
Status	Status eksekusi (Success, Failed, atau No Match)
Rule	Nama rule yang dijalankan (jika ada yang match)
Pesan/Error	Pesan sukses atau error message

Filter Logs

Anda dapat memfilter logs berdasarkan:

Source: Filter berdasarkan sumber webhook
Status: Filter berdasarkan status (Success, Failed, No Match)

Non Official Whatsapp API

In developing Non-Official WhatsApp Tools, we use the Baileys library (https://github.com/WhiskeySockets/Baileys).

However, the published API is not directly directed to the Node server, but is repackaged by Laravel. So, the first request is sent to the API provided by Laravel.

Chats

This API focuses on getting a list of contacts stored in your WhatsApp, as well as message history based on contacts or groups. There are several endpoints currently available:

📤 Send Message

POST

https://chat.ping.co.id/api-app/whatsapp/send-message

This endpoint is for sending single messages to both personal and group numbers.

Body Parameters

Parameter	Description	Example	Requirement
phone	Fill in the number or group ID	6281290641111	Required
device_key	Device ID. Optional if system is set to auto-pick, but required if targeting group or forced by settings	bc8bae5a-0997-40a2-a827-b95adc714dd3	Required if mandatory or sending to group
api_key	Your API key	XYZ987TOKEN	Required
method	Message method, available values: `text` or `template`	text / template	Required
text	Message content, used only when method is `text`	Hallo guys!	Required if method is text
is_group	Set `true` if sending to group, `false` if to individual	true	Required

Request Example

{
  "phone": "RECEIVER_NUMBER_OR_GROUP_ID",
  "device_key": "YOUR_DEVICE_ID",
  "api_key": "YOUR_API_KEY",
  "method": "text",
  "text": "Hallo guys!",
  "is_group": true
}

cURL Example

curl --location 'https://chat.ping.co.id/api-app/whatsapp/send-message' \
--header 'Content-Type: application/json' \
--data-raw '{
  "phone": "RECEIVER_NUMBER_OR_GROUP_ID",
  "device_key": "YOUR_DEVICE_ID",
  "api_key": "YOUR_API_KEY",
  "method": "text",
  "text": "Hallo guys!",
  "is_group": true
}'

Response Example

{
  "status": true,
  "message": "Berhasil mengirimkan pesan"
}

📝 Send Message With Template

POST

https://chat.ping.co.id/api-app/whatsapp/send-message

The endpoint here is the same as the previous Send Message endpoint, the only difference is in the body, if in the example above we use the text method, to send a message without a template, in this endpoint we use the template method, to send a message using the template we created in Ping Dashboard

Body Parameters

Parameter	Description	Example	Requirement
phone	Receiver phone number or WhatsApp Group ID	6281234567890 / 1203630xxxxxxx@g.us	Required
device_key	Your WhatsApp device identifier	bc8bae5a-0997-40a2-a827-b95adc714dd3	Required
api_key	Your API key	39c91b1a-03a5-43e6-a798-73b18388652b	Required
method	Sending method (use `template` for this)	template	Required
template	Whatsapp message template ID to be used	510b32e9-d6d9-4c75-83ae-f95cdfcc96e3	Required
is_group	Set `true` if sending to a group	true	Optional
variables	Fill with the variables provided in the message template	{ "{business_name}": "My Store", "{name}": "Budi" }	Required

Request Example

{
  "phone": "RECEIVER_NUMBER_OR_GROUP_ID",
  "device_key": "YOUR_DEVICE_ID",
  "api_key": "YOUR_API_KEY",
  "method": "template",
  "template": "YOUR_TEMPLATE_ID",
  "is_group": true,
  "variables": {
    "{business_name}": "BUSINESS_NAME",
    "{name}": "YOUR_NAME"
  }
}

cURL Example

curl --location 'https://chat.ping.co.id/api-app/whatsapp/send-message' \
--header 'Content-Type: application/json' \
--data-raw '{
  "phone": "RECEIVER_NUMBER_OR_GROUP_ID",
  "device_key": "YOUR_DEVICE_ID",
  "api_key": "YOUR_API_KEY",
  "method": "template",
  "template": "YOUR_TEMPLATE_ID",
  "is_group": true,
  "variables": {
    "{business_name}": "BUSINESS_NAME",
    "{name}": "YOUR_NAME"
  }
}'

Response Example

{
  "status": true,
  "message": "Berhasil mengirimkan pesan"
}

📞 Message Callback

POST

https://chat.ping.co.id/api-app/whatsapp/callback/device_03359ec3-2052-43ff-9495-6155b8cab4cc

This endpoint is actually created to open communication from the WhatsApp server when a WhatsApp message comes into the connected device.

But sometimes this callback will be useful when we want to do auto reply testing without having to test sending messages on WhatsApp

Body Parameters

Parameter	Description	Example	Requirement
from	The sender's number (use `628xxxx@s.whatsapp.net` for personal chats or `xxxx@g.us` for groups)	62812906*****@s.whatsapp.net	Required
message_id	Unique identifier for the WhatsApp message	18DD98462C8AA16C5A598C3DEBA0879B	Required
message	The content of the message	Hello	Required
from_name	Name of the sender	Bhisma Kalijaga	Required
type	Type of message, typically set to `single`	single	Required

Request Example

{
  "from": "62812906*****@s.whatsapp.net",
  "message_id": "18DD98462C8AA16C5A598C3DEBA0879B",
  "message": "Halo",
  "from_name": "Bhisma Kalijaga",
  "type": "single"
}

cURL Example

curl --location 'https://chat.ping.co.id/api-app/whatsapp/callback/device_03359ec3-2052-43ff-9495-6155b8cab4cc' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from": "62812906*****@s.whatsapp.net",
    "message_id": "18DD98462C8AA16C5A598C3DEBA0879B",
    "message": "Halo",
    "from_name": "Bhisma Kalijaga",
    "type": "single"
}'

Response Example

{
  "message": {
    "text": "API Doc Ping Example"
  },
  "receiver": "6281290*****@s.whatsapp.net",
  "session_id": "device_03359ec3-2052-43ff-9495-6155b8cab4cc",
  "autoread": false,
  "reply": true
}

🔗 Webhook Sample (Custom Webhook)

POST

https://yourdomain.com/webhook

Fitur Custom Webhook memungkinkan Anda menerima notifikasi real-time ketika WhatsApp device menerima pesan baru. Webhook akan otomatis dikirim ke URL yang Anda konfigurasi di pengaturan device.

📋 Cara Setup

Buka menu Device di dashboard Ping!
Pilih atau buat device WhatsApp yang ingin dikonfigurasi
Isi field "WebHook Url" dengan URL endpoint Anda (contoh: https://yourdomain.com/webhook)
Simpan perubahan

Catatan: URL webhook harus dapat diakses dari internet dan menerima request POST dengan Content-Type: application/json

⚙️ Kondisi Webhook Dikirim

Webhook akan dikirim jika semua kondisi berikut terpenuhi:

✅ Webhook URL sudah dikonfigurasi di device
✅ Device menerima pesan baru (teks atau file/image)
✅ Paket langganan Anda aktif

📦 Payload Structure

Webhook akan mengirim payload dalam format JSON dengan struktur berikut:

Body Parameters

Parameter	Description	Example	Type
`device_key`	Unique identifier untuk device WhatsApp yang menerima pesan	7eab82d8-805a-4828-97e5-70a699027c4c	String (UUID)
`name`	Nama pengirim pesan (dari WhatsApp contact)	John Doe	String
`from`	Nomor telepon pengirim (tanpa @s.whatsapp.net)	6281234567890	String
`message`	Isi pesan yang diterima (teks). Null jika hanya file/image tanpa teks	Halo, ini pesan test	String \| Null
`type`	Tipe pesan. Biasanya "single" untuk pesan personal	single	String
`file_url`	URL lengkap file/gambar (hanya ada jika pesan mengandung file/gambar)	https://chat.ping.co.id/uploads/media-manager/image_123.jpg	String \| Null
`file_type`	MIME type file (hanya ada jika pesan mengandung file/gambar)	image/jpeg, video/mp4, application/pdf	String \| Null
`file_size`	Ukuran file dalam bytes (hanya ada jika pesan mengandung file/gambar)	123456	Integer \| Null
`file_category`	Kategori file: image, video, audio, pdf, file (hanya ada jika pesan mengandung file/gambar)	image, video, audio, pdf, file	String \| Null

💡 Catatan: Field file_url, file_type, file_size, dan file_category hanya akan muncul di payload jika pesan yang diterima mengandung file atau gambar (baik dengan teks maupun tanpa teks).

Request Example

{
    "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
    "name": "John Doe",
    "from": "6281234567890",
    "message": "Halo, ini pesan test",
    "type": "single"
}

Contoh Payload untuk Pesan dengan Teks + File/Image

Jika pesan berisi teks dan file/gambar, payload akan menyertakan informasi file:

{
    "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
    "name": "John Doe",
    "from": "6281234567890",
    "message": "Ini pesan dengan gambar",
    "type": "single",
    "file_url": "https://chat.ping.co.id/uploads/media-manager/image_123.jpg",
    "file_type": "image/jpeg",
    "file_size": 123456,
    "file_category": "image"
}

Contoh Payload untuk Pesan Hanya File/Image (Tanpa Teks)

Jika pesan hanya berisi file/image tanpa teks, field message akan berisi null, tetapi informasi file tetap tersedia:

{
    "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
    "name": "Jane Smith",
    "from": "6289876543210",
    "message": null,
    "type": "single",
    "file_url": "https://chat.ping.co.id/uploads/media-manager/video_456.mp4",
    "file_type": "video/mp4",
    "file_size": 2345678,
    "file_category": "video"
}

Contoh Payload untuk Berbagai Tipe File

Audio:

{
    "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
    "name": "Audio User",
    "from": "6281111111111",
    "message": "Voice note",
    "type": "single",
    "file_url": "https://chat.ping.co.id/uploads/media-manager/audio_789.mp3",
    "file_type": "audio/mpeg",
    "file_size": 567890,
    "file_category": "audio"
}

PDF/Dokumen:

{
    "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
    "name": "Document User",
    "from": "6282222222222",
    "message": "Ini dokumen",
    "type": "single",
    "file_url": "https://chat.ping.co.id/uploads/media-manager/document_abc.pdf",
    "file_type": "application/pdf",
    "file_size": 345678,
    "file_category": "pdf"
}

cURL Example (Testing)

Anda dapat menggunakan cURL untuk testing endpoint webhook Anda:

curl --location 'https://yourdomain.com/webhook' \
--header 'Content-Type: application/json' \
--data-raw '{
    "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
    "name": "John Doe",
    "from": "6281234567890",
    "message": "Halo, ini pesan test",
    "type": "single"
}'

⚠️ Catatan Penting

Webhook tidak dikirim jika:
- Paket langganan tidak aktif
- Webhook URL tidak dikonfigurasi
- Pesan adalah reaction, sticker, atau disappearing message
Timeout: Request webhook memiliki timeout 10 detik. Pastikan endpoint Anda merespons dengan cepat.
Error Handling: Jika webhook gagal dikirim (timeout, network error, dll), sistem akan silent fail dan tidak mengganggu proses utama.

🔍 Testing Webhook

Untuk testing webhook, Anda dapat menggunakan layanan berikut:

Webhook.site: https://webhook.site - Dapatkan URL unik untuk testing
RequestBin: https://requestbin.com - Alternatif untuk testing webhook
ngrok: Untuk testing webhook di local development

Official WhatsApp API (WABA)

Bagian ini khusus untuk WhatsApp Official / WhatsApp Business API (WABA) yang terhubung melalui Meta Cloud API. Endpoint-nya terpisah dari Non Official WhatsApp API agar tidak tercampur.

Request tetap masuk ke Laravel terlebih dahulu (/api-app/waba/...), lalu Laravel meneruskan ke Meta Graph API. Autentikasi memakai api_key (Local API Key akun Anda) dan opsional device_key (ID nomor WABA). Cara mendapatkannya dijelaskan di bagian API Key & Device ID.

💡 Catatan Meta: Pesan teks bebas (simple) hanya diizinkan dalam jendela percakapan 24 jam setelah customer membalas. Di luar jendela tersebut, gunakan template yang sudah APPROVED di Meta.

Perbedaan singkat vs Non Official

Unofficial: satu endpoint /whatsapp/send-message + field method
Official: dua endpoint terpisah — /waba/messages/simple dan /waba/messages/template
Template Official mengikuti struktur Meta (header / body / buttons), bukan variabel template Ping unofficial

🔑 API Key & Device ID (WABA)

Untuk memanggil API Official, Anda membutuhkan dua kredensial berikut.

1. `api_key` — Local API Key

Buka menu Settings di dashboard Ping!
Cari field Local API Key
Salin nilainya — ini dipakai sebagai api_key di setiap request

2. `device_key` — Device ID nomor WABA

Buka menu WABA → pilih akun Meta Anda → Devices (daftar nomor)
Di bawah nomor telepon, ada baris ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
Klik tombol Copy () di samping ID, atau tombol copy di kolom Action
Nilai UUID tersebut adalah device_key yang dipakai di API

💡 Catatan:

device_key adalah ID unik per nomor WABA (bukan Meta Account ID / WABA ID Meta).
Jika setting API Device Use = required, device_key wajib diisi.
Jika tidak required, field ini boleh dikosongkan — sistem akan auto-pick nomor aktif sesuai strategi pengiriman (sequence / spin / random).

⚠️ Jangan tertukar:

device_key → ID nomor di halaman WABA Devices
api_key → Local API Key di Settings
Meta Account ID / Business App ID → hanya untuk setup integrasi, bukan untuk send message API

📤 Send Simple Message (WABA)

POST

https://chat.ping.co.id/api-app/waba/messages/simple

Kirim pesan teks atau media melalui nomor WABA Official. Jika url diisi, sistem mengunggah media ke Meta lalu mengirim sebagai image/video/audio/document.

Body Parameters

Parameter	Description	Example	Requirement
api_key	Local API Key akun bisnis Anda. Ambil dari Settings → Local API Key. Lihat API Key & Device ID	39c91b1a-03a5-43e6-a798-73b18388652b	Required
device_key	Device ID nomor WABA. Ambil dari WABA → Devices (teks ID di bawah nomor, atau tombol Copy). Wajib jika API Device Use = required	bc8bae5a-0997-40a2-a827-b95adc714dd3	Conditional
phone	Nomor penerima (disarankan format internasional tanpa +)	6281234567890	Required
message	Isi pesan teks, atau caption jika mengirim media	Halo, pesanan Anda sudah diproses	Required for text
url	URL publik file media (opsional). Jika ada, dikirim sebagai media message	https://example.com/invoice.pdf	Optional

Request Example (Text)

{
  "api_key": "YOUR_API_KEY",
  "device_key": "YOUR_WABA_DEVICE_ID",
  "phone": "6281234567890",
  "message": "Halo, pesanan Anda sudah diproses"
}

Request Example (Media)

{
  "api_key": "YOUR_API_KEY",
  "device_key": "YOUR_WABA_DEVICE_ID",
  "phone": "6281234567890",
  "message": "Berikut invoice Anda",
  "url": "https://example.com/invoice.pdf"
}

cURL Example

curl --location 'https://chat.ping.co.id/api-app/waba/messages/simple' \
--header 'Content-Type: application/json' \
--data-raw '{
  "api_key": "YOUR_API_KEY",
  "device_key": "YOUR_WABA_DEVICE_ID",
  "phone": "6281234567890",
  "message": "Halo, pesanan Anda sudah diproses"
}'

Response Example

{
  "status": true,
  "message": "Pesan berhasil dikirim"
}

📝 Send Template Message (WABA)

POST

https://chat.ping.co.id/api-app/waba/messages/template

Kirim pesan menggunakan template Meta yang statusnya APPROVED. Endpoint ini memakai struktur komponen resmi Meta: header, body parameters, dan buttons.

Body Parameters

Parameter	Description	Example	Requirement
api_key	Local API Key akun bisnis Anda. Ambil dari Settings → Local API Key. Lihat API Key & Device ID	39c91b1a-03a5-43e6-a798-73b18388652b	Required
device_key	Device ID nomor WABA. Ambil dari WABA → Devices (teks ID di bawah nomor, atau tombol Copy). Opsional jika auto-pick device aktif	bc8bae5a-0997-40a2-a827-b95adc714dd3	Conditional
phone	Nomor penerima	6281234567890	Required
template_id	ID template lokal di Ping (harus milik akun Meta yang sama & APPROVED)	510b32e9-d6d9-4c75-83ae-f95cdfcc96e3	Required
template_lang	Kode bahasa template	id / en	Required
header	Komponen header dinamis. `type`: text \| image \| video \| document; `value`: teks atau URL	{"type":"image","value":"https://..."}	Optional
body	Array parameter body template (urutan mengikuti variabel 1, 2, dst.)	["Budi", "ORD-123"]	Optional
buttons	Parameter tombol dinamis. Setiap item: `type` (url \| quick_reply), `index`, `value`	[{"type":"url","index":0,"value":"order/123"}]	Optional

Request Example

{
  "api_key": "YOUR_API_KEY",
  "device_key": "YOUR_WABA_DEVICE_ID",
  "phone": "6281234567890",
  "template_id": "YOUR_TEMPLATE_ID",
  "template_lang": "id",
  "header": {
    "type": "image",
    "value": "https://example.com/banner.jpg"
  },
  "body": [
    "Budi",
    "ORD-12345"
  ],
  "buttons": [
    {
      "type": "url",
      "index": 0,
      "value": "order/12345"
    }
  ]
}

cURL Example

curl --location 'https://chat.ping.co.id/api-app/waba/messages/template' \
--header 'Content-Type: application/json' \
--data-raw '{
  "api_key": "YOUR_API_KEY",
  "device_key": "YOUR_WABA_DEVICE_ID",
  "phone": "6281234567890",
  "template_id": "YOUR_TEMPLATE_ID",
  "template_lang": "id",
  "body": ["Budi", "ORD-12345"]
}'

Response Example

{
  "status": true,
  "message": "Pesan berhasil dikirim",
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [{"input": "6281234567890", "wa_id": "6281234567890"}],
    "messages": [{"id": "wamid.HBgLNjI4..."}]
  }
}

⚠️ Catatan: Template harus status APPROVED di Meta dan tersinkron di Ping. Jika template tidak ditemukan / belum approved, API mengembalikan HTTP 404.

📞 Meta Callback (WABA Inbound)

GET POST

https://chat.ping.co.id/api-app/waba/callback-url/{settings_id}

Endpoint ini dipakai Meta untuk mengirim event ke Ping (pesan masuk, status delivery, dll). Biasanya tidak dipanggil langsung oleh integrator eksternal.

Verifikasi Webhook (GET)

Meta memanggil GET dengan query hub.mode, hub.verify_token, dan hub.challenge. Ping memvalidasi token lalu mengembalikan challenge.

Event Pesan (POST)

Meta mengirim payload Cloud API (object whatsapp_business_account) berisi pesan masuk atau update status. Ping memproses, menyimpan ke CRM, menjalankan auto-reply/AI bila aktif, lalu dapat meneruskan ke Custom Webhook Anda.

💡 Setup: URL callback digenerate otomatis saat koneksi WABA di dashboard: {APP_URL}/api-app/waba/callback-url/{tokenUid}. Pastikan URL ini ter-subscribe di Meta App / WABA subscribed apps.

🔗 Custom Webhook (WABA)

POST

https://yourdomain.com/webhook

Mirip Non Official: Anda bisa menerima notifikasi real-time ke URL sendiri saat nomor WABA menerima pesan. Konfigurasi dilakukan di pengaturan device/nomor WABA (field WebHook Url + webhook enable).

📋 Cara Setup

Buka menu WABA Devices di dashboard Ping!
Pilih nomor WABA yang ingin dikonfigurasi
Isi WebHook Url dan pastikan webhook dalam status enabled
Simpan perubahan

⚙️ Kondisi Webhook Dikirim

✅ Webhook URL terisi dan webhook_enable = yes
✅ Nomor WABA menerima pesan baru yang diproses sistem
✅ Paket langganan aktif (untuk fitur terkait)

📦 Payload Structure

Parameter	Description	Example	Type
`device_key`	ID nomor WABA yang menerima pesan	7eab82d8-805a-4828-97e5-70a699027c4c	String (UUID)
`from`	Nomor pengirim	6281234567890	String
`message`	Isi teks pesan (bisa kosong untuk media tanpa caption)	Halo, saya mau tanya	String
`type`	Tipe pesan dari Meta (text, image, audio, video, document, dll.)	text	String
`file`	Objek info media (jika ada). Berisi `status`, `type`, `size`, `path`	lihat contoh di bawah	Object

Request Example (Text)

{
  "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
  "from": "6281234567890",
  "message": "Halo, saya mau tanya",
  "type": "text",
  "file": {
    "status": false,
    "type": null,
    "size": null,
    "path": null
  }
}

Request Example (Media)

{
  "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
  "from": "6281234567890",
  "message": "Ini foto produk",
  "type": "image",
  "file": {
    "status": true,
    "type": "image/jpeg",
    "size": 123456,
    "path": "https://chat.ping.co.id/uploads/media-manager/image_123.jpg"
  }
}

cURL Example (Testing)

curl --location 'https://yourdomain.com/webhook' \
--header 'Content-Type: application/json' \
--data-raw '{
  "device_key": "7eab82d8-805a-4828-97e5-70a699027c4c",
  "from": "6281234567890",
  "message": "Halo, saya mau tanya",
  "type": "text",
  "file": {
    "status": false,
    "type": null,
    "size": null,
    "path": null
  }
}'

Timeout: request webhook timeout 10 detik.
Silent fail: kegagalan kirim webhook tidak mengganggu proses utama callback Meta.
Auto-disable: jika URL unreachable (connection refused / DNS / timeout), sistem dapat menonaktifkan webhook_enable otomatis.
Beda payload: Custom Webhook WABA memakai field file (object), berbeda dari Non Official yang memakai file_url / file_type / file_size / file_category.

🐛 Troubleshooting

Error: INVALID_BUSINESS_ID

Penyebab: Business ID yang dikirim tidak valid atau tidak ditemukan.
Solusi: Pastikan Anda menggunakan Webhook URL yang benar dari halaman Settings.

Error: PACKAGE_NOT_ACTIVE

Penyebab: Paket langganan Anda tidak aktif.
Solusi: Perpanjang paket langganan Anda untuk menggunakan fitur webhook.

Webhook Tidak Terkirim

Checklist:

✅ Pastikan rule sudah dibuat dan statusnya Aktif
✅ Pastikan kondisi rule sesuai dengan payload yang dikirim
✅ Pastikan WhatsApp Device sudah dipilih dan statusnya Active
✅ Cek Webhook Logs untuk melihat detail error

Pesan WhatsApp Tidak Terkirim

Checklist:

✅ Pastikan nomor telepon di payload valid
✅ Pastikan Field Nomor Telepon sudah diisi dengan benar
✅ Pastikan WhatsApp Device terhubung dan aktif
✅ Cek Webhook Logs untuk melihat error message

Dokumentasi - Ping! Chatbot AI & WhatsApp CRM

📋 Introduction

Main Modules

🚀 Getting Started

Langkah 1: Dapatkan Webhook URL

Langkah 2: Konfigurasi di Scalev/Lynk

Langkah 3: Buat Webhook Rule

Untuk API

Cara Mendapatkan Device ID:

Cara Mendapatkan API Key:

🔗 Konsep Webhook

Flow Webhook

🔗 Webhook URL

Format URL

Request Headers

Response Format

📦 Payload Scalev

Field Penting Scalev

📦 Payload Lynk

Field Penting Lynk

⚙️ Membuat Webhook Rules

Langkah-langkah Membuat Rule

🔍 Kondisi & Trigger

Format Kondisi (JSON)

Operator Logika

Operator Perbandingan

Contoh Kondisi

💬 Template Pesan WhatsApp

Format Placeholder

Placeholder Scalev

Placeholder Lynk

Contoh Template

📊 Monitoring Webhook Logs

Akses Webhook Logs

Informasi di Logs

Filter Logs

Non Official Whatsapp API

Chats

📤 Send Message

Body Parameters

Request Example

cURL Example

Response Example

📝 Send Message With Template

Body Parameters

Request Example

cURL Example

Response Example

📞 Message Callback

Body Parameters

Request Example

cURL Example

Response Example

🔗 Webhook Sample (Custom Webhook)

📋 Cara Setup

⚙️ Kondisi Webhook Dikirim

📦 Payload Structure

Body Parameters

Request Example

Contoh Payload untuk Pesan dengan Teks + File/Image

Contoh Payload untuk Pesan Hanya File/Image (Tanpa Teks)

Contoh Payload untuk Berbagai Tipe File

cURL Example (Testing)

⚠️ Catatan Penting

🔍 Testing Webhook

Official WhatsApp API (WABA)

Perbedaan singkat vs Non Official

🔑 API Key & Device ID (WABA)

1. api_key — Local API Key

2. device_key — Device ID nomor WABA

📤 Send Simple Message (WABA)

Body Parameters

Request Example (Text)

Request Example (Media)

cURL Example

Response Example

📝 Send Template Message (WABA)

Body Parameters

Request Example

cURL Example

1. `api_key` — Local API Key

2. `device_key` — Device ID nomor WABA