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

🚀 Getting Started

Langkah 1: Dapatkan Webhook URL

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

1. Login ke aplikasi Ping
2. Buka menu Settings (/app/settings)
3. Salin Webhook URL yang ditampilkan
4. 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:

1. Buka menu Webhook Integrasi → Rules
2. Klik Tambah Rule
3. Isi form sesuai kebutuhan Anda
4. 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 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

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": "[email protected]",
      "address": "This is not a real address.",
      "city": "Kota Surabaya",
      "province": "Jawa Timur"
    },
    "business": {
      "username": "username"
    },
    "store": {
      "name": "Example Store"
    }
  }
}

Field Penting Scalev

📦 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": "[email protected]",
        "phone": "0812345677889"
      },
      "totals": {
        "grandTotal": 72000,
        "totalPrice": 25000,
        "totalAddon": 50000,
        "discount": 0,
        "totalShipping": 0
      },
      "items": [
        {
          "title": "Digital Produk",
          "price": 25000,
          "qty": 1
        }
      ]
    }
  }
}

Field Penting Lynk

⚙️ Membuat Webhook Rules

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

Langkah-langkah Membuat Rule

1. Buka halaman Webhook Rules: Menu Webhook Integrasi → Rules
2. Klik "Tambah Rule"
3. 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
4. Simpan Rule

🔍 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 Perbandingan

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 Lynk

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

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

Informasi di Logs

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

{
  "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 --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
}'

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

📝 Send Message With Template

{
  "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 --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"
  }
}'

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

📞 Message Callback

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

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"
}'

{
  "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

1. Buka menu Device di dashboard Ping!
2. Pilih atau buat device WhatsApp yang ingin dikonfigurasi
3. Isi field "WebHook Url" dengan URL endpoint Anda (contoh: https://yourdomain.com/webhook)
4. 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"
}

Copy

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"
}

Copy

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"
}

Copy

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"
}

Copy

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"
}

Copy

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"
}'

Copy

⚠️ 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

🐛 Troubleshooting

Error: INVALID_BUSINESS_ID

Error: PACKAGE_NOT_ACTIVE

Webhook Tidak Terkirim

Pesan WhatsApp Tidak Terkirim

📝 Changelog

Berikut adalah daftar perubahan dan update yang telah dilakukan pada platform Ping! Chatbot AI & WhatsApp CRM.