Reaksi, Read Receipt & Indikator Mengetik

Kontrol status pesan: kirim reaksi emoji, tandai pesan dibaca (blue tick manual), dan tampilkan indikator mengetik.

Tiga endpoint untuk pengalaman chat yang lebih natural dan responsif: reaksi emoji, tanda pesan dibaca, dan indikator mengetik / merekam.

Halaman ini tidak menyediakan endpoint untuk menanyakan status pengiriman sebuah pesan. Status sent / delivered / read / failed hanya dilaporkan lewat webhook — tidak ada endpoint polling.

Ketiga endpoint memerlukan sesi WhatsApp yang hidup saat itu juga: bila perangkat offline, respons 409 device_not_connected.

Base URL

https://dash.ngirimwa.com/api/v1

Headers

x-api-key: API_KEY_ANDA
Content-Type: application/json
Idempotency-Key: <uuid-unik-per-request>

Idempotency-Key opsional; di-scope per endpoint, jadi key yang sama untuk /reaction dan /mark-read tidak saling memengaruhi.

Kirim Reaksi Emoji

Kirim reaksi (😄 👍 ❤️ dll) ke pesan tertentu — milik penerima atau milik Anda sendiri.

Endpoint

POST /messages/reaction

Request — Tambah Reaksi

{
  "to": "628123456789",
  "message": {
    "remote_jid":  "628123456789@s.whatsapp.net",
    "message_id":  "3EB0C12345ABCDEF",
    "from_me":     false
  },
  "emoji": "👍"
}

Request — Hapus Reaksi

Kirim dengan emoji kosong:

{
  "to": "628123456789",
  "message": {
    "remote_jid": "628123456789@s.whatsapp.net",
    "message_id": "3EB0C12345ABCDEF"
  },
  "emoji": ""
}

Parameter

Parameter	Tipe	Wajib	Deskripsi
`to`	string	✅	Nomor lawan bicara (untuk log)
`message.remote_jid`	string	✅	JID chat (biasanya `<phone>@s.whatsapp.net` atau `<id>@g.us` untuk grup)
`message.message_id`	string	✅	ID pesan yang ingin direaksi
`message.from_me`	boolean	❌	`true` jika pesan tersebut Anda yang kirim. Default `false`.
`emoji`	string	✅	Karakter emoji, maksimal 16 karakter. Kosong (`""`) untuk hapus reaksi.

Respon Sukses

{
  "success": true,
  "message": "Reaction queued for delivery",
  "data": { "job_id": "61510", "status": "queued" }
}

Saat menghapus reaksi (emoji: ""), message menjadi Reaction removal queued for delivery. Sama seperti endpoint kirim lain, 200 berarti diantrekan; status: "sent" (dengan job_id: null) hanya bila diserahkan langsung ke WhatsApp.

Mendapatkan `remote_jid` & `message_id`

Keduanya datang dari payload webhook message.received yang dikirim NgirimWA ke webhook_url device Anda. Mapping field:

Field di payload webhook	→ dipakai sebagai
`message.id`	`message_id`
`message.from` + `@s.whatsapp.net` (chat pribadi) atau `metadata.group_id` (grup)	`remote_jid`
`metadata.is_group`	menentukan apakah ini chat pribadi vs grup

Contoh payload message.received yang masuk (bentuk lengkap — lihat Jenis Event Webhook):

{
  "event": "message.received",
  "timestamp": "2026-05-15T10:00:00.000Z",
  "device": { "id": "...", "name": "Toko Saya", "phone": "628111111111" },
  "message": {
    "id":          "3EB0C12345ABCDEF",
    "from":        "628222222222",
    "sender_name": "Budi",
    "type":        "text",
    "content":     "Halo, saya mau tanya",
    "info":        {},
    "timestamp":   1747300800,
    "raw":         { /* objek message Baileys mentah */ }
  },
  "metadata": { "is_group": false, "group_id": null, "is_lid_only": false }
}

Dari payload di atas, untuk membalas reaksi 👍, kirim:

{
  "to": "628222222222",
  "message": {
    "remote_jid": "628222222222@s.whatsapp.net",
    "message_id": "3EB0C12345ABCDEF",
    "from_me":    false
  },
  "emoji": "👍"
}

Lihat Jenis Event Webhook untuk daftar lengkap field.

Tandai Pesan Sebagai Dibaca

