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.

Base URL
https://wa.tangandiatas.com

API 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/json

Quick Start

  1. Daftar / login di dashboard, buat device baru
  2. Scan QR WhatsApp di halaman device
  3. Salin API Key device tersebut
  4. 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

GET/api/device

Cek status koneksi device. Device dikenali dari API Key.

{ "success": true, "data": { "id": 1, "name": "WA Marketing", "phoneNumber": "6281234567890", "webhookUrl": "https://app.com/webhook", "status": "connected" } }
GET/api/device/qr

Ambil QR code (base64 PNG) untuk pairing WhatsApp. Scan via HP: WhatsApp → Perangkat Tertaut.

PUT/api/device/webhook

Set URL webhook untuk menerima pesan masuk.

{"url": "https://aplikasi-anda.com/wa-webhook"}
POST/api/device/logout

Putuskan session WhatsApp device (perlu scan QR ulang).

Kirim Pesan

POST/api/device/messages

Kirim satu pesan ke nomor tujuan. Device harus status connected.

FieldTipeWajibKeterangan
tostringYaNomor tujuan: 6281234567890 atau JID lengkap
typestringYatext · image · video · audio · document
textstringtextIsi pesan text
captionstringOpsionalCaption untuk image/video/document
media.urlstringmedia*URL publik file media
media.base64stringmedia*Alternatif: file media dalam base64
media.filenamestringOpsionalNama file (untuk document)
media.mimetypestringOpsionalMIME 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"
    }
  }'
// Response sukses (201) { "success": true, "data": { "messageId": 42, "waMessageId": "3EB0...", "to": "6281234567890@s.whatsapp.net", "status": "sent" } }

Blast Massal

POST/api/device/messages/blast

Kirim pesan ke banyak nomor sekaligus. Diproses di background dengan delay acak antar pesan untuk mengurangi risiko banned.

FieldTipeKeterangan
recipientsstring[]Array nomor tujuan
messageobjectObjek pesan (sama format kirim pesan tunggal)
delayMs.minnumberDelay minimum antar pesan (ms), default 3000
delayMs.maxnumberDelay 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

GET/api/device/messages

Ambil riwayat pesan masuk dan keluar device.

QueryKeterangan
directionin (masuk) atau out (keluar)
jidFilter nomor: 6281234567890
typeFilter tipe: text, image, video, dll
since / untilFilter rentang waktu (ISO 8601)
page / limitPagination (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"
GET/api/device/messages/:id

Detail satu pesan.

GET/api/device/messages/:id/media

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

{ "event": "message", "deviceId": 1, "messageId": 123, "waMessageId": "ABCD1234", "from": "6289876543210@s.whatsapp.net", "pushName": "Budi", "type": "text", "text": "Isi pesan", "content": { "text": "Isi pesan" }, "mediaUrl": null, "timestamp": 1765865000000 }

Payload status koneksi

{ "event": "connection", "deviceId": 1, "status": "connected", "phoneNumber": "6281234567890", "timestamp": 1765865000000 }

Admin API

Endpoint admin memakai header X-Admin-Key (bukan API Key device). Digunakan untuk mengelola user dan device secara programmatic.

MethodEndpointFungsi
POST/api/admin/usersBuat user
GET/api/admin/usersList user + device
POST/api/admin/users/:userId/devicesBuat device → response berisi apiKey
GET/api/admin/users/:userId/devicesList device user
DELETE/api/admin/devices/:deviceIdHapus 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

HTTPArti
401API Key tidak valid atau tidak dikirim
400Request body tidak valid (field wajib kosong, tipe salah)
409Device belum terhubung ke WhatsApp
502Gagal kirim pesan ke server WhatsApp
504QR 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
});