Kirim WhatsApp dengan API KirimWA.id dan cURL

6 min read

Disclaimer
Saya bekerja di AWS, semua opini adalah dari saya pribadi. (I work for AWS, my opinions are my own.)
API KirimWA unofficial WhatsApp API Gateway
API KirimWA.id – https://developer.kirimwa.id/

TeknoCerdas.com – Salam cerdas untuk kita semua. API KirimWA.id adalah layanan unofficial WhatsApp API Gateway untuk mengirimkan pesan WhatsApp dengan melalui HTTP. Pada artikel ini akan ditunjukkan cara kirim WhatsApp dengan API KirimWA.id dan cURL.

cURL adalah sebuah HTTP client berbasis command line interface yang tersedia secara bebas. Utilitas ini hampir ada pada setiap distribusi Linux dan macOS, pada Windows mungkin anda perlu mendownloadnya di https://curl.se/windows/.

Saat artikel ini ditulis API KirimWA.id masih dalam status developer preview. Sehingga untuk mendapatkan API Token anda harus mendaftar di https://developer.kirimwa.id/ terlebih dahulu dan menunggu persetujuan secara manual. Setelah disetujui anda dapat menggunakan layanan API KirimWA.id.

Baca Juga
Kirim WhatsApp dengan API KirimWA.id dan PHP
Kirim WhatsApp dengan API KirimWA.id dan Node.js

Fitur-fitur dari API KirimWA.id diantaranya:

  • API berbasis REST sehingga mudah digunakan
  • Mengirim pesan teks dan gambar
  • Webhook untuk notifikasi pemrosesan pesan
  • Mendukung pengelolaan lebih dari satu nomor atau device

Langkah-langkah untuk mengirimkan pesan adalah:

  1. Tambahkan device melalui POST /v1/devices
  2. Pairing device melalui scan QR code GET /v1/qr
  3. Mengirim pesan teks melalui POST /v1/messages
  4. Cek status pengiriman pesan melalui GET /v1/messages/ID
  5. Menambahkan webhook melalui POST /v1/webhooks
    1. Membuat script penerima webhook
    2. Expose webhook ke Internet
    3. Menambahkan webhook
    4. Tes Webhook

1. Tambahkan Device

Untuk menambahkan device digunakan API endpoint POST /v1/devices. Device adalah perangkat yang terasosiasi dengan nomor WhatsApp yang akan digunakan untuk mengirimkan pesan.

Anda dapat menamakan device id sesuai keinginan. Dalam contoh saya namakan ID nya adalah iphone-x-pro.

$ curl -X POST 'https://api.kirimwa.id/v1/devices' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
    "device_id": "iphone-x-pro"
}'

Jika sukses maka server akan mengembalikan kode HTTP 201 Created.

{
  "id": "iphone-x-pro",
  "status": "disconnected",
  "created_at": "2021-07-09T15:11:53.657Z",
  "meta": {
    "location": "https://api.kirimwa.id/v1/devices/iphone-x-pro"
  }
}

Untuk melihat semua perangkat yang telah ditambahkan gunakan endpoint GET /v1/devices.

{
  "data": [
    {
      "id": "iphone-x-pro",
      "status": "disconnected",
      "created_at": "2021-07-09T15:11:53.657Z",
      "connected_at": "2021-07-18T13:26:57.698Z",
      "disconnected_at": "2021-07-18T13:27:33.089Z",
      "disconnected_reason": "Send message timeout."
    },
    {
      "id": "zenfone-red-1",
      "status": "disconnected",
      "created_at": "2021-07-09T08:40:58.070Z",
      "connected_at": "2021-07-19T13:26:57.698Z",
      "disconnected_at": "2021-07-19T13:27:33.089Z",
      "disconnected_reason": "Send message timeout."
    }
  ],
  "meta": {
    "last_key": "zenfone-red-1"
  }
}

2. Pairing Device Melalui Scan QR Code

