> For the complete documentation index, see [llms.txt](https://docs.watzap.id/help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.watzap.id/help/integrations/watzap-sdk/instalasi-and-kirim-pesan-pertama.md).

# Instalasi & Kirim Pesan Pertama

Pasang WatZap SDK dan kirim pesan WhatsApp pertama dalam beberapa menit.

Di panduan ini Kamu akan memasang WatZap SDK, lalu mengirim pesan WhatsApp pertama ke nomor HP Kamu sendiri.

## Sebelum mulai

1. Paket akun **Plus** atau **Premium**.
2. **API Key** akun pemilik (owner). Lihat [Mendapatkan API Key di Member Area](/help/integrations/mendapatkan-api-key-di-member-area.md).
3. Nomor pengirim yang sudah terhubung:
   * **WABA Official**: nomor WABA sudah terhubung ke akun. Lihat [Cara Connect Nomor WABA Official](/help/waba-official/cara-connect-nomor-waba-official.md).
   * **Unofficial**: nomor di tab **API** berstatus **Online**, dan Kamu sudah menyalin **Number Key**-nya. Lihat [Mendapatkan Number Key untuk API](/help/integrations/mendapatkan-number-key-untuk-api.md).

## Langkah instalasi

{% stepper %}
{% step %}

### Pastikan Node.js sudah terpasang

Buka terminal (Command Prompt atau PowerShell di Windows), lalu jalankan:

```bash
node -v
```

Kalau muncul `v20.6.0` atau lebih baru, lanjut ke langkah berikutnya. Kalau belum ada atau versinya lebih lama, install versi **LTS** dari [nodejs.org](https://nodejs.org/).

{% hint style="info" %}
SDK sendiri berjalan di Node.js 18 ke atas. Versi 20.6 dibutuhkan karena panduan ini memakai opsi `--env-file` di langkah terakhir.
{% endhint %}
{% endstep %}

{% step %}

### Buat project dan install SDK

```bash
mkdir coba-watzap
cd coba-watzap
npm init -y
npm install @watzapid/sdk
```

{% endstep %}

{% step %}

### Simpan API Key di file `.env`

Buat file bernama `.env` di dalam folder `coba-watzap`, lalu isi:

{% code title=".env" %}

```bash
WATZAP_API_KEY=isi_dengan_api_key_kamu
# Khusus nomor Unofficial:
WATZAP_NUMBER_KEY=isi_dengan_number_key_kamu
```

{% endcode %}

SDK membaca API Key otomatis dari `WATZAP_API_KEY`, jadi API Key tidak perlu ditulis di dalam kode. `WATZAP_NUMBER_KEY` tidak dibaca otomatis. Kode di langkah berikutnya mengambilnya lewat `process.env.WATZAP_NUMBER_KEY`.

{% hint style="danger" %}
Jangan pernah membagikan file `.env` atau meng-upload-nya ke GitHub. Kalau memakai Git, tambahkan `.env` ke file `.gitignore`.
{% endhint %}
{% endstep %}

{% step %}

### Tulis kode untuk mengirim pesan

Buat file `kirim.mjs`, lalu pilih kode sesuai jenis nomor Kamu:

{% tabs %}
{% tab title="WABA Official" %}
{% code title="kirim.mjs" %}

```js
import { WatZap } from '@watzapid/sdk'

const wz = new WatZap() // API Key dibaca otomatis dari WATZAP_API_KEY

const hasil = await wz.whatsapp.messages.sendText({
  to: '081234567890', // ganti dengan nomor HP Kamu
  text: 'Halo! Ini pesan pertama dari WatZap SDK 🎉',
})

console.log('Berhasil! ID pesan:', hasil.id)
```

{% endcode %}

`hasil.id` adalah ID pesan dari Meta (diawali `wamid.`). Simpan ID ini bila Kamu ingin mengecek status pesan nanti.

{% hint style="warning" %}
Pesan teks biasa lewat WABA hanya sampai ke nomor yang **mengirim chat ke nomor WABA Kamu dalam 24 jam terakhir**. Untuk uji coba, kirim chat apa saja dulu dari HP Kamu ke nomor WABA. Di luar 24 jam, kode tetap menampilkan ID pesan, tapi pesannya tidak sampai. Gunakan template. Baca juga [Memahami Aturan 24 Jam WhatsApp](/help/menu-marketing/mengenal-menu-marketing-1.md).
{% endhint %}
{% endtab %}

{% tab title="WhatsApp Unofficial" %}
{% code title="kirim.mjs" %}

```js
import { WatZap } from '@watzapid/sdk'

const wz = new WatZap() // API Key dibaca otomatis dari WATZAP_API_KEY
const nomor = wz.unofficial.device(process.env.WATZAP_NUMBER_KEY)

const hasil = await nomor.messages.sendText({
  to: '081234567890', // ganti dengan nomor HP Kamu
  text: 'Halo! Ini pesan pertama dari WatZap SDK 🎉',
})

console.log('Berhasil! Dikirim dari nomor', hasil.senderNumber)
```

{% endcode %}

Jalur Unofficial tidak mengembalikan ID pesan. Hasilnya berisi `message` (pesan dari server) dan `senderNumber` (nomor pengirim).
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

### Jalankan

```bash
node --env-file=.env kirim.mjs
```

Kalau berhasil, terminal menampilkan tulisan **Berhasil!** dan pesan masuk ke WhatsApp Kamu.
{% endstep %}
{% endstepper %}

## Nomor HP tujuan

Isi `to` dengan format `08…`, `62…`, atau `+62…`. SDK merapikannya otomatis. Untuk nomor luar negeri, awali dengan `+` dan kode negara, misalnya `+6591234567`.

## Pakai `require` atau TypeScript?

Kalau project Kamu memakai CommonJS (`require`), import SDK seperti ini. Di CommonJS, `await` harus berada di dalam fungsi `async`:

{% code title="kirim.js" %}

```js
const { WatZap } = require('@watzapid/sdk')

async function main() {
  const wz = new WatZap()
  const hasil = await wz.whatsapp.messages.sendText({ to: '081234567890', text: 'Halo dari WatZap SDK' })
  console.log('Berhasil! ID pesan:', hasil.id)
}

main().catch((err) => {
  console.error(err.name, err.message)
  process.exitCode = 1
})
```

{% endcode %}

Untuk TypeScript, tipe data sudah disertakan di dalam SDK. Tidak perlu install paket tambahan.

## Pengaturan tambahan (opsional)

```js
import { WatZap } from '@watzapid/sdk'

const wz = new WatZap({
  apiKey: process.env.WATZAP_API_KEY,
  timeout: 60_000,
  maxRetries: 2,
})
```

| Opsi         | Bawaan                 | Fungsi                                                                |
| ------------ | ---------------------- | --------------------------------------------------------------------- |
| `apiKey`     | Nilai `WATZAP_API_KEY` | API Key akun                                                          |
| `timeout`    | `60000` (60 detik)     | Batas waktu satu kali percobaan request, dalam milidetik              |
| `maxRetries` | `2`                    | Jumlah percobaan ulang otomatis saat aman. Isi `0` untuk mematikannya |

Setiap fungsi juga menerima pengaturan khusus sebagai argumen terakhir, khusus untuk panggilan itu saja. Isinya `timeout`, `maxRetries`, atau `signal` (untuk membatalkan request). Contoh:

```js
await wz.whatsapp.messages.sendText({ to: '081234567890', text: 'Halo' }, { timeout: 10_000 })
```

## Masalah umum

<details>

<summary>Muncul "Missing API key"</summary>

SDK tidak menemukan API Key. Pastikan `WATZAP_API_KEY` sudah diisi di file `.env`, dan program dijalankan dengan `node --env-file=.env kirim.mjs`.

</details>

<details>

<summary>Muncul "bad option: --env-file"</summary>

Versi Node.js Kamu lebih lama dari 20.6. Perbarui Node.js ke versi LTS terbaru dari [nodejs.org](https://nodejs.org/).

</details>

<details>

<summary>Muncul "Invalid Secret Key" atau "Invalid API Key"</summary>

API Key salah. Salin ulang API Key dari [member area](/help/integrations/mendapatkan-api-key-di-member-area.md), lalu pastikan tidak ada spasi atau karakter yang ikut tersalin.

</details>

<details>

<summary>Muncul "Need Upgrade Package"</summary>

Paket akun Kamu belum mendukung kirim pesan lewat API. Fitur ini butuh paket **Plus** atau **Premium**.

</details>

<details>

<summary>Muncul "numberKey is required."</summary>

`WATZAP_NUMBER_KEY` belum diisi di file `.env`, atau program tidak dijalankan dengan `--env-file=.env`.

</details>

<details>

<summary>Muncul "License Not Found" atau "Pairing Failed, Access Denied"</summary>

* **License Not Found**: Number Key salah, nomornya sudah dihapus, atau sudah dipindah dari tab **API**. Salin ulang dari [Mendapatkan Number Key untuk API](/help/integrations/mendapatkan-number-key-untuk-api.md).
* **Pairing Failed, Access Denied**: Number Key milik akun lain. Ini juga terjadi bila Kamu memakai API Key akun operator. Gunakan API Key akun pemilik.

</details>

<details>

<summary>Muncul "Please Connect WhatsApp Business API First"</summary>

Belum ada nomor WABA yang terhubung ke akun yang memiliki API Key ini. Hubungkan dulu lewat [Cara Connect Nomor WABA Official](/help/waba-official/cara-connect-nomor-waba-official.md).

</details>

<details>

<summary>WABA: ID pesan muncul, tapi pesan tidak masuk</summary>

Biasanya karena nomor tujuan belum chat ke nomor WABA Kamu dalam 24 jam terakhir. Meta menerima request-nya, lalu menandai pesan gagal beberapa saat kemudian. Cek status pesannya dengan `wz.whatsapp.messages.status(id)`. Kalau statusnya `failed`, alasannya ada di `error`. Contohnya ada di [Contoh Use Case](/help/integrations/watzap-sdk/contoh-use-case.md).

</details>

<details>

<summary>Unofficial: "Kami gagal mengirimkan pesan..." atau "WhatsApp Instance Not Started"</summary>

Nomor Unofficial sedang tidak terhubung. Buka tab **API** di menu **WhatsApp**, klik **Connect** di baris nomor itu, lalu scan QR Code lagi. Sebelum mengirim ulang, cek dulu di HP pengirim apakah pesan sebelumnya ternyata sudah terkirim.

</details>

Daftar lengkap error dan cara menanganinya ada di [Menangani Error](/help/integrations/watzap-sdk/menangani-error.md). Kendala kirim lewat API secara umum dibahas di [Solusi Kendala Kirim Pesan via API](/help/integrations/solusi-kendala-kirim-pesan-via-api.md).

Selanjutnya, lihat [Contoh Use Case](/help/integrations/watzap-sdk/contoh-use-case.md) untuk kebutuhan yang lebih nyata.