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:

Jenis	Deskripsi
`waha`	API WhatsApp Web self-hosted melalui WAHA Plus. Dukungan fitur lengkap termasuk grup, label, dan kontak.
`cloud_api`	API WhatsApp Business Cloud resmi dari Meta. Memerlukan akun Meta Business.

Nilai Status Instance

Sepanjang siklus hidupnya, instance bertransisi melalui status-status berikut:

Status	Deskripsi
`created`	Record instance sudah ada tetapi belum dimulai.
`starting`	Instance sedang booting dan menginisialisasi sesi WhatsApp.
`scan_qr`	Instance menunggu Anda untuk memindai kode QR dengan ponsel.
`connected`	Sesi WhatsApp aktif dan siap mengirim/menerima pesan.
`disconnected`	Sesi dihentikan atau kehilangan koneksi. Dapat dihubungkan kembali.
`failed`	Instance 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"
  }'

const response = await fetch("https://api.wappfy.io/api/instances", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My WhatsApp",
    type: "waha",
  }),
});

const instance = await response.json();
console.log(instance.data.id); // use this ID for all subsequent calls

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"

const response = await fetch(
  "https://api.wappfy.io/api/instances/inst_abc123/qr",
  {
    headers: { "X-Api-Key": "YOUR_API_KEY" },
  }
);

const { data } = await response.json();
// data.qr contains a base64-encoded QR code image

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 Status	Deskripsi
`404`	Instance tidak ditemukan atau bukan milik akun Anda.
`409`	Instance sudah dalam status yang diminta (misalnya, sudah terhubung).
`422`	Body permintaan tidak valid (misalnya, `name` tidak ada atau `type` tidak valid).
`429`	Batas laju terlampaui. Lihat Batas Laju.

​Mengelola Instance

​Jenis Instance

​Nilai Status Instance

​Gambaran Siklus Hidup

​Membuat Instance

​Menghubungkan Instance

​Mendapatkan Kode QR

​Memeriksa Status Instance

​Melihat Semua Instance

​Memutuskan Instance

​Memulai Ulang Instance

​Logout Instance

​Menghapus Instance

​Contoh Siklus Hidup Lengkap

​Penanganan Error

Mengelola Instance

Jenis Instance

Nilai Status Instance

Gambaran Siklus Hidup

Membuat Instance

Menghubungkan Instance

Mendapatkan Kode QR

Memeriksa Status Instance

Melihat Semua Instance

Memutuskan Instance

Memulai Ulang Instance

Logout Instance

Menghapus Instance

Contoh Siklus Hidup Lengkap

Penanganan Error