Setelah device ditambahkan langkah berikutnya adalah melakukan pairing atau menghubungkan device tersebut ke API KirimWA.id agar terkoneksi. Endpoint yang digunakan adalah GET /v1/qr dengan query string parameter device_id.

$ curl 'https://api.kirimwa.id/v1/qr?device_id=iphone-x-pro'

Jika sukses server akan mengembalikan JSON dengan dua atribut yaitu qr_code dan image_url.

{
  "qr_code": "1@U2tS5Q1elzj6Y7IAKDurwvja47SQz8bvW24fb43r3n+gPC4PN1iSNlGLizlfGsrHSD/M6ym6/aYiYw==,xXlcsqVquva7/1c2g8wAZkWdnk2el5tHWh7MWUW2UTc=,v+P3exsbB1W62wX3Vn4dcC==",
  "image_url": "https://api.kirimwa.id/v1/qr/show?qrcode=1%40U2tS5Q1elzj6Y7IAKDurwvja47SQz8bvW24fb43r3n%2BgPC4PN1iSNlGLizlfGsrHSD%2FM6ym6%2FaYiYw%3D%3D%2CxXlcsqVquva7%2F1c2g8wAZkWdnk2el5tHWh7MWUW2UTc%3D%2Cv%2BP3exsbB1W62wX3Vn4dcC%3D%3D&device_id=iphone-x-pro"
}

Yang harus dilakukan adalah segera copy-paste URL yang ada pada atribut image_url pada browser untuk memunculkan gambar QR code. Setelah itu scan QR code tersebut dengan perangkat yang ingin dikoneksikan dengan API KirimWA.id.

3. Mengirim Pesan Teks

Setelah pairing device, untuk mengirim pesan WhatsApp akan digunakan endpoint POST /v1/messages. API KirimWA.id mendukung dua tipe pesan yaitu teks dan gambar.

Berikut adalah contoh untuk mengirim sebuah pesan WhatsApp dengan format teks. Atribut yang digunakan adalah message_type dengan nilai text. Atribut phone_number digunakan untuk nomor tujuan dan message digunakan untuk isi dari pesan yang akan dikirimkan.

Setiap pengiriman terasosiasi dengan sebuah device_id. Gunakan device_id yang telah ditambahkan sebelumnya.

$ curl -X POST 'https://api.kirimwa.id/v1/messages' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "phone_number": "6281234567890",
  "message": "Halo ini adalah pesan dari api.kirimwa.id",
  "device_id": "iphone-x-pro",
  "message_type": "text"
}'

Pengiriman pada API KirimWA.id bersifat asynchronous dan akan diproses beberapa saat kemudian. Oleh karena itu respon yang didapat ketika mengirim pesan adalah id dari message yang dikirimkan.

Berikut contoh respon dari request sebelumnya.

{
  "id": "kwid-426564a5db7940288dc9fddb845",
  "status": "pending",
  "message": "Message is pending and waiting to be processed.",
  "meta": {
    "location": "https://api.kirimwa.id/v1/messages/kwid-426564a5db7940288dc9fddb845"
  }
}

Dalam terlihat statusnya adalah pending karena ketika respon dikembalikan pemrosesan belum dilakukan. Untuk mengecek status pemrosesan pesan dapat digunakan id dari pesan tersebut.

3.1. Mengirim Pesan Gambar

Tidak ada perbedaan endpoint yang digunakan untuk pengiriman gambar. Yang perlu diubah saat pengiriman adalah atribut message_type dan message.

Nilai atribut message_type untuk gambar harus bernilai image. Sedangkan untuk nilai dari message adalah URL dari gambar. Berikut contoh penggunanannya.

$ curl -X POST 'https://api.kirimwa.id/v1/messages' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "phone_number": "6281234567890",
  "message": "https://rioastamal.net/portfolio/img/rioastamal.jpg",
  "device_id": "iphone-x-pro",
  "message_type": "image",
  "caption": "Foto Profil"
}'