Picu blue tick secara manual — berguna bila Anda mematikan auto-read di pengaturan device, atau ingin menandai banyak pesan sekaligus.

Endpoint

POST /messages/mark-read

Request

{
  "to": "628123456789",
  "messages": [
    { "remote_jid": "628123456789@s.whatsapp.net", "message_id": "ABC123" },
    { "remote_jid": "628123456789@s.whatsapp.net", "message_id": "DEF456" }
  ]
}

Parameter

Parameter	Tipe	Wajib	Deskripsi
`to`	string	✅	Nomor lawan bicara (untuk log)
`messages`	array	✅	1–50 key pesan
`messages[].remote_jid`	string	✅	JID chat
`messages[].message_id`	string	✅	ID pesan yang akan ditandai dibaca
`messages[].from_me`	boolean	❌	Default `false`
`messages[].participant`	string	❌	JID partisipan (untuk grup)

Respon Sukses

{
  "success": true,
  "message": "Messages marked as read",
  "data": { "count": 2, "job_id": "12345", "jobId": "12345" }
}

count = jumlah message_id yang dikirim untuk ditandai (bukan jumlah yang terverifikasi terbaca). job_id adalah ID antrean internal (null bila dieksekusi langsung) — boleh diabaikan. jobId adalah alias lama yang deprecated (dihapus setelah 31 Oktober 2026).

Batasan WhatsApp: Pesan tertentu (terlalu lama, sudah dihapus, dsb) mungkin tidak bisa ditandai. API tetap return 200 — gunakan log webhook untuk konfirmasi.

Indikator Mengetik / Merekam

Tampilkan teks “sedang mengetik…” atau “merekam audio…” di sisi penerima — efektif untuk membuat chatbot terasa lebih manusiawi.

Endpoint

POST /messages/presence

Request — Mengetik 3 Detik

{
  "to": "628123456789",
  "state": "composing",
  "duration_ms": 3000
}

Request — Set Online Saja

{
  "to": "628123456789",
  "state": "available"
}

State yang Didukung

`state`	Yang penerima lihat
`composing`	"sedang mengetik..."
`recording`	"merekam audio..."
`paused`	menghentikan indikator mengetik
`available`	status online
`unavailable`	offline

Parameter

Parameter	Tipe	Wajib	Deskripsi
`to`	string	✅	Nomor penerima
`state`	string	✅	Salah satu nilai di atas
`duration_ms`	number	❌	Berapa milidetik state aktif, lalu otomatis `paused` (composing/recording) atau `unavailable`. Maks 30000 ms.

Respon Sukses

{
  "success": true,
  "message": "Presence update sent successfully",
  "data": { "job_id": "12346", "jobId": "12346" }
}

job_id adalah ID antrean internal (null bila dieksekusi langsung) — boleh diabaikan. jobId adalah alias lama yang deprecated (dihapus setelah 31 Oktober 2026).

Pola Penggunaan: Mengetik Sebelum Membalas

# 1. Tampilkan "mengetik..." selama 2 detik
curl -X POST https://dash.ngirimwa.com/api/v1/messages/presence \
  -H "x-api-key: API_KEY_ANDA" -H "Content-Type: application/json" \
  -d '{ "to": "628123456789", "state": "composing", "duration_ms": 2000 }'

# 2. Kirim balasan
curl -X POST https://dash.ngirimwa.com/api/v1/messages/send \
  -H "x-api-key: API_KEY_ANDA" -H "Content-Type: application/json" \
  -d '{ "to": "628123456789", "message": "Halo, ada yang bisa saya bantu?" }'

Atau, untuk efek serupa langsung dari messages/send, pakai opsi humanlike: { enabled: true } di payload. Endpoint presence ini dipakai bila Anda ingin kontrol granular.

Tips

Gabungkan reaksi + mark-read untuk chatbot yang responsif: saat menerima pesan, tandai sebagai dibaca, lalu kirim reaksi 👀 sebagai akknowledgement instan sebelum balasan asli siap.

Indikator mengetik membatasi diri sendiri di WhatsApp — setelah ~25 detik tanpa update, WhatsApp otomatis menyembunyikan indikator. Pakai duration_ms untuk timing yang konsisten.

Mark-read dan presence tidak konsumsi kuota pesan. Reaksi dihitung sebagai pesan (memerlukan langganan aktif & kuota tersisa).

Reaksi, Read Receipt & Indikator Mengetik

On this page