> For the complete documentation index, see [llms.txt](https://docs.dibales.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dibales.ai/n8n/whatsapp-nodes.md).

# Whatsapp Nodes

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FDHL1Ia72MEZbKBDzhgxN%2Fimage.png?alt=media&amp;token=26ae15cf-dbec-4f5f-b28e-cfda6b2664ed" alt=""><figcaption></figcaption></figure>

Node ini menghubungkan N8N langsung ke akun WhatsApp yang sudah terhubung di dibales.ai. **WhatsApp Trigger** menangkap event masuk sebagai pemicu workflow, sementara **WhatsApp** (action node) berfungsi mengirim pesan.

**Pastikan kamu sudah:**

* Menginstall package `@pake-ai/n8n-nodes-dibales-ai` di instance N8N kamu
* Menghubungkan akun WhatsApp ke dashboard dibales.ai [Integrasi Akun Whatsapp](/whatsapp/integrasi-akun-whatsapp.md)

## Node 1: WhatsApp Trigger

Memulai workflow setiap kali ada event masuk dari akun WhatsApp yang terhubung.

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2F57wTw2Cl2gNNpRBerKfR%2Fimage.png?alt=media&amp;token=4f2a5cf4-ac14-4ab0-adc9-c6269053b24b" alt=""><figcaption></figcaption></figure>

#### Parameter

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2F8FHdJaBPagpV8oWy0fvE%2Fimage.png?alt=media&amp;token=acd02cf7-f2b6-47a7-852a-14022789fbf8" alt=""><figcaption></figcaption></figure>

| Parameter                             | Keterangan                                                                                                                                                                                              |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Webhook URLs**                      | URL endpoint yang didaftarkan ke dashboard dibales.ai. Tersedia dua mode: **Test URL** untuk pengujian saat workflow belum aktif, dan **Production URL** untuk workflow yang sudah aktif dan dipublish. |
| **Signature Verification (Opsional)** | String *webhook secret* yang disalin dari halaman Webhooks di dashboard dibales.ai. Digunakan untuk memverifikasi bahwa kiriman event benar-benar dari sistem dibales.ai.                               |

#### Setup

1. **Tambahkan node WhatsApp Trigger ke workflow kamu** Cari `dibales.ai - WhatsApp` di panel node N8N, pilih sebagai trigger.
2. **Salin Webhook URL** Buka node, expand bagian **Webhook URLs**, klik tab **Test URL & Production URL**, lalu *copy* URL-nya.
3. Buka dashboard dibales.ai, pilih agent yang ingin dihubungkan → [halaman Webhooks](https://app.dibales.ai/agent/integrations/webhooks) → klik Tambah Webhook.

{% hint style="warning" %}
**Baca ini dulu sebelum menyimpan webhook.**

Waktu kamu klik simpan di dashboard, dibales.ai langsung mengirim satu request percobaan ke URL yang kamu daftarkan dan menunggu balasan dengan code `200`. Kalau N8N belum siap menerima, URL itu membalas error dan webhook gagal disimpan.&#x20;
{% endhint %}

**A. Mendaftarkan Test URL**

1. **Salin Test URL:** Di node WhatsApp Trigger, buka tab **Test URL**, lalu salin URL-nya.
2. **Jalankan workflow dalam mode listening:** (tetap di N8N) klik **Execute workflow** (atau **Listen for test event** dari dalam node). Tunggu sampai N8N menampilkan status menunggu event masuk. Biarkan tab N8N tetap terbuka, jangan klik Stop.
3. **Simpan webhook di dashboard dibales.ai, selagi masih listening:** paste Test URL, lalu **Simpan**.

{% hint style="warning" %}
Kalau mode listening sudah berhenti sebelum kamu klik Simpan, dashboard menolak dengan error. Klik **Execute workflow** lagi di N8N, lalu ulangi penyimpanan.
{% endhint %}

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FfKriwutDAabPpGpOK3Sb%2Fimage.png?alt=media&amp;token=0a1c78b2-772e-429c-9ad3-b6bf186adb5f" alt=""><figcaption></figcaption></figure>

**B. Mendaftarkan Production URL**

Production URL baru hidup setelah workflow dipublish. Publish dulu, baru simpan di dashboard.

1. **Publish workflow-nya.** Di N8N klik **Save**, lalu publish workflow lewat toggle di pojok kanan atas. Pastikan statusnya sudah **Active**.
2. **Salin Production URL.** Buka node WhatsApp Trigger, pilih tab **Production URL**, lalu salin URL-nya.
3. **Simpan webhook di dashboard.** Buka halaman **Webhooks** lagi, klik **Tambah Webhook**, paste Production URL, lalu **Simpan**.

{% hint style="warning" %}
Kalau workflow belum dipublish, URL ini belum menerima request apapun dan penyimpanan akan gagal dengan error yang sama.&#x20;
{% endhint %}

<details>

<summary>Signature Verification (Optional)</summary>

{% hint style="info" %}
**Signature Verification (Webhook Secret)** berfungsi untuk mengamankan URL webhook agar tidak bisa diakses tanpa secret key tersebut. Silakan aktifkan jika diperlukan.
{% endhint %}

1. **Salin Webhook Secret** Setelah webhook dibuat, salin nilai **Secret** yang tampil di dashboard.

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FCWKOXxQ2v6jTJihAHdoS%2Fimage.png?alt=media&amp;token=8005b5a9-6150-429e-9d15-c59a324f67a1" alt=""><figcaption></figcaption></figure>

2. **Paste Secret ke node** Kembali ke N8N, buka node Whatsapp Trigger, paste secret ke field **Webhook Secret**, lalu simpan workflow.

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FugtD7JckZ4FcoCUvdYVR%2Fimage.png?alt=media&amp;token=3addd26f-c325-450a-850c-c5d3fc86086b" alt=""><figcaption></figcaption></figure>

</details>

**✅ Selesai! Workflow akan aktif menerima event dari WhatsApp. Setiap event yang masuk akan muncul sebagai satu execution di tab Executions.**

#### Output Ports

Node ini memiliki **8 output port**. Setiap port aktif untuk tipe event yang berbeda, sehingga kamu bisa membuat routing langsung dari satu trigger ke flow yang berbeda.

| Port                        | Event                                                          | Keterangan                                                                      |
| --------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| **0. Message Received**     | Pesan masuk dari kontak                                        | Teks, gambar, video, audio, file, lokasi, atau kontak yang dikirim ke akun kamu |
| **1. Message Echo**         | Pesan yang dikirim dari akun kamu sendiri                      | Berguna untuk logging atau monitoring pesan keluar                              |
| **2. Reaction**             | Kontak menambahkan atau menghapus reaksi emoji pada pesan      | Field `data.reaction.action` berisi `added` atau `removed`                      |
| **4. Read Receipt**         | Pesan yang kamu kirim sudah dibaca oleh kontak                 |                                                                                 |
| **5. Account Connected**    | Akun WhatsApp berhasil terhubung ke sistem dibales.ai          | Berguna untuk notifikasi atau reset state                                       |
| **6. Account Disconnected** | Akun WhatsApp terputus dari sistem dibales.ai, butuh reconnect | Berguna untuk alerting otomatis                                                 |
| **7. Other**                | Event lain yang tidak masuk kategori di atas                   | Bisa dipakai untuk debugging atau menangkap event baru                          |

> 💡 Sambungkan hanya port yang kamu butuhkan. Port yang tidak terhubung tidak akan mempengaruhi performa workflow.

#### Struktur Data Trigger

Payload WhatsApp menggunakan key `data` (berbeda dengan Instagram dan TikTok yang menggunakan `raw`). Gunakan ekspresi berikut untuk mengakses field dari event di node selanjutnya:

**Field tersedia di semua event:**

| Field           | Ekspresi N8N              |
| --------------- | ------------------------- |
| Tipe event      | `{{ $json.event_type }}`  |
| Timestamp event | `{{ $json.occurred_at }}` |

**Untuk event pesan (`Message Received` dan `Message Echo`):**

| Field                  | Ekspresi N8N                          |
| ---------------------- | ------------------------------------- |
| Nomor telepon pengirim | `{{ $json.data.message.from.phone }}` |
| Nama kontak            | `{{ $json.data.message.from.name }}`  |
| WhatsApp ID pengirim   | `{{ $json.data.message.from.wa_id }}` |
| Tipe pesan             | `{{ $json.data.message.type }}`       |
| Isi teks               | `{{ $json.data.message.text }}`       |
| ID pesan               | `{{ $json.data.message.id }}`         |

> 💡 Untuk balas pesan masuk, gunakan `{{ $json.data.message.from.wa_id }}` sebagai **Chat ID** di node WhatsApp Send.

## Node 2: WhatsApp

Action node untuk mengirim pesan dan melakukan lookup kontak melalui akun WhatsApp di dibales.ai.

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FWSoVtGhtcNPOMETtb4oO%2Fimage.png?alt=media&amp;token=5786b7cc-f949-4a03-8517-27e204e3a9b8" alt=""><figcaption></figcaption></figure>

### Credential

Di field **Credential**, pilih credential dengan tipe **dibales.ai account**. Jika belum ada, buat credential baru dan isi dengan API Key yang tersedia di dashboard dibales.ai.

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FqQOJXvxPYsZRM5jBv77A%2Fimage.png?alt=media&amp;token=e8f7e110-9461-4da7-8eb6-a1cca56a1e12" alt=""><figcaption></figcaption></figure>

**Ambil API Key dari dashboard dibales.ai**

<https://app.dibales.ai/agent/integrations/public-api>

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FQY5Py0DWh2vIdygwutMh%2Fimage.png?alt=media&amp;token=784f7774-fb1e-442e-b65a-74015a9fdbbf" alt=""><figcaption></figcaption></figure>

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FExkMK2uVfFp6P5GmsDzy%2Fimage.png?alt=media&amp;token=95d8f315-f556-4617-ad09-96ad78adca75" alt=""><figcaption></figcaption></figure>

***

### Resource: Message

#### **Operation: Send**

<figure><img src="https://2065917909-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKUsDba2MmOSrIeqmsc9J%2Fuploads%2FbjBWHhW2AQVIg275E4US%2Fimage.png?alt=media&amp;token=7d292be4-ce23-4a2e-8515-5282061c16ef" alt=""><figcaption></figcaption></figure>

Kirim pesan ke kontak personal atau grup WhatsApp.

**Parameter utama yang selalu ada:**

| Parameter   | Keterangan                                                                                               |
| ----------- | -------------------------------------------------------------------------------------------------------- |
| **Chat ID** | ID chat tujuan. Format personal: `628xxxxxxxxxx@c.us/99699243663465@lid`. Format grup: ID grup WhatsApp. |
| **Type**    | Pilih tipe pesan yang akan dikirim (lihat daftar di bawah).                                              |

***

**Type: Text**

| Parameter                | Keterangan                                                                                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Text**                 | Isi teks pesan. Mendukung format WhatsApp: `*bold*`, `_italic_`, `~strikethrough~`                                                               |
| **Disable Link Preview** | Toggle. Aktifkan untuk mencegah preview link muncul di bawah pesan. Default: OFF                                                                 |
| **Simulate Typing**      | Toggle. Aktifkan agar sistem menampilkan indikator "sedang mengetik" sesaat sebelum pesan terkirim. Memberikan kesan lebih natural. Default: OFF |
| **Reply To Message ID**  | (Opsional) Isi dengan `message_id` atau `platform_message_id` dari pesan sebelumnya untuk membuat reply berantai.                                |

***

**Type: Image / Video / Audio / File**

| Parameter | Keterangan                                                                           |
| --------- | ------------------------------------------------------------------------------------ |
| **URL**   | URL publik dari file media yang akan dikirim. File harus bisa diakses secara publik. |

***

**Type: Location**

| Parameter     | Keterangan                                  |
| ------------- | ------------------------------------------- |
| **Latitude**  | Koordinat lintang lokasi. Contoh: `-6.2088` |
| **Longitude** | Koordinat bujur lokasi. Contoh: `106.8456`  |

💡 Tambahkan **Name** dan **Address** lokasi lewat **Additional Fields** untuk tampilan yang lebih informatif di WhatsApp.

***

**Type: Contact (vCard)**

| Parameter | Keterangan                                                                      |
| --------- | ------------------------------------------------------------------------------- |
| **vCard** | String format vCard. Minimal berisi `FN` (full name) dan `TEL` (nomor telepon). |

Contoh vCard minimal:

```
BEGIN:VCARD
VERSION:3.0
FN:Nama Kontak
TEL:+628xxxxxxxxxx
END:VCARD
```

***

**Type: Poll**

| Parameter    | Keterangan                                                                               |
| ------------ | ---------------------------------------------------------------------------------------- |
| **Question** | Pertanyaan polling yang akan ditampilkan                                                 |
| **Options**  | Daftar pilihan jawaban. Klik **Add Option** untuk menambah pilihan baru. Minimal 2 opsi. |

***

#### **Operation: React**

Tambahkan reaksi emoji ke pesan yang sudah terkirim.

| Parameter                 | Keterangan                                                                                                  |
| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Platform Message ID**   | ID pesan di WhatsApp yang akan diberi reaksi. Ambil dari output send node sebelumnya: `platform_message_id` |
| **Recipient Platform ID** | ID kontak penerima                                                                                          |
| **Reaction**              | Pilih emoji reaksi dari dropdown                                                                            |

***

#### **Operation: Mark Seen**

Tandai pesan masuk sebagai sudah dibaca. Tidak ada parameter tambahan selain Chat ID dan Message ID.

***

### Resource: Contact

Operasi untuk lookup dan verifikasi informasi kontak WhatsApp. Berguna untuk memvalidasi nomor sebelum mengirim pesan, atau untuk mendapatkan identifier yang dibutuhkan oleh sistem.

| Operation            | Fungsi                                         | Parameter Utama                                      |
| -------------------- | ---------------------------------------------- | ---------------------------------------------------- |
| **Check Phone**      | Cek apakah nomor telepon terdaftar di WhatsApp | `Phone`: nomor format E.164, contoh `+628xxxxxxxxxx` |
| **Get LID by Phone** | Ambil WhatsApp LID dari nomor telepon          | `Phone`: nomor format E.164                          |
| **Get Phone by LID** | Ambil nomor telepon dari WhatsApp LID          | `LID`: WhatsApp LID kontak                           |
| **Get Detail**       | Ambil informasi detail profil kontak           | Identifier kontak                                    |

> 💡 **LID (Linked ID)** adalah identifier internal WhatsApp yang digunakan di beberapa endpoint API. Jika kamu mendapatkan LID dari trigger event, gunakan **Get Phone by LID** untuk mendapatkan nomor teleponnya.

***

#### Output Data

Semua operation di **Resource: Message > Send** mengembalikan output dengan struktur yang konsisten:

| Field                 | Tipe              | Keterangan                                                                 |
| --------------------- | ----------------- | -------------------------------------------------------------------------- |
| `message_id`          | String            | ID pesan di sistem dibales.ai                                              |
| `platform_message_id` | String            | ID pesan asli di WhatsApp. Gunakan ini untuk operation React atau Reply To |
| `sent_at`             | String (ISO 8601) | Timestamp saat pesan terkirim                                              |

Akses field ini di node berikutnya dengan ekspresi: `{{ $json.message_id }}`, `{{ $json.platform_message_id }}`, dst.