4. Cek Status Pengiriman Pesan

Endpoint yang digunakan untuk mengecek status dari pesan adalah GET /v1/messages/MESSAGE_ID dimana MESSAGE_ID adalah id dari pesan hasil dari pemanggilan endpoint POST /v1/messages.

$ curl 'https://api.kirimwa.id/v1/messages/kwid-426564a5db7940288dc9fddb845' \
  -H 'Authorization: Bearer API_TOKEN'

Respon akan berisi status dari pemrosesan pada atribut status yang dapat berisi pending, success atau fail. Jika masih pending berarti pesan tersebut masih belum diproses.

Berikut contoh respon dari perintah sebelumnya.

{
  "id": "kwid-426564a5db7940288dc9fddb845",
  "message": "Message has been sent.",
  "status": "success",
  "created_at": "2021-07-10T00:16:10.373Z",
  "payload": {
    "message": "Halo ini adalah pesan dari api.kirimwa.id",
    "phone_number": "6281234567890",
    "device_id": "iphone-x-pro",
    "message_type": "text",
    "caption": null
  }
}

Aplikasi anda tentu akan rumit jika harus melakukan pengecekan pesan status secara mandiri artinya secara periodik anda harus menghubungi API KirimWA.id untuk mengetahui status suatu pengiriman pesan. Ini tentu tidak efisien, untuk itulah dihadirkan webhook.

5. Menambahkan Webhook

Dengan menambahkan webhook maka aplikasi anda akan mendapatkan informasi tentang perubahan status dari pengiriman pesan tanpa harus menghubungi server API KirimWA.id.

Ketika sebuah status pemrosesan pesan berubah dari pending ke success atau fail maka API KirimWA.id akan mengirimkan notifikasi ke aplikasi anda lewat URL webhook yang ditambahkan.

Berikut ini adalah contoh data yang dikirimkan pada sebuah webhook lewat HTTP POST.

{
  id: 'kwid-426564a5db7940288dc9fddb812',
  webhook_type: 'send_message_response',
  status: 'success',
  message: 'Message has been sent.',
  payload: {
    message: 'Halo ini adalah pesan dari api.kirimwa.id',
    phone_number: '6281234567890',
    device_id: 'asus-zenfone-1',
    message_type: 'text',
    caption: null
  },
  created_at: '2021-07-10T00:16:10.373Z',
  server_time: '2021-07-19T13:35:00.078Z'
}

5.1. Membuat Script Penerima Webhook

Berikut ini adalah contoh script sederhana yang akan menerima webhook yang dikirimkan oleh API KirimWA.id. Apa yang dilakukan script ini hanyalah melakukan dump data yang dikirimkan.

Pada contoh kali ini saya menggunakan Node.js untuk menerima Webhook dari API KirimWA.id. Buat sebuah direktori dengan nama api-kirimwa-webhook.

$ mkdir api-kirimwa-webhook
$ cd api-kirimwa-webhook

Install Express framework.

$ npm install express

Buat sebuah file dengan nama main.js dan berikut isinya.

const express = require('express');
const app = express();

app.use(express.json());
app.post('/webhook', function(req, res) {
    console.log({ '$body' : req.body });
    console.log({ '$headers' : req.headers });
    res.status(process.env.APP_STATUS_CODE).send({
        message: 'OK.'
    });
});

app.listen(3001, function() {
  console.log(`Example app listening at http://localhost:3001`);
});

Jalankan webhook tersebut yang akan running pada port 3001. Kita akan mengembalikan HTTP 200 OK kepada API KirimWA.id.

$ APP_STATUS_CODE=200 node main.js
Example app listening at http://localhost:3001

5.2. Expose Webhook ke Internet

Saat melakukan testing webhook ke server biasanya kita akan develop dulu di localhost sebelum diupload ke server. Agar API KirimWA.id dapat menghubungi alamat Webhook URL yang dibuat maka ia harus bisa diakses lewat internet. Cara paling mudah untuk membuat localhost diakses dari internet adalah menggunakan layanan seperti ngrok atau Cloudflare Tunnel.

Baca Juga
Mengakses localhost dari Internet dengan SSH Tunneling

Pada contoh ini saya menggunakan Cloudflare Tunnel untuk melakukan expose localhost webhook ke Internet. Saya akan melakukan mapping domain webhooks.teknocerdas.com ke localhost port 3001.

$ cloudflared tunnel --hostname webhooks.teknocerdas.com --url http://localhost:3001

Harusnya sekarang localhost port 3001 bisa diakses dari internet dengan domain https://webhooks.teknocerdas.com.

5.3. Menambahkan Webhook

Langkah berikutnya adalah menambahkan webhook pada API KirimWA.id agar jika proses pengiriman selesai maka webhook yang kita buat akan dipanggil.

Endpoint yang digunakan untuk menambahkan webhook adalah POST /v1/webhooks.

curl -X POST 'https://api.kirimwa.id/v1/webhooks' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "webhook_url": "https://webhooks.teknocerdas.com/webhook"
}'
{
  "id": "whu-YOUR@EMAIL",
  "status": "active",
  "data": "https://webhooks.teknocerdas.com/webhook",
  "created_at": "2021-06-20T17:17:06.333Z",
  "meta": {
    "location": "https://api.kirimwa.id/v1/webhooks"
  }
}

5.4. Tes Webhook

Untuk melakukan tes webhook maka perlu dilakukan pengiriman pesan baru. Jika berhasil harusnya server pada webhooks.teknocerdas.com akan menerima kiriman data lewat HTTP POST yang isinya adalah pesan yang dikirimkan dan status pengirimannya.

$ curl -X POST 'https://api.kirimwa.id/v1/messages' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "phone_number": "6281234567890",
  "message": "Halo ini adalah pesan dari api.kirimwa.id",
  "device_id": "iphone-x-pro",
  "message_type": "text"
}'
{
  "id": "kwid-b930ab810bb44b31909083fcfad",
  "status": "pending",
  "message": "Message is pending and waiting to be processed.",
  "meta": {
    "location": "https://api.kirimwa.id/v1/messages/kwid-b930ab810bb44b31909083fcfad"
  }
}

Cek output pada aplikasi Node.js yang berjalan harusnya muncul log pada terminal yang berisi data yang dikirimkan oleh API KirimWA.id.

{
  '$body': {
    id: 'kwid-b930ab810bb44b31909083fcfad',
    status: 'success',
    message: 'Message has been sent.',
    webhook_type: 'send_message_response',
    payload: {
      message: 'Tes webhook pada API KirimWA.id',
      phone_number: '6281234567890',
      device_id: 'iphone-x-pro',
      message_type: 'text',
      caption: null
    },
    created_at: '2021-07-29T00:37:28.727Z',
    server_time: '2021-07-29T00:37:28.765Z'
  }
}
{
  '$headers': {
    'user-agent': 'API KirimWA/1.0',
    'content-type': 'application/json',
    'content-length': '387',
    host: 'localhost:3001',
    connection: 'close'
  }
}

Terlihat bahwa data berhasil ditangkap oleh aplikasi Node.js yang dibuat. Pada aplikasi yang anda buat mungkin perlu menyimpan log setiap pesan yang dikirim dan statusnya.

Avatar
Rio Astamal Adalah penulis utama di TeknoCerdas.com. Rio Astamal seorang yang sangat antusias dengan web development sejak 2003. Sejak November 2021 Rio Astamal bekerja di Amazon Web Services (AWS) sebagai Developer Advocate untuk Indonesia. Dia mengelola TeknoCerdas.com di waktu senggangnya sebagai salah satu sarana untuk ikut mencerdaskan pembaca dalam dunia IT.
«
»