Dokumentasi API
Integrasikan aplikasi Anda dengan WhatsApp Gateway Tdawa. Setiap device memiliki API Key unik yang menjadi kunci autentikasi untuk semua operasi pengiriman dan penerimaan pesan pada device tersebut.
https://wa.tangandiatas.comAPI Key Device
Login dan buat device di dashboard untuk melihat API Key Anda. Atau ganti manual placeholder YOUR_DEVICE_API_KEY di contoh kode.
Autentikasi — API Key per Device
Setiap device WhatsApp yang Anda buat mendapat API Key unik (64 karakter hex). API Key ini adalah satu-satunya kredensial yang dibutuhkan aplikasi eksternal untuk berkomunikasi dengan device tersebut.
- Kirim API Key di header HTTP:
X-API-Key - Device dikenali otomatis dari API Key — tidak perlu menyertakan device ID di URL
- Satu API Key = satu nomor WhatsApp = satu device
- API Key bisa dilihat di Dashboard → halaman device
GET https://wa.tangandiatas.com/api/device
X-API-Key: YOUR_DEVICE_API_KEY
Content-Type: application/jsonQuick Start
- Daftar / login di dashboard, buat device baru
- Scan QR WhatsApp di halaman device
- Salin API Key device tersebut
- Tembak request POST dengan header
X-API-Key
curl -X POST https://wa.tangandiatas.com/api/device/messages \
-H "X-API-Key: YOUR_DEVICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"6281234567890","type":"text","text":"Halo dari API!"}'
const res = await fetch('https://wa.tangandiatas.com/api/device/messages', {
method: 'POST',
headers: {
'X-API-Key': 'YOUR_DEVICE_API_KEY',
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: '6281234567890',
type: 'text',
text: 'Halo dari API!',
}),
});
const data = await res.json();
console.log(data);
$ch = curl_init('https://wa.tangandiatas.com/api/device/messages');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: YOUR_DEVICE_API_KEY',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'to' => '6281234567890',
'type' => 'text',
'text' => 'Halo dari API!',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
import requests
resp = requests.post(
'https://wa.tangandiatas.com/api/device/messages',
headers={'X-API-Key': 'YOUR_DEVICE_API_KEY'},
json={
'to': '6281234567890',
'type': 'text',
'text': 'Halo dari API!',
},
)
print(resp.json())
Info Device & Koneksi
Cek status koneksi device. Device dikenali dari API Key.
Ambil QR code (base64 PNG) untuk pairing WhatsApp. Scan via HP: WhatsApp → Perangkat Tertaut.
Set URL webhook untuk menerima pesan masuk.
{"url": "https://aplikasi-anda.com/wa-webhook"}Putuskan session WhatsApp device (perlu scan QR ulang).
Kirim Pesan
Kirim satu pesan ke nomor tujuan. Device harus status connected.
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
to | string | Ya | Nomor tujuan: 6281234567890 atau JID lengkap |
type | string | Ya | text · image · video · audio · document |
text | string | text | Isi pesan text |
caption | string | Opsional | Caption untuk image/video/document |
media.url | string | media* | URL publik file media |
media.base64 | string | media* | Alternatif: file media dalam base64 |
media.filename | string | Opsional | Nama file (untuk document) |
media.mimetype | string | Opsional | MIME type (contoh: application/pdf) |
Text
curl -X POST https://wa.tangandiatas.com/api/device/messages \
-H "X-API-Key: YOUR_DEVICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"to":"6281234567890","type":"text","text":"Halo!"}'Image (dari URL)
curl -X POST https://wa.tangandiatas.com/api/device/messages \
-H "X-API-Key: YOUR_DEVICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "6281234567890",
"type": "image",
"caption": "Promo hari ini!",
"media": { "url": "https://contoh.com/gambar.jpg" }
}'Document (PDF)
curl -X POST https://wa.tangandiatas.com/api/device/messages \
-H "X-API-Key: YOUR_DEVICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "6281234567890",
"type": "document",
"caption": "Brosur produk",
"media": {
"url": "https://contoh.com/brosur.pdf",
"filename": "brosur.pdf",
"mimetype": "application/pdf"
}
}'Blast Massal
Kirim pesan ke banyak nomor sekaligus. Diproses di background dengan delay acak antar pesan untuk mengurangi risiko banned.
| Field | Tipe | Keterangan |
|---|---|---|
recipients | string[] | Array nomor tujuan |
message | object | Objek pesan (sama format kirim pesan tunggal) |
delayMs.min | number | Delay minimum antar pesan (ms), default 3000 |
delayMs.max | number | Delay maksimum antar pesan (ms), default 8000 |
curl -X POST https://wa.tangandiatas.com/api/device/messages/blast \
-H "X-API-Key: YOUR_DEVICE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"recipients": ["6281111111111", "6282222222222", "6283333333333"],
"message": { "type": "text", "text": "Promo spesial hari ini!" },
"delayMs": { "min": 3000, "max": 8000 }
}'Riwayat Pesan
Ambil riwayat pesan masuk dan keluar device.
| Query | Keterangan |
|---|---|
direction | in (masuk) atau out (keluar) |
jid | Filter nomor: 6281234567890 |
type | Filter tipe: text, image, video, dll |
since / until | Filter rentang waktu (ISO 8601) |
page / limit | Pagination (max 200 per halaman) |
# Pesan masuk saja
curl "https://wa.tangandiatas.com/api/device/messages/incoming?page=1&limit=50" \
-H "X-API-Key: YOUR_DEVICE_API_KEY"
# Filter pesan keluar ke nomor tertentu
curl "https://wa.tangandiatas.com/api/device/messages?direction=out&jid=6281234567890" \
-H "X-API-Key: YOUR_DEVICE_API_KEY"Detail satu pesan.
Download file media pesan masuk.
Webhook Pesan Masuk
Set webhook URL via PUT /api/device/webhook. Setiap pesan masuk akan di-POST ke URL tersebut. Pesan tetap tersimpan di database walau webhook gagal.
Retry: 3x dengan exponential backoff jika webhook gagal.
Payload pesan masuk
Payload status koneksi
Admin API
Endpoint admin memakai header X-Admin-Key (bukan API Key device). Digunakan untuk mengelola user dan device secara programmatic.
| Method | Endpoint | Fungsi |
|---|---|---|
| POST | /api/admin/users | Buat user |
| GET | /api/admin/users | List user + device |
| POST | /api/admin/users/:userId/devices | Buat device → response berisi apiKey |
| GET | /api/admin/users/:userId/devices | List device user |
| DELETE | /api/admin/devices/:deviceId | Hapus device |
# Buat device untuk user id 1 — simpan apiKey dari response!
curl -X POST https://wa.tangandiatas.com/api/admin/users/1/devices \
-H "X-Admin-Key: YOUR_ADMIN_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"WA Marketing"}'
# Response:
# { "success": true, "data": { "id": 1, "apiKey": "529bfbb8...", ... } }Kode Error
| HTTP | Arti |
|---|---|
401 | API Key tidak valid atau tidak dikirim |
400 | Request body tidak valid (field wajib kosong, tipe salah) |
409 | Device belum terhubung ke WhatsApp |
502 | Gagal kirim pesan ke server WhatsApp |
504 | QR code belum tersedia, coba lagi |
Contoh Integrasi Lengkap
Skenario: CRM kirim notifikasi order
CRM Anda memanggil API saat order baru masuk. Satu device = satu nomor WA bisnis.
// Node.js — kirim notifikasi order
async function kirimNotifikasiOrder(nomorHp, orderId, total) {
const res = await fetch('https://wa.tangandiatas.com/api/device/messages', {
method: 'POST',
headers: {
'X-API-Key': process.env.TDAWA_API_KEY, // API Key device WA bisnis
'Content-Type': 'application/json',
},
body: JSON.stringify({
to: nomorHp,
type: 'text',
text: `Order #${orderId} berhasil! Total: Rp ${total.toLocaleString('id-ID')}`,
}),
});
if (!res.ok) throw new Error(await res.text());
return res.json();
}Skenario: Terima balasan customer via webhook
Set webhook URL, lalu handle POST di aplikasi Anda.
// Express.js — handler webhook pesan masuk
app.post('/wa-webhook', express.json(), (req, res) => {
const { event, from, text, type, mediaUrl } = req.body;
if (event === 'message') {
const nomor = from.replace('@s.whatsapp.net', '');
console.log(`Pesan ${type} dari ${nomor}: ${text}`);
// Simpan ke database CRM, auto-reply, dll.
}
res.sendStatus(200); // Wajib respond 200 agar tidak di-retry
});