Langsung ke konten utama

​
Mengelola Instance

Sebuah instance merepresentasikan satu nomor WhatsApp yang terhubung ke Wappfy. Setiap instance melewati siklus hidup: buat, hubungkan, pindai QR, gunakan, dan akhirnya putuskan atau hapus.

​
Jenis Instance

Wappfy mendukung dua provider:
JenisDeskripsi
wahaAPI WhatsApp Web self-hosted melalui WAHA Plus. Dukungan fitur lengkap termasuk grup, label, dan kontak.
cloud_apiAPI WhatsApp Business Cloud resmi dari Meta. Memerlukan akun Meta Business.

​
Nilai Status Instance

Sepanjang siklus hidupnya, instance bertransisi melalui status-status berikut:
StatusDeskripsi
createdRecord instance sudah ada tetapi belum dimulai.
startingInstance sedang booting dan menginisialisasi sesi WhatsApp.
scan_qrInstance menunggu Anda untuk memindai kode QR dengan ponsel.
connectedSesi WhatsApp aktif dan siap mengirim/menerima pesan.
disconnectedSesi dihentikan atau kehilangan koneksi. Dapat dihubungkan kembali.
failedInstance mengalami error saat startup atau koneksi.

​
Gambaran Siklus Hidup

​
Membuat Instance

Buat instance WhatsApp baru yang terikat ke akun Anda. 
curl -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My WhatsApp",
    "type": "waha"
  }'
Respons: 
{
  "data": {
    "id": "inst_abc123",
    "name": "My WhatsApp",
    "type": "waha",
    "status": "created",
    "created_at": "2026-02-10T12:00:00Z"
  }
}

​
Menghubungkan Instance

Mulai sesi WhatsApp. Instance akan bertransisi ke starting kemudian ke scan_qr. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/connect \
  -H "X-Api-Key: YOUR_API_KEY"
Respons: 
{
  "data": {
    "id": "inst_abc123",
    "status": "starting"
  }
}

​
Mendapatkan Kode QR

Setelah instance mencapai status scan_qr, ambil kode QR untuk dipindai dengan ponsel Anda. 
curl https://api.wappfy.io/api/instances/inst_abc123/qr \
  -H "X-Api-Key: YOUR_API_KEY"
Respons: 
{
  "data": {
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}
Kode QR kedaluwarsa setelah kurang lebih 60 detik. Jika kedaluwarsa sebelum Anda memindainya, panggil endpoint lagi untuk mendapatkan kode baru.
Buka gambar kode QR dan pindai dengan WhatsApp > Perangkat Tertaut > Tautkan Perangkat di ponsel Anda. Setelah dipindai, status instance akan berubah menjadi connected.

​
Memeriksa Status Instance

Polling endpoint status untuk mengetahui kapan instance siap. 
curl https://api.wappfy.io/api/instances/inst_abc123/status \
  -H "X-Api-Key: YOUR_API_KEY"
Respons: 
{
  "data": {
    "id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}
Daripada polling, atur webhook untuk event instance.connected dan instance.qr agar mendapat notifikasi secara real-time.

​
Melihat Semua Instance

Ambil semua instance untuk akun Anda. 
curl https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY"
Respons: 
{
  "data": [
    {
      "id": "inst_abc123",
      "name": "My WhatsApp",
      "type": "waha",
      "status": "connected"
    },
    {
      "id": "inst_def456",
      "name": "Support Line",
      "type": "waha",
      "status": "disconnected"
    }
  ]
}

​
Memutuskan Instance

Hentikan sesi WhatsApp tanpa menghapus instance. Anda dapat menghubungkan kembali nanti. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/disconnect \
  -H "X-Api-Key: YOUR_API_KEY"

​
Memulai Ulang Instance

Mulai ulang sesi WhatsApp. Berguna jika instance dalam status failed atau berperilaku tidak normal. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/restart \
  -H "X-Api-Key: YOUR_API_KEY"
Memulai ulang mempertahankan sesi WhatsApp yang tertaut. Anda tidak perlu memindai kode QR lagi.

​
Logout Instance

Keluar dari WhatsApp sepenuhnya. Ini memutuskan tautan ponsel dari sesi. Anda perlu memindai kode QR lagi untuk menghubungkan kembali. 
curl -X POST https://api.wappfy.io/api/instances/inst_abc123/logout \
  -H "X-Api-Key: YOUR_API_KEY"
Logout sepenuhnya menghapus tautan WhatsApp. Berbeda dengan disconnect, Anda harus memindai kode QR baru untuk menggunakan instance ini lagi.

​
Menghapus Instance

Hapus instance secara permanen beserta semua data terkaitnya. 
curl -X DELETE https://api.wappfy.io/api/instances/inst_abc123 \
  -H "X-Api-Key: YOUR_API_KEY"
Tindakan ini tidak dapat dibatalkan. Semua pesan, webhook, dan konfigurasi yang terkait dengan instance ini akan dihapus secara permanen.

​
Contoh Siklus Hidup Lengkap

Berikut contoh lengkap yang membuat instance, menghubungkannya, dan melakukan polling untuk kode QR: 
# 1. Create the instance
INSTANCE=$(curl -s -X POST https://api.wappfy.io/api/instances \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "type": "waha"}')

INSTANCE_ID=$(echo $INSTANCE | jq -r '.data.id')
echo "Created instance: $INSTANCE_ID"

# 2. Connect the instance
curl -s -X POST "https://api.wappfy.io/api/instances/$INSTANCE_ID/connect" \
  -H "X-Api-Key: YOUR_API_KEY"

# 3. Wait a moment, then fetch the QR code
sleep 3
QR=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/qr" \
  -H "X-Api-Key: YOUR_API_KEY")

echo $QR | jq -r '.data.qr' > qr-code.png
echo "QR code saved to qr-code.png — scan it with your phone"

# 4. Poll for connected status
while true; do
  STATUS=$(curl -s "https://api.wappfy.io/api/instances/$INSTANCE_ID/status" \
    -H "X-Api-Key: YOUR_API_KEY" | jq -r '.data.status')
  echo "Status: $STATUS"
  if [ "$STATUS" = "connected" ]; then
    echo "Instance is connected and ready!"
    break
  fi
  sleep 2
done

​
Penanganan Error

Kode StatusDeskripsi
404Instance tidak ditemukan atau bukan milik akun Anda.
409Instance sudah dalam status yang diminta (misalnya, sudah terhubung).
422Body permintaan tidak valid (misalnya, name tidak ada atau type tidak valid).
429Batas laju terlampaui. Lihat Batas Laju.