REST API · v1

Satu API.
Banyak koneksi.

Kirim pesan WhatsApp pribadi dan grup dari device terpilih. Nama grup dapat dipakai langsung sebagai tujuan.

Base URL

https://wa.ayo-ngopi.my.id/api/v1

01 / Autentikasi

Semua endpoint /api/v1 membutuhkan API key. Gunakan salah satu header:

X-API-Key: YOUR_API_KEY
Authorization: Bearer YOUR_API_KEY

API key memberi akses seluruh device. Simpan di backend atau secret manager, bukan kode frontend publik. Dokumentasi ini tidak menyimpan kredensial dan tidak mengirim request otomatis.

export API_KEY='YOUR_API_KEY'
export DEVICE_ID='UUID-PERANGKAT'
export BASE='https://wa.ayo-ngopi.my.id/api/v1'

curl "$BASE/devices" -H "X-API-Key: $API_KEY"

02 / Kirim pesan teks

POST /messages/text — kirim lewat device_id. Device harus terhubung.

curl "$BASE/messages/text" \
  -H "X-API-Key: $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "device_id": "UUID-PERANGKAT",
    "to": "Nama Grup Anda",
    "message": "Halo dari WhatsApp Gateway",
    "idempotency_key": "event-20261019-001"
  }'

Field	Aturan
`device_id`	UUID perangkat pengirim dari daftar device.
`to`	Nama grup persis, nomor internasional seperti `628123456789`, atau JID grup seperti `120363123456789@g.us`. Maksimum 512 byte pada HTTP.
`message`	Teks tidak kosong, maksimum 65.536 byte.
`idempotency_key`	Kunci unik per peristiwa dan device, 1–128 byte. Jangan ganti kunci saat mengulang request yang sama.

Respons sukses

{
  "success": true,
  "data": {
    "device_id": "UUID-PERANGKAT",
    "message_id": "WHATSAPP_MESSAGE_ID",
    "status": "server_ack",
    "timestamp": "2026-10-19T11:49:17Z"
  }
}

server_ack berarti server WhatsApp menerima pesan, bukan bukti pesan terkirim ke semua anggota atau dibaca. Contoh di halaman ini ilustrasi, bukan hasil request otomatis.

Idempotency

Device + key + tujuan JID/nomor terkonversi + isi sama mengembalikan hasil tersimpan. Payload berbeda memakai key sama menghasilkan konflik. Resolusi nama dilakukan ulang sebelum pemeriksaan idempotency; jika grup berganti nama atau ada nama kembar, replay bisa gagal pada resolusi. Gunakan JID untuk integrasi stabil. Jika hasil outcome_unknown_do_not_resend, jangan kirim ulang dengan key baru karena pesan mungkin sudah diterima WhatsApp.

03 / Nama grup menjadi JID

Nama dicari hanya pada grup milik device pengirim. Cocok persis dan peka huruf besar/kecil; spasi awal/akhir diabaikan. Device harus anggota grup dan diizinkan mengirim. Nama kembar tidak dipilih otomatis.

# Daftar grup: data berisi array {name, jid}
curl "$BASE/devices/$DEVICE_ID/groups" \
  -H "X-API-Key: $API_KEY"

# Konversi tanpa mengirim pesan
curl -G "$BASE/devices/$DEVICE_ID/groups/resolve" \
  -H "X-API-Key: $API_KEY" \
  --data-urlencode 'name=Nama Grup Anda'

{"success":true,"data":{"name":"Nama Grup Anda","jid":"120363123456789@g.us"}}

Tidak ditemukan: 404 group_not_found. Nama kembar: 409 group_name_ambiguous disertai error.candidates. Pilih JID yang benar. Nama grup seluruhnya angka atau mengandung @ harus menggunakan JID; format tersebut dicadangkan untuk nomor/JID pada endpoint kirim.

04 / Endpoint perangkat

Method	Path	Keterangan
GET	`/devices`	Daftar perangkat.
POST	`/devices`	Buat perangkat: `{"name":"Device 01"}`.
GET	`/devices/{id}` `/devices/{id}/status`	Detail / status perangkat.
POST	`/devices/{id}/pair`	Mulai pairing. QR dikirim privat ke admin Telegram, bukan respons API.
GET	`/devices/{id}/pair/status`	Status pairing tanpa QR rahasia.
POST	`/devices/{id}/connect` `/devices/{id}/disconnect` `/devices/{id}/reconnect`	Kelola koneksi sesi.
POST	`/devices/{id}/logout`	Menghapus autentikasi sesi. Wajib header `X-Confirm-Action: logout`.
DELETE	`/devices/{id}`	Hapus perangkat dan sesi. Wajib header `X-Confirm-Action: delete`.
GET	`/gateway/status`	Jumlah device / koneksi.

Pairing juga bisa lewat bot admin Telegram. Akses Telegram dibatasi ke admin yang dikonfigurasi; REST API tetap memakai API key.

05 / Error & batas

{"success":false,"error":{"code":"group_not_found"}}

HTTP	Makna
400	JSON / UUID / pesan tidak valid, atau konfirmasi tindakan belum diberikan.
401	API key salah atau kosong.
404	Grup atau device tidak ditemukan.
409	Konflik state, nama grup kembar, konflik idempotency, atau hasil pengiriman belum pasti.
429	Rate limit. Ikuti header `Retry-After`.
501	Fitur belum diimplementasikan.
503 / 504	Dependency belum siap / operasi timeout.

Body maksimum 1 MiB; field JSON yang tidak dikenal ditolak. Rate limit bawaan 10 request/detik dengan burst 30, dibagi lintas request terautentikasi. Media image/document/video/audio/location/reaction belum didukung dan menghasilkan 501.

06 / Health check

Tanpa API key: /health/live dan /health/ready. Endpoint /metrics membutuhkan API key. Health ready bukan bukti setiap device terhubung.