Kirim pesan pertama lewat API

Sebelum mulai

Alamat dasar: https://api.gocap.id. Semua endpoint memakai metode POST di alamat ini, tanpa awalan versi.

Autentikasi: header Authorization berisi token device; bentuk Bearer TOKEN_DEVICE juga diterima. Token hanya dibaca dari header Authorization; parameter dikirim di badan permintaan, bukan di query string.

Yang Anda perlukan:

• Device berstatus terhubung di daftar device. Belum punya device? Mulai dari wizard Mulai.
• Token device: token yang tampil sekali saat device dibuat. Bila hilang, buat token baru di pengaturan device; token lama berhenti berlaku.
• Nomor WhatsApp Anda sendiri sebagai target pesan uji.
• Terminal dengan curl. Di Windows PowerShell 5.1 ketik curl.exe, bukan curl: di sana curl adalah alias perintah lain.

Kirim pesan pertama

1. Siapkan token device Anda

   Pakai token yang tampil sekali saat device dibuat. Bila hilang, buat token baru di pengaturan device; token lama berhenti berlaku. Token akun, yang berawalan gc_ (atau wv_ untuk token akun lama), tidak diterima endpoint API.

2. Kirim pesan ke nomor WhatsApp Anda sendiri

   Kirim ke nomor yang sudah pernah berbalas pesan dengan device ini: dari WhatsApp di ponsel Anda, kirim "Halo" ke nomor device lebih dulu, lalu jalankan perintah di bawah ke nomor Anda sendiri. Pesan ke kontak yang belum pernah berbalas pesan dengan device tidak dijamin sampai (lihat OTP dan kontak pertama).

   curl

   Salin

   curl -X POST https://api.gocap.id/send \
     -H 'Authorization: TOKEN_DEVICE' \
     --data-urlencode 'target=NOMOR_TUJUAN' \
     --data-urlencode 'message=Halo dari gocap.
   Simbol % + & tetap utuh.'

   Contoh ini memakai --data-urlencode agar %, +, &, dan baris baru di pesan tiba utuh; -d meneruskan data apa adanya sehingga pesan ber-% dijawab input invalid. Di Windows PowerShell 5.1 ketik curl.exe dan ganti \ di akhir baris dengan backtick (`). Command Prompt (cmd.exe) tidak mengenal kutip tunggal, jadi perintah ini tidak berjalan di sana; pakai PowerShell atau contoh bahasa lain.

   PHP

   Salin

   <?php
   $pesan = "Halo dari gocap.\nSimbol % + & tetap utuh.";
   $ch = curl_init('https://api.gocap.id/send');
   curl_setopt_array($ch, [
       CURLOPT_POST => true,
       CURLOPT_HTTPHEADER => ['Authorization: TOKEN_DEVICE'],
       CURLOPT_POSTFIELDS => [
           'target' => 'NOMOR_TUJUAN',
           'message' => $pesan,
       ],
       CURLOPT_RETURNTRANSFER => true,
       CURLOPT_TIMEOUT => 30,
   ]);
   $raw = curl_exec($ch);
   if ($raw === false) {
       echo 'Koneksi gagal: ', curl_error($ch), PHP_EOL;
       exit(1);
   }
   $data = json_decode($raw, true);
   // Penolakan tetap HTTP 200: periksa status.
   if (empty($data['status'])) {
       $alasan = $data['reason'] ?? $raw;
       echo 'gocap menolak: ', $alasan, PHP_EOL;
       exit(1);
   }
   echo 'requestid ', $data['requestid'], PHP_EOL;

   Butuh ekstensi curl PHP. Array di CURLOPT_POSTFIELDS dikirim sebagai multipart/form-data, bentuk yang sama dengan contoh Fonnte.

   Node.js

   Salin

   const PESAN = "Halo dari gocap.\nSimbol % + & tetap utuh.";
   
   async function main() {
     const res = await fetch("https://api.gocap.id/send", {
       method: "POST",
       headers: { Authorization: "TOKEN_DEVICE" },
       body: new URLSearchParams({
         target: "NOMOR_TUJUAN",
         message: PESAN,
       }),
       signal: AbortSignal.timeout(30000),
     });
     const data = await res.json();
     // Penolakan tetap HTTP 200: periksa status.
     if (!data.status) {
       throw new Error(`gocap menolak: ${data.reason}`);
     }
     console.log("requestid", data.requestid);
   }
   
   main().catch((err) => {
     console.error(err.message);
     process.exitCode = 1;
   });

   Node.js 18 atau lebih baru (fetch bawaan). Simpan sebagai kirim.js, lalu jalankan node kirim.js.

   Python

   Salin

   import requests
   
   PESAN = "Halo dari gocap.\nSimbol % + & tetap utuh."
   
   res = requests.post(
       "https://api.gocap.id/send",
       headers={"Authorization": "TOKEN_DEVICE"},
       data={"target": "NOMOR_TUJUAN", "message": PESAN},
       timeout=30,
   )
   data = res.json()
   # Penolakan tetap HTTP 200: periksa status.
   if not data["status"]:
       raise SystemExit(f"gocap menolak: {data['reason']}")
   print("requestid", data["requestid"])

   Butuh pustaka requests (pip install requests).

   Google Apps Script

   Salin

   // Token device dibaca dari Script Property
   // GOCAP_TOKEN (Project Settings > Script Properties).
   const PESAN = "Halo dari gocap.\nSimbol % + & tetap utuh.";
   
   function kirimGocap() {
     const token = PropertiesService.getScriptProperties()
       .getProperty("GOCAP_TOKEN");
     const url = "https://api.gocap.id/send";
     const res = UrlFetchApp.fetch(url, {
       method: "post",
       headers: { Authorization: token },
       payload: { target: "NOMOR_TUJUAN", message: PESAN },
       muteHttpExceptions: true,
     });
     const data = JSON.parse(res.getContentText());
     // Penolakan tetap HTTP 200: periksa status.
     if (!data.status) {
       throw new Error("gocap menolak: " + data.reason);
     }
     Logger.log("requestid %s", data.requestid);
   }

   Di editor Apps Script, buka Project Settings > Script Properties, lalu tambah properti bernama GOCAP_TOKEN berisi token device; kode membacanya dari sana, jadi token tidak tertulis di kode. Apps Script hanya dapat mengirim (mengapa Apps Script tidak bisa menerima webhook).

   Ganti TOKEN_DEVICE dengan token device Anda dan NOMOR_TUJUAN dengan nomor WhatsApp Anda sendiri, mis. 08… atau 628…; angka 0 di depan otomatis diganti 62.

   {
     "status": true,
     "detail": "success! message in queue",
     "id": [
       "407"
     ],
     "process": "pending",
     "requestid": 101,
     "target": [
       "628xxxxxxxxx"
     ],
     "quota": 299
   }

   "status": true berarti permintaan diterima. "process": "pending" berarti pesan sudah masuk antrian kirim dan dikirim sesudah gocap membalas. requestid adalah nomor permintaan kirim ini.

3. Lihat pesan tiba di WhatsApp

   Buka WhatsApp di ponsel target. Bila pesan tidak muncul, lihat Kalau gagal.

4. Opsional: periksa status koneksi device

   Lihat Cek device untuk arti device_status dan health.

Baca respons

Galat tetap dikembalikan dengan HTTP 200; periksa status dan reason, bukan kode HTTP.

• status: true bila diterima, false bila ditolak.
• reason: alasan penolakan, hanya bila status bernilai false. Cocokkan string-nya persis.
• detail: ringkasan hasil.
• id: id pesan, satu per target, berurutan sama dengan target.
• process: selalu pending; pesan dikirim dari antrian kirim.
• requestid: nomor permintaan kirim; sebutkan saat menghubungi gocap.
• target: target setelah dinormalisasi, berurutan sama dengan permintaan.
• quota: sisa kuota device; null untuk paket Pro.

{
  "status": false,
  "reason": "target invalid"
}

Beberapa keadaan memakai kode lain dengan amplop yang sama: path yang tidak ada dijawab HTTP 404 dengan endpoint not available, kegagalan internal dijawab HTTP 500 dengan reason bebas yang tidak boleh dicocokkan, dan gerbang di depan API dapat menjawab:

• HTTP 503 service unavailable: Gerbang di depan API tidak mendapat jawaban dari layanan gocap: layanan sedang dimulai ulang, terganggu, atau melewati batas waktu.
• HTTP 400 input invalid: Gerbang menolak permintaan yang rusak sebelum sampai ke API, misalnya HTTP polos ke port HTTPS atau header terlalu besar (HTTP/1.1).
• HTTP 413 file size must under 25MB: Badan permintaan melebihi batas ukuran gerbang.

Kalau gagal

Tabel ini memuat reason yang dapat muncul saat memanggil POST /send hari ini, termasuk jawaban gerbang di depan API dan jawaban untuk path yang salah ketik, ditambah kesalahan yang terjadi sebelum permintaan sampai ke gocap.

Masalah berlanjut? Kirim email ke hi@gocap.id dan sertakan requestid dari respons.

Cek device

POST /device mengembalikan keadaan device pemilik token; tidak ada parameter.

curl -X POST https://api.gocap.id/device \
  -H 'Authorization: TOKEN_DEVICE'

{
  "status": true,
  "device": "628xxxxxxxxx",
  "device_status": "connect",
  "expired": "2026-10-23T10:00:00+07:00",
  "messages": 1,
  "name": "Toko Contoh",
  "package": "Free",
  "quota": 299,
  "health": "ok",
  "restricted": false,
  "restricted_until": null
}

device_status menyatakan status koneksi ke WhatsApp:

health menyatakan apakah device sedang dibatasi:

OTP dan kontak pertama

Pola yang dianjurkan:

• Minta pelanggan mengirim pesan lebih dulu, misalnya lewat tautan https://wa.me/NOMOR_DEVICE?text=Halo berlabel "Mulai chat" di formulir Anda. Ganti NOMOR_DEVICE dengan nomor device (field device di respons POST /device).
• Tulis pesan yang mengundang balasan, misalnya "Balas OK untuk mengonfirmasi pesanan".
• Sebelum mengirim OTP, periksa POST /device: device_status, health, dan restricted_until. Selama health bernilai restricted, OTP ikut ditahan sampai Anda memilih "Lanjutkan pengiriman" dan bisa sudah basi saat terkirim; pakai jalur cadangan.
• Kirim ke kontak baru dalam jumlah kecil dan bertahap.
• Siapkan jalur cadangan seperti SMS atau email untuk pesan yang wajib sampai.

Akun WhatsApp Business dapat mengalami pembatasan tambahan "new chat message capping" yang tidak dimodelkan gocap.

Terima pesan masuk

Isi URL webhook pesan masuk di pengaturan device (slot webhook). gocap mengirim pesan masuk ke URL itu sebagai POST JSON bertanda tangan: pesan pribadi aktif bawaan, sedangkan pesan grup hanya bila "Kirim pesan grup ke webhook" dinyalakan di pengaturan device.

• URL wajib https dan dapat dijangkau dari internet; URL http dan alamat jaringan privat ditolak saat disimpan. Untuk pengembangan di komputer sendiri, pakai tunnel HTTPS.
• Balas dengan kode 2xx tanpa badan dalam 10 detik, lalu proses isinya. Badan JSON berisi message atau url menjadi balasan webhook: gocap mengirimnya sebagai pesan WhatsApp ke pengirim (ke grup bila pesan berasal dari grup) dan memakai kuota.
• Kode selain 2xx, termasuk pengalihan 3xx, dan batas waktu yang terlewati dihitung gagal. gocap mencoba lagi dengan jeda 1, 5, 15, lalu 40 menit antar-percobaan: total 5 percobaan dalam ±61 menit, lalu berhenti.
• Pesan yang sama dapat terkirim lebih dari sekali; pakai inboxid untuk membuang duplikat.
• Tombol "Uji webhook" di pengaturan device mengirim satu payload contoh bertanda tangan ke URL yang tersimpan. Tombol ini mengabaikan badan jawaban penerima, jadi tidak dapat dipakai untuk menguji balasan webhook.

Slot webhook koneksi dan status pesan dapat diisi, tetapi belum mengirim event.

Verifikasi tanda tangan

Setiap pengiriman webhook membawa header X-Gocap-Signature dan X-Gocap-Timestamp. Periksa keduanya sebelum memproses isi.

Langkah berikutnya

• Verifikasi tanda tangan webhook (bagian 4.6)Tolak permintaan yang tidak berasal dari gocap.
• Wizard MulaiTekan Segarkan: langkah Kirim pesan pertama tercentang begitu pesan tercatat di kuota device.
• Daftar deviceAtur webhook pesan masuk dan token device.
• Pengaturan akunTampilkan Webhook Secret untuk memverifikasi tanda tangan.