NAV

api.kirimwa.id

Developer Preview

Pengenalan

API KirimWA.id adalah sebuah layanan unofficial WhatsApp API Gateway. Dengan API KirimWA.id anda dapat melakukan otomasi pengiriman pesan WhatsApp lewat HTTP request. API KirimWA.id dapat digunakan untuk mengirim link konfirmasi, OTP, alert, dan berbagai notifikasi yang sesuai dengan keingingan.

Langkah-langkah yang harus dilakukan untuk mulai menggunakan API KirimWA.id adalah:

  1. Daftar untuk mendapatkan API Token
  2. Tambahkan device pada API KirimWA.id
  3. Hubungkan atau pairing device WhatsApp dengan API KirimWA.id
  4. Mulai mengirimkan pesan WhatsApp dengan API KirimWA.id

Langkah opsional berikutnya:

  1. Menambahkan webhook agar ketika pengiriman pesan selesai maka aplikasi anda otomatis akan mendapatkan pemberitahuan.

Pada setiap endpoint API di sebelah kanan terdapat keterangan dan contoh cara penggunaannya di API KirimWA.id.

Layanan ini memerlukan akun WhatsApp yang aktif, dimana anda perlu melakukan scan QR code terlebih dahulu untuk melakukan pairing device antara WhatsApp anda dengan API KirimWA.id. Prosesnya mirip dengan WhatsApp Web karena dibalik layar API KirimWA.id memanfaatkan WhatsApp Web untuk berkomunkasi dengan perangkat WhatsApp anda.

Status

CATATAN PENTING

Saat ini layanan API KirimWA.id masih dalam tahap developer preview sehingga tidak direkomendasikan untuk penggunaan pada production. Dalam tahap ini mungkin akan banyak perubahan karena bug fixes dan fitur-fitur baru akan dihadirkan secara cepat. Selalu pantau halaman ini berkala untuk update terbaru.

Layanan disediakan secara GRATIS saat ini namun dapat berubah sewaktu-waktu dimasa yang akan datang. Perubahan tentunya akan diberitahukan kepada para pengembang yang telah menggunakan layanan ini.

Versi mayor dari API KirimWA.id saat ini adalah v1 sehingga setiap API request akan memiliki prefix /v1.

https://api.kirimwa.id/v1

Otentikasi

API KirimWA.id menggunakan API Token untuk melakukan otentikasi setiap request yang masuk. Untuk mendapatkan API Token silahkan mendaftar pada halaman developer.kirimwa.id. Untuk otentikasi API KirimWA.id mengharapkan API Token dikirim lewat Authorization header atau lewat query string parameter access_token.

curl -H 'Authorization: Bearer API_TOKEN' https://api.kirimwa.id/v1

Atau

curl https://api.kirimwa.id/v1/?access_token=API_TOKEN

Contoh Integrasi

# Lihat pada tab Node.js atau PHP untuk melihat
# contoh fungsi apiKirimWaRequest() yang
# digunakan pada dokumentasi ini.
const https = require('https');

/**
 * Make request to API KirimWA.id
 *
 * @param Object params
 * @return Promise
 */
function apiKirimWaRequest(params)
{
  return new Promise((resolve, reject) => {
    let responseBody = '';
    const options = {
      method: params.method || 'GET',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${params.token}`
      }
    }

    if (params.method === 'POST') {
      const payloadBuffer = Buffer.from(params.payload);
      options.headers['Content-Length'] = payloadBuffer.length;
    }

    const req = https.request(params.url, options, function(res) {
      res.on('data', function concatBody(chunk) {
        responseBody += chunk;
      });

      res.on('end', () => {
        if (res.statusCode >= 200 && res.statusCode < 300) {
          resolve({ body: responseBody, response: res });
          return;
        }

        // Non 2XX response
        reject({ body: responseBody, response: res });
      });
    });

    if (params.method === 'POST') {
      req.write(payloadBuffer);
    }

    req.end();
  }); // Promise
}
<?php

/**
 * Make a request to API KirimWA.id
 *
 * @param Array $params
 * @return Array
 * @throws Exception
 */
function apiKirimWaRequest(array $params) {
  $httpStreamOptions = [
    'method' => $params['method'] ?? 'GET',
    'header' => [
      'Content-Type: application/json',
      'Authorization: Bearer ' . ($params['token'] ?? '')
    ],
    'timeout' => 15,
    'ignore_errors' => true
  ];

  if ($httpStreamOptions['method'] === 'POST') {
    $httpStreamOptions['header'][] = sprintf('Content-Length: %d', strlen($params['payload'] ?? ''));
    $httpStreamOptions['content'] = $params['payload'];
  }

  // Join the headers using CRLF
  $httpStreamOptions['header'] = implode("\r\n", $httpStreamOptions['header']) . "\r\n";

  $stream = stream_context_create(['http' => $httpStreamOptions]);
  $response = file_get_contents($params['url'], false, $stream);

  // Headers response are created magically and injected into
  // variable named $http_response_header
  $httpStatus = $http_response_header[0];

  preg_match('#HTTP/[\d\.]+\s(\d{3})#i', $httpStatus, $matches);

  if (! isset($matches[1])) {
    throw new Exception('Can not fetch HTTP response header.');
  }

  $statusCode = (int)$matches[1];
  if ($statusCode >= 200 && $statusCode < 300) {
    return ['body' => $response, 'statusCode' => $statusCode, 'headers' => $http_response_header];
  }

  throw new Exception($response, $statusCode);
}

Silahkan lihat pada tab sebelah kanan untuk melihat contoh sederhana sebuah fungsi untuk melakukan integrasi dengan API KirimWA.id dengan bahasa pemrograman tertentu.

Saat ini contoh yang kami sediakan adalah untuk cURL, runtime Node.js (Javascript) dan PHP. Anda dapat menggunakan pustaka lain, tidak harus mengikuti contoh yang diberikan sebagai contoh pada PHP anda dapat menggunakan libCURL atau Guzzle.

Untuk bahasa pemrograman lain anda dapat memanfaatkan pustaka HTTP client dari masing-masing bahasa pemrograman untuk melakukan integrasi dengan API KirimWA.id.

Devices

Sebelum dapat mengirim pesan menggunakan API KirimWA.id maka anda perlu menambahkan device terlebih dahulu. Anda dapat memiliki lebih dari satu device pada API KirimWA.id. Sebuah device harusnya terasosiasi dengan sebuah nomor WhatsApp.

POST /devices

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"
}'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/devices');
  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify({
        device_id: 'iphone-x-pro'
    })
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/devices',
    'method' => 'POST',
    'payload' => json_encode([
      'device_id' => 'iphone-x-pro'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 201 Created
Content-Type: application/json
{
  "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"
  }
}

Endpoint ini untuk menambahkan device baru yang bisa digunakan untuk pairing ke API KirimWA.id.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token
Content-Type: application/json Wajib Tipe dari request harus application/json

Body

Body dalam bentuk JSON.

Parameter Wajib Keterangan
device_id Wajib ID dari device yang ingin ditambahkan. Misal iphone-x-pro.

GET /devices

curl 'https://api.kirimwa.id/v1/devices' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/devices');
  // url.searchParams.set('start_key', 'Enter start_key here');
  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/devices'
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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"
  }
}

Untuk merequest halaman berikutnya dapat digunakan nilai dari parameter last_key sebagai input untuk parameter start_key.

curl 'https://api.kirimwa.id/v1/devices?start_key=zenfone-red-1'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/devices');
  url.searchParams.set('start_key', 'zenfone-red-1');
  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query(['start_key' => 'zenfone-red-1']);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/devices?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Endpoint ini untuk melihat semua devices yang sudah dibuat oleh akun anda. Maksimum data yang dikembalikan per page adalah 10 item. Item terkahir yang dikembalikan per halaman ada pada properti last_key. Properti ini kemudian dapat digunakan untuk merequest halaman berikutnya dengan menggunakan query string parameter start_key. Jika nilai dari last_key adalah null maka data sudah habis dan ini adalah halaman terakhir.

Query String Parameter

Parameter Wajib Keterangan
start_key Opsional Nilai dari last_key yang digunakan untuk merequest halaman berikutnya.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

GET /devices/DEVICE_ID

curl 'https://api.kirimwa.id/v1/devices/iphone-x-pro' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const deviceId = process.env.DEVICE_ID;
  const url = new URL('https://api.kirimwa.id/v1/devices/' + deviceId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprint('https://api.kirimwa.id/v1/devices/%s', getenv('DEVICE_ID'))
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "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."
}

Endpoint ini digunakan untuk mendapatkan informasi pada sebuah device berdasarkan DEVICE_ID.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

DELETE /devices/DEVICE_ID

curl -X DELETE 'https://api.kirimwa.id/v1/devices/iphone-x-pro'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const deviceId = process.env.DEVICE_ID;
  const url = new URL('https://api.kirimwa.id/v1/devices/' + deviceId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'DELETE'
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/devices/%s', getenv('DEVICE_ID')),
    'method' => 'DELETE'
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 204 No Content

Endpoint ini digunakan untuk menghapus sebuah device berdasarkan DEVICE_ID. Setelah device dihapus maka request berikutnya seperti mengirim pesan yang menggunakan DEVICE_ID akan gagal.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

QR Code

GET /qr

curl -s \
  'https://api.kirimwa.id/v1/qr?device_id=DEVICE_ID'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
    const deviceId = process.env.DEVICE_ID;
    const url = new URL('https://api.kirimwa.id/v1/qr');
    url.searchParams.set('device_id', deviceId);

    const reqParams = {
      token: process.env.API_TOKEN,
      url: url
    };

    try {
      const { body, response } = await apiKirimWaRequest(reqParams);
      console.log(body);
    } catch (error) {
      console.error('Something went wrong', {
        body: error.body,
        statusCode: error.response.statusCode
      });
    }
  })();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query(['device_id' => getenv('DEVICE_ID')]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/qr?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "qr_code": "[email protected]+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=YOUR_DEVICE_ID"
}

Endpoint ini digunakan untuk mendapatkan QR code yang digunakan untuk melakukan pairing device ke API KirimWA.id. Terdapat dua atribut yang dikembalikan yaitu qr_code dan image_url.

Untuk menampilkan gambar QR Code kunjungi link URL yang ada terdapat pada image_url kemudian scan QR code tersebut dengan WhatsApp.

Query String Parameter

Parameter Wajib Keterangan
device_id Wajib WhatsApp device yang akan dikoneksikan atau dipairing dengan API KirimWA.id.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

Groups

GET /groups

curl 'https://api.kirimwa.id/v1/groups?device_id=DEVICE_ID' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const deviceId = process.env.DEVICE_ID;
  const url = new URL('https://api.kirimwa.id/v1/groups');
  url.searchParams.set('device_id', deviceId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query(['device_id' => getenv('DEVICE_ID')]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/groups?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "message": "Contacts has been synced.",
  "data": [
    {
      "id": "6281234567890-1628639680",
      "name": "Grup Keluarga Besar"
    },
    {
      "id": "6281234567890-1628639662",
      "name": "Developer Tim"
    }
  ]
}

Jika query dilakukan saat koneksi perangkat terputus maka API KirimWA.id akan coba melakukan koneksi ulang ke perangkat. Sehingga hasil yang didapatkan mungkin kosong.

{
  "message": "Contacts is being sync.",
  "data": []
}

Tunggu beberapa detik karena kontak akan disinkronisasi ulang. Setelah itu lakukan hit ulang ke endpoint.

Endpoint ini digunakan untuk mendapatkan daftar group yang ada.

Query String Parameter

Parameter Wajib Keterangan
device_id Wajib Target device yang digunakan.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

GET /groups/GROUP_ID

curl 'https://api.kirimwa.id/v1/groups/6281234567890-1628639680?device_id=DEVICE_ID' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const deviceId = process.env.DEVICE_ID;
  const groupId = process.env.GROUP_ID;
  const url = new URL('https://api.kirimwa.id/v1/groups/' + groupId);
  url.searchParams.set('device_id', deviceId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query(['device_id' => getenv('DEVICE_ID')]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/groups/%s?%s', getenv('GROUP_ID'), $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": [
    "6281234567890",
    "6281234567891",
    "6281234567892",
    "6281234567893",
    "6281234567894",
    "6281234567895"
  ],
  "meta": {
    "name": "Grup Keluarga Besar",
    "admins": [
      "6281234567890"
    ],
    "created_at": "2019-09-22T12:31:30.000Z",
    "number_of_participants": 6
  }
}

Endpoint ini digunakan untuk mendapatkan daftar anggota dan metadata pada sebuah grup berdasarkan GROUP_ID.

Query String Parameter

Parameter Wajib Keterangan
device_id Wajib Target device yang digunakan.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

Messages

Saat ini API KirimWA.id mendukung pengiriman pesan teks dan gambar. Pengiriman pesan pada API KirimWA.id bersifat asynchronous. Artinya pesan yang dikirim akan masuk ke queue (antrian) server API KirimWA.id. Proses ini sangat cepat biasanya hanya memerlukan waktu beberapa detik untuk queue diproses.

API KirimWA.id mendukung pengiriman pesan ke nomor WhatsApp individu atau sebuah grup WhatsApp.

Selain itu API KirimWA.id juga dapat mengirimkan pesan secara terjadwal. Dimana pesan akan dikirim sesuai dengan tanggal dan waktu yang ditentukan.

Kirim Pesan ke Grup

Jika mengirim ke individu maka yang digunakan adalah nomor WhatsApp tujuan. Sedangkan untuk grup digunakan ID dari grup. Untuk mendapatkan daftar ID dari grup WhatsApp gunakan endpoint GET /groups.

Jika mengirim pesan ke grup maka atribut is_group_message harus diset ke nilai true.

Jika ingin mention seseorang pada grup maka didalam pesan yang dikirim gunakan tanda @ lalu ikuti dengan nomor WhatsApp dari pengguna tersebut misal @6281234567890. Mention juga dapat dimasukkan ke caption jika pesan yang dikirimkan adalah gambar.

Kirim Pesan Terjadwal

Untuk mengirim pesan terjadwal maka atribut yang harus dikirimkan adalah send_at dan nilainya sesuai dengan standard ISO 8601. Sebagai contoh jika ingin mengirimkan pesan pada tanggal 15 Oktober 2021 jam 14:30 Waktu Indonesia Barat GMT+7 maka format yang dikirimkan adalah 2021-10-15T14:30:00+07:00.

Atribut send_at bersifat opsional jika tidak dikirimkan maka secara default pesan akan langsung dikirim. Hal yang sama juga berlaku jika nilainya now maka pesan akan langsung dikirim.

POST /messages

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"
}
'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/messages');
  const message = {
    message: 'Halo ini adalah pesan dari api.kirimwa.id',
    phone_number: '6281234567890',
    message_type: 'text',
    device_id: 'iphone-x-pro'
  }

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify(message)
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/messages',
    'method' => 'POST',
    'payload' => json_encode([
      'message' => 'Halo ini adalah pesan dari api.kirimwa.id.',
      'phone_number' => '6281234567890',
      'message_type' => 'text',
      'device_id' => 'iphone-x-pro'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 201 Created
Content-Type: application/json
{
  "id": "kwid-426564a5db7940288dc9fddb845",
  "status": "pending",
  "message": "Message is pending and waiting to be processed.",
  "meta": {
    "location": "https://api.kirimwa.id/v1/messages/kwid-426564a5db7940288dc9fddb845"
  }
}

Nilai dari message_id dapat anda gunakan untuk mengetahui status pengiriman dari sebuah pesan dengan melakukan request pada endpoint GET /messages/MESSAGE_ID.

Berikut adalah contoh request untuk mengirimkan pesan dalam bentuk gambar.

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"
}
'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/messages');
  const message = {
    message: 'https://rioastamal.net/portfolio/img/rioastamal.jpg',
    phone_number: '6281234567890',
    message_type: 'image',
    device_id: 'iphone-x-pro',
    caption: 'Foto Profil'
  }

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify(message)
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/messages',
    'method' => 'POST',
    'payload' => json_encode([
      'message' => 'https://rioastamal.net/portfolio/img/rioastamal.jpg',
      'phone_number' => '6281234567890',
      'message_type' => 'image',
      'device_id' => 'iphone-x-pro',
      'caption' => 'Foto Profil'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Berikut adalah contoh mengirim pesan dalam bentuk dokumen. Jenis dokumen bisa berupa file apa saja pdf, docx, xlsx, mp3, mp4, jpg, gif dan lainnya. Caption pada pengiriman document digunakan sebagai nama file. Contoh dibawah akan menyimpan file dengan nama ebook.pdf.

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/files/ebook/dasar2-web-programming-1.0.pdf",
  "device_id": "iphone-x-pro",
  "message_type": "document",
  "caption": "ebook.pdf"
}
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/messages');
  const message = {
    message: 'https://rioastamal.net/files/ebook/dasar2-web-programming-1.0.pdf',
    phone_number: '6281234567890',
    message_type: 'document',
    device_id: 'iphone-x-pro',
    caption: 'ebook.pdf'
  }

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify(message)
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/messages',
    'method' => 'POST',
    'payload' => json_encode([
      'message' => 'https://rioastamal.net/files/ebook/dasar2-web-programming-1.0.pdf',
      'phone_number' => '6281234567890',
      'message_type' => 'document',
      'device_id' => 'iphone-x-pro',
      'caption' => 'ebook.pdf'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Berikut adalah contoh mengirim pesan ke grup dengan ID 6281234567890-1628639680 dengan tipe pesan text.

curl -X POST 'https://api.kirimwa.id/v1/messages' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "phone_number": "6281234567890-1628639680",
  "message": "Halo semua ini dari api.kirimwa.id",
  "device_id": "iphone-x-pro",
  "message_type": "text",
  "is_group_message": true
}
'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/messages');
  const message = {
    message: 'Halo semua ini dari api.kirimwa.id',
    phone_number: '6281234567890-1628639680',
    message_type: 'text',
    device_id: 'iphone-x-pro',
    is_group_message: true
  }

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify(message)
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/messages',
    'method' => 'POST',
    'payload' => json_encode([
      'message' => 'Halo semua ini dari api.kirimwa.id',
      'phone_number' => '6281234567890-1628639680',
      'message_type' => 'text',
      'device_id' => 'iphone-x-pro'
      'is_group_message' => true
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Endpoint ini digunakan untuk mengirimkan pesan baik teks, gambar atau dokumen (segala jenis file).

Beberapa batasan untuk pengiriman pesan diantaranya:

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token
Content-Type: application/json Wajib Tipe dari request harus application/json

Body

Body dalam bentuk JSON.

Parameter Wajib Keterangan
phone_number Wajib Nomor WhatsApp tujuan dalam format internasional TANPA tanda +. Misal 6281234567890. Jika mengirim ke Grup maka ini adalah ID dari Grup yang bisa dilihat di GET /groups.
message Wajib Pesan yang akan dikirimkan. Jika message_type berupa image atau document maka ini adalah HTTP URL dari image atau dokumen tersebut.
device_id Wajib Device yang akan digunakan untuk mengirim.
message_type Opsional Tipe dari pesan yaitu text, image, atau document. Default adalah text.
caption Opsional Jika tipe pesan adalah image anda dapat menambahkan caption yaitu teks yang akan ditampilkan dibawah gambar. Jika pesan berupa document maka caption ini akan menjadi nama file untuk dokumen tersebut.
is_group_message Opsional Pesan untuk grup atau individu. Jika untuk grup nilainya true, sedangkan false untuk individu. Default adalah false yaitu untuk individu.
send_at Opsional Jadwal untuk tanggal dan waktu pesan akan dikirim. Default adalah now. Contoh agar pesan terkirim pada tanggal 05 Oktober 2021 jam 02:15 dini hari GMT+7 maka nilainya 2021-10-05T02:15:00+07:00.

GET /messages

curl 'https://api.kirimwa.id/v1/messages' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/messages');
  // Do some filter
  // --------------
  url.searchParams.set('status', 'success'); // value: success | fail
  // url.searchParams.set('start_key', 'some_value');
  // url.searchParams.set('date', '2021-07-01');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
    $query = http_build_query([
      'status' => 'success',
      'start_key' => '',
      'date' => ''
    ]);
    $reqParams = [
      'token' => getenv('API_TOKEN'),
      'url' => sprintf('https://api.kirimwa.id/v1/messages?%s', $query)
    ];

    $response = apiKirimWaRequest($reqParams);
    echo $response['body'];
  } catch (Exception $e) {
    print_r($e);
  }

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": [
    {
      "id": "kwid-426564a5db7940288dc9fddb845",
      "message": "Message has been sent.",
      "status": "success",
      "created_at": "2021-07-10T00:18:30.614Z",
      "payload": {
        "message": "Halo ini adalah pesan dari api.kirimwa.id",
        "phone_number": "6281234567890",
        "device_id": "iphone-x-pro",
        "message_type": "text",
        "caption": null,
        "is_group_message": false
      }
    },
    {
      "id": "kwid-426564a5db7940288dc9fddb812",
      "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": "asus-zenfone-1",
        "message_type": "text",
        "catption": null,
        "is_group_message": false
      }
    }
  ],
  "meta": {
    "last_key": "kwid-426564a5db7940288dc9fddb812"
  }
}

Untuk merequest pesan pada halaman berikutnya dapat digunakan nilai dari parameter last_key sebagai input untuk parameter start_key.

curl 'https://api.kirimwa.id/v1/messages?start_key=kwid-426564a5db7940288dc9fddb812' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/messages');
  // Do some filter
  // --------------
  url.searchParams.set('status', 'success'); // value: success | fail
  url.searchParams.set('start_key', 'kwid-426564a5db7940288dc9fddb812');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query([
    'status' => 'success',
    'start_key' => 'kwid-426564a5db7940288dc9fddb812'
  ]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/messages?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Endpoint ini digunakan untuk mendapatkan semua pesan yang dikirim dengan menggunakan endpoint POST /messages. Maksimum data yang dikembalikan per request adalah 10 item. Untuk merequest item berikutnya gunakan nilai dari atribut last_key dan gunakan sebagai input untuk parameter start_key. Jika nilai dari last_key adalah null maka data sudah habis dan ini adalah halaman terakhir.

Query String Parameter

Parameter Wajib Keterangan
start_key Opsional Nilai dari last_key yang digunakan untuk merequest halaman berikutnya.
status Opsional Status pemrosesan pesan yaitu pending, success, atau fail. Default adalah success.
date Opsional Tanggal pesan dikirim dalam format YYYY-MM-DD, contoh 2021-07-10.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

GET /messages/MESSAGE_ID

curl 'https://api.kirimwa.id/v1/messages/kwid-426564a5db7940288dc9fddb812' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const messageId = process.env.MESSAGE_ID;
  const url = new URL('https://api.kirimwa.id/v1/messages/' + messageId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/messages/%s', getenv('MESSAGE_ID'))
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "kwid-426564a5db7940288dc9fddb812",
  "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": "asus-zenfone-1",
    "message_type": "text",
    "caption": null,
    "is_group_message": false
  }
}

Endpoint ini digunakan untuk mendapatkan informasi sebuah message berdasarkan MESSAGE_ID.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

Incoming Messages

Ketika ada pesan baru masuk di WhatsApp maka API KirimWA.id otomatis akan mengirimkan payload ke webhook yang telah anda ditentukan seperti dijelaskan pada Webhook Incoming Message. Setiap pesan yang masuk akan disimpan dan dapat dilihat menggunakan API GET /incoming-messages berikut.

GET /incoming-messages

curl -X POST 'https://api.kirimwa.id/v1/incoming-messages?device_id=DEVICE_ID' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const deviceId = process.env.DEVICE_ID;
  const url = new URL('https://api.kirimwa.id/v1/incoming-messages');
  // Do some filter
  // --------------
  url.searchParams.set('device_id', deviceId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query([
    'device_id' => getenv('DEVICE_ID')
  ]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/incoming-messages?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": [
    {
      "id": "3EB07079D3331BA4746C",
      "device_id": "iphone-x-pro",
      "message_type": "text",
      "timestamp": 1631369848,
      "text": "Hello incoming message from api.kirimwa.id",
      "group_id": "6281234567890-1628639662",
      "is_group_message": true,
      "sender": "6281234567891",
      "caption": null,
      "from_me": false,
      "created_at": "2021-09-11T14:17:29.291Z",
      "location": {
        "name": null,
        "address": null,
        "latitude": 0,
        "longitude": 0
      },
      "contact": {
        "name": null,
        "vcard": null
      },
      "meta": {
        "seconds": 0,
        "size": 42,
        "mime_type": "plain/text",
        "dimension": {
          "width": 0,
          "height": 0
        },
        "file_name": null
      }
    },
    {
      "id": "3EB07079D3331BA471ER",
      "device_id": "iphone-x-pro",
      "message_type": "text",
      "timestamp": 1631369848,
      "text": "Hello from api.kirimwa.id",
      "group_id": null,
      "is_group_message": false,
      "sender": "6281234567890",
      "caption": null,
      "from_me": false,
      "created_at": "2021-09-11T14:17:29.291Z",
      "location": {
        "name": null,
        "address": null,
        "latitude": 0,
        "longitude": 0
      },
      "contact": {
        "name": null,
        "vcard": null
      },
      "meta": {
        "seconds": 0,
        "size": 25,
        "mime_type": "plain/text",
        "dimension": {
          "width": 0,
          "height": 0
        },
        "file_name": null
      }
    }
  ],
  "meta": {
    "last_key": null
  }
}

Endpoint untuk melihat pesan yang masuk ke WhatsApp sesuai dengan device ID.

Query String Parameter

Parameter Wajib Keterangan
device_id Wajib Device ID untuk pesan yang masuk.
start_key Opsional Nilai dari last_key yang digunakan untuk merequest halaman berikutnya.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

Batch Messages

Batch messages adalah proses mengirim pesan WhatsApp ke banyak penerima sekaligus dalam satu waktu. Dengan proses ini misal anda ingin mengirimkan pesan ke 10 penerima dalam satu waktu maka cukup lakukan satu kali request API ke batch messages tidak perlu melakukan 10 kali hit API. Sehingga lebih efisien karena HTTP request dilakukan hanya sekali.

Default jumlah pesan yang dapat dikirim dalam satu waktu adalah 50 pesan dalam satu kali batch request. Jumlah pesan yang dikirim pada setiap batch akan mengungari quota pesan hari ini. Misal sisa quota pesan hari ini adalah 10 pesan sedangkan jumlah pesan pada batch yang dikirim adalah 15 maka request akan ditolak.

POST /batch-messages

curl -X POST 'https://api.kirimwa.id/v1/batch-messages' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "messages": [
    {
      "message": "Hello from api.kirimwa.id - #1",
      "phone_number": "6281234567890",
      "message_type": "text"
    },
    {
      "message": "https://rioastamal.net/portfolio/img/rioastamal.jpg",
      "caption": "Hello from api.kirimwa.id - #2",
      "phone_number": "6281234567890-1628639662",
      "is_group_message": true,
      "message_type": "image",
      "send_at": "2021-10-17T06:50:05+07:00"
    }
  ],
  "device_id": "iphone-x-pro"
}
'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/batch-messages');
  const batchMessage = {
    messages: [
      {
        message: 'Hello from api.kirimwa.id - #1',
        phone_number: '6281234567890',
        message_type: 'text'
      },
      {
        // Scheduled image message
        message: 'https://rioastamal.net/portfolio/img/rioastamal.jpg?build=202001140325',
        caption: 'Hello from api.kirimwa.id - #2',
        phone_number: '6281234567890-1628639662',
        is_group_message: true,
        message_type: 'image',
        send_at: '2021-10-17T06:50:05+07:00'
      }
    ],
    device_id: 'iphone-x-pro'
  }

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify(batchMessage)
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/batch-messages',
    'method' => 'POST',
    'payload' => json_encode([
      'messages' => [
        [
          'message' => 'Hello from api.kirimwa.id - #1',
          'phone_number' => '6281234567890',
          'message_type' => 'text'
        ],
        [
          // Scheduled image message
          'message' => 'https://rioastamal.net/portfolio/img/rioastamal.jpg?build=202001140325',
          'caption' => 'Hello from api.kirimwa.id - #2',
          'phone_number' => '6281234567890-1628639662',
          'is_group_message' => true,
          'message_type' => 'image',
          'send_at' => '2021-10-17T06:50:05+07:00'
        ]
      ],
      'device_id' => 'iphone-x-pro'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "720ef393-0ba1-4dd1-9543-b9b03c35c247",
  "message": "Messages are being processed.",
  "meta": {
    "number_of_messages": 2,
    "location": "https://api.kirimwa.id/v1/batch-messages/720ef393-0ba1-4dd1-9543-b9b03c35c247"
  }
}

Endpoint ini digunakan untuk mengirimkan pesan teks, gambar atau file document secara batch artinya dalam satu kali request anda dapat mengirimkan pesan ke banyak penerima sekaligus.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token
Content-Type: application/json Wajib Tipe dari request harus application/json

Body

Body dalam bentuk JSON.

Parameter Wajib Keterangan
messages Wajib Array of message dari pesan yang akan dikirimkan. Nilai dari setiap tiap atribut message sama dengan parameter pada POST /messages minus atribut device_id.
device_id Wajib Device yang akan digunakan untuk mengirim.

GET /batch-messages

curl 'https://api.kirimwa.id/v1/batch-messages' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/batch-messages');
  // Do some filter
  // --------------
  url.searchParams.set('device_id', 'iphone-x-pro');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query([
    'device_id' => 'iphone-x-pro'
  ]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/batch-messages?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": [
    {
      "id": "dae788e2-4227-45ab-8063-0f8c492341a5",
      "device_id": "iphone-x-pro",
      "created_at": "2021-10-17T10:12:44.067Z",
      "number_of_messages": 2,
      "messages": {
        "processed": [
          {
            "value": {
              "meta": {
                "location": "https://api.kirimwa.id/v1/messages/kwid-9d643c1a6cb64eeea6aaec542f9"
              },
              "id": "kwid-9d643c1a6cb64eeea6aaec542f9"
            },
            "payload": {
              "caption": "@see meta.location",
              "phone_number": "6281234567890",
              "message_type": "text",
              "message": "@see meta.location"
            }
          }
        ],
        "failed": [
          {
            "reason": "Error: Invalid image format, allowed format are JPEG, PNG and GIF.",
            "payload": {
              "send_at": "2021-10-17T06:50:05+07:00",
              "is_group_message": true,
              "caption": "@see meta.location",
              "phone_number": "6281234567890-1628639662",
              "message_type": "image",
              "message": "@see meta.location"
            }
          }
        ]
      }
    },
    {
      "id": "f7f0c933-8247-472d-8546-9c825eecb6e6",
      "device_id": "iphone-x-pro",
      "created_at": "2021-10-17T10:10:37.973Z",
      "number_of_messages": 2,
      "messages": {
        "processed": [
          {
            "value": {
              "meta": {
                "location": "https://api.kirimwa.id/v1/messages/kwid-2596f2e699154404aa41d078e34"
              },
              "id": "kwid-2596f2e699154404aa41d078e34"
            },
            "payload": {
              "caption": "@see meta.location",
              "phone_number": "6281234567890",
              "message_type": "text",
              "message": "@see meta.location"
            }
          },
          {
            "value": {
              "meta": {
                "location": "https://api.kirimwa.id/v1/messages/kwid-43c15386182c4175908b2f91738"
              },
              "id": "kwid-43c15386182c4175908b2f91738"
            },
            "payload": {
              "send_at": "2021-10-17T06:50:05+07:00",
              "is_group_message": true,
              "caption": "@see meta.location",
              "phone_number": "6281234567890-1628639661",
              "message_type": "image",
              "message": "@see meta.location"
            }
          }
        ],
        "failed": []
      }
    }
  ],
  "meta": {
    "last_key": null
  }
}

Endpoint ini digunakan untuk melihat semua pesan batch yang telah dikirim. Dimana pada setiap pesan batch tersebut terdapat pesan yang sudah diproses processed dan pesan yang gagal dikirim failed.

Query String Parameter

Parameter Wajib Keterangan
device_id Wajib Pesan batch yang dikirim berdasarkan device id.
start_key Opsional Nilai dari meta.last_key yang digunakan untuk merequest halaman berikutnya.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

GET /batch-messages/BATCH_ID

curl 'https://api.kirimwa.id/v1/batch-messages/dae788e2-4227-45ab-8063-0f8c492341a5' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const messageId = process.env.MESSAGE_ID;
  const url = new URL('https://api.kirimwa.id/v1/batch-messages/' + messageId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/batch-messages/%s', getenv('MESSAGE_ID'))
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "dae788e2-4227-45ab-8063-0f8c492341a5",
  "device_id": "iphone-x-pro",
  "created_at": "2021-10-17T10:12:44.067Z",
  "number_of_messages": 2,
  "messages": {
    "processed": [
      {
        "value": {
          "meta": {
            "location": "https://api.kirimwa.id/v1/messages/kwid-9d643c1a6cb64eeea6aaec542f9"
          },
          "id": "kwid-9d643c1a6cb64eeea6aaec542f9"
        },
        "payload": {
          "caption": "@see meta.location",
          "phone_number": "6281234567890",
          "message_type": "text",
          "message": "@see meta.location"
        }
      }
    ],
    "failed": [
      {
        "reason": "Error: Invalid image format, allowed format are JPEG, PNG and GIF.",
        "payload": {
          "send_at": "2021-10-17T06:50:05+07:00",
          "is_group_message": true,
          "caption": "@see meta.location",
          "phone_number": "6281234567890-1628639662",
          "message_type": "image",
          "message": "@see meta.location"
        }
      }
    ]
  }
}

Endpoint ini digunakan untuk melihat pesan batch berdasarkan BATCH_ID. Informasi detil dari tiap-tiap pesan dapat dilihat berdasarkan message id menggunakan endpoint GET /messages/ID.

Penjelasan respon dari endpoint ini adalah sebagai berikut.

Atribut Keterangan
id ID dari batch message.
device_id Device ID yang digunakan untuk mengirim.
created_at Waktu batch message mulai diproses.
number_of_messages Jumlah pesan yang dikirimkan pada batch message.
messages Array of pesan yang dikirimkan.
messages.processed Jumlah pesan yang sudah diproses, statusnya dapat success atau fail. Lihat pada API GET /messages/ID.
messages.failed Jumlah pesan yang gagal atau ditolak sebelum sempat diproses.

Webhooks

Webhooks digunakan agar aplikasi anda dapat memperoleh informasi status dari API KirimWA.id. Saat ini API KirimWA.id akan mengirimkan webhook pada kondisi berikut:

Anda hanya perlu menyediakan satu Webhook URL. API KirimWA.id membedakan setiap aksi pada webhook dengan argumen tertentu yang dibahas pada bagian berikutnya.

Webhook Message Response

Webhook ini akan dipanggil ketika sebuah pesan selesai diproses baik itu success atau fail. Ketika endpoint POST /messages dipanggil maka webhook ini akan dijalankan oleh API KirimWA.id setelah proses selesai. Atribut yang mengindikasikan tipe webhook ini adalah atribut webhook_type dengan nilai send_message_response.

API KirimWA.id akan melakukan POST request ke URL webhook yang telah didaftarkan. Data yang dikirimkan oleh API KirimWA.id ketika memanggil webhook URL ini adalah sebagai berikut.

{ 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' }

Penjelasan dari atribut Webhook Message Response.

Atribut Deskripsi
id ID dari message yang dihasilkan dari POST /messages
webhook_type Tipe dari webhook yaitu send_message_response.
status Status dari pemrosesan pesan. Antara success atau fail.
message Pesan dari pemrosesan.
payload Adalah payload data yang dikirimkan ketika memanggil endpoint POST /messages.
created_at Tanggal pemrosesan pesan.
server_time Tanggal dari server ketika webhook dikirimkan.

Webhook Incoming Message

Webhook ini akan dipanggil ketika sebuah pesan baru masuk ke WhatsApp. Saat ini webhook pesan masuk hanya mendukung pesan berbentuk teks. Atribut yang mengindikasikan tipe webhook ini adalah atribut webhook_type dengan nilai incoming_message.

API KirimWA.id akan melakukan POST request ke URL webhook yang telah didaftarkan. Data yang dikirimkan oleh API KirimWA.id berupa JSON String. Ini adalah struktur JSON yang dikirimkan pada webhook pesan masuk.

{ "id": "kwid-2605630cf636463da5ce2f4110a", "webhook_type": "incoming_message", "payload": { "id": "kwid-2605630cf636463da5ce2f4110a", "device_id": "iphone-x-pro", "sender": "6281234567890", "from_me": false, "message_type": "text", "text": "Halo ini adalah pesan dari api.kirimwa.id", "caption": null, "is_group_message": false, "group_id": null, "timestamp": 1631306956, "contact": { "name": null, "vcard": null }, "location": { "latitude": 0, "longitude": 0, "name": null, "address": null }, "meta": { "file_name": null, "seconds": 0, "size": 41, "mime_type": "plain/text", "dimension": { "height": 0, "width": 0 } } }, "created_at": "2021-09-10T20:49:16.000Z", "server_time": "2021-09-10T20:49:17.462Z" }

Penjelasan dari atribut Webhook Pesan Masuk.

Atribut Deskripsi
id ID dari message yang diterima.
webhook_type Tipe dari webhook yaitu incoming_message.
payload Adalah payload data dari pesan masuk yang diterima oleh API KirimWA.id.
payload.id ID dari pesan yang diterima.
payload.sender Nomor WhatsApp pengirim.
payload.message_type Tipe dari pesan. Contoh: text, image, document, video, contact, location.
payload.from_me Apakah pesan dari nomor itu sendiri, biasanya digunakan untuk pesan pada grup. Nilainya true atau false.
payload.text Isi dari pesan yang bertipe text.
payload.caption Deskripsi dari pesan bertipe image atau video.
payload.is_group_message Apakah pesan dari group, nilainya true atau false.
payload.group_id ID dari group jika ini merupakan pesan dari grup.
payload.timestamp Unix timestamp waktu pesan dikirim.
payload.contact Pesan yang berisi data contact.
payload.location Pesan yang berisi koordinat lokasi.
payload.meta Informasi tambahan pada pesan yang masuk.
created_at Tanggal pesan diterima.
server_time Tanggal dari server ketika webhook dikirimkan.

Incoming Message Rules

Allowed Senders

Dalam satu kasus anda mungkin tidak ingin menerima webhook dari setiap nomor. Anda dapat membatasi pengiriman webhook untuk nomor atau group tertentu saja. Misal anda hanya ingin menerima webhook jika ada pesan baru dari pengirim 621234567890 atau Group ID tertentu. Gunakan atribut allowed_senders pada saat memasukkan URL webhook melalui POST /webhooks.

Process Message with Media

Selain allowed_senders anda juga dapat memberitahu API KirimWA.id untuk memproses pesan media yang masuk. Saat membuat webhook gunakan atribut process_message_with_media dengan nilai true untuk mengaktifkannya.

Ketika ada pesan media dengan tipe image, document, audio dan video masuk maka API KirimWA.id akan memberikan URL dari media tersebut dalam metadata incoming webhook sehingga dapat anda proses lebih lanjut. URL dari media ada pada metadata payload.metadata.media_url seperti dicontohkan di bawah.

{ "id": "kwid-2605630cf636463da5ce2f4110b", "webhook_type": "incoming_message", "payload": { "id": "kwid-2605630cf636463da5ce2f4110b", "device_id": "iphone-x-pro", "sender": "6281234567890", "from_me": false, "message_type": "media", "text": null, "caption": null, "is_group_message": false, "group_id": null, "timestamp": 1631306956, "contact": { "name": null, "vcard": null }, "location": { "latitude": 0, "longitude": 0, "name": null, "address": null }, "meta": { "file_name": null, "seconds": 0, "size": 41, "mime_type": "plain/text", "media_url": "https://api-kirimwa-media.s3.ap-southeast-1.amazonaws.com/6281234567890%40s.whatsapp.net/6281234567890-1628639662%40g.us/2022/04/02/0C6BEB7964564FB300062E631FA6E538.jpeg", "dimension": { "height": 0, "width": 0 } } }, "created_at": "2021-09-10T20:49:16.000Z", "server_time": "2021-09-10T20:49:17.462Z" }

Webhook Device Status

Webhook ini akan dipanggil ketika status dari perangkat berubah misal dari connected ke disconnected atau sebaliknya. Atribut yang mengindikasikan tipe webhook ini adalah atribut webhook_type dengan nilai device_status_changed.

API KirimWA.id akan melakukan POST request ke URL webhook yang telah didaftarkan. Data yang dikirimkan oleh API KirimWA.id berupa JSON String. Ini adalah struktur JSON yang dikirimkan pada webhook perubahan status perangkat.

{ "webhook_type": "device_status_changed", "device_id": "iphone-x-pro", "status": "disconnected", "changed_at": "2021-10-16T18:50:21.353Z", "server_time": "2021-10-16T18:50:21.388Z" }

Penjelasan dari atribut webhook perubahan status perangkat.

Atribut Deskripsi
webhook_type Tipe dari webhook yaitu device_status_changed.
device_id ID dari device yang statusnya berubah.
status Status dari device tersebut, antara connected atau disconnected.
changed_at Waktu status berubah.
server_time Waktu dari server ketika pengiriman dilakukan.

POST /webhooks

curl -X POST 'https://api.kirimwa.id/v1/webhooks' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "webhook_url": "https://YOUR_DOMAIN/my/webhook"
}'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/webhooks');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify({
      webhook_url: 'https://YOUR_DOMAIN/my/webhook'
    })
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/webhooks',
    'method' => 'POST',
    'payload' => json_encode([
      'webhook_url' => 'https://YOUR_DOMAIN/my/webhook'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "[email protected]",
  "status": "active",
  "data": "https://YOUR_DOMAIN/my/webhook",
  "incoming_message_rules": {
    "allowed_senders": [
      "*"
    ],
    "process_message_with_media": false
  },
  "created_at": "2021-06-20T17:17:06.333Z",
  "meta": {
    "location": "https://api.kirimwa.id/v1/webhooks"
  }
}

Perintah berikut akan menambahkan webhook dan API KirimWA.id hanya akan mengirimkan pesan webhook ketika pengirim dari invdividu dengan nomor 621234567890 dan dari Group ID 621234567890-1628639662.

curl -X POST 'https://api.kirimwa.id/v1/webhooks' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '
{
  "webhook_url": "https://YOUR_DOMAIN/my/webhook",
  "allowed_senders": "621234567890,621234567890-1628639662"
}'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/webhooks');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify({
      webhook_url: 'https://YOUR_DOMAIN/my/webhook',
      allowed_senders: '621234567890,621234567890-1628639662'
    })
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/webhooks',
    'method' => 'POST',
    'payload' => json_encode([
      'webhook_url' => 'https://YOUR_DOMAIN/my/webhook',
      'allowed_senders' => '621234567890,621234567890-1628639662'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengambalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "[email protected]",
  "status": "active",
  "data": "https://YOUR_DOMAIN/my/webhook",
  "incoming_message_rules": {
    "allowed_senders": [
      "621234567890",
      "621234567890-1628639662"
    ],
    "process_message_with_media": false
  },
  "created_at": "2021-06-20T17:17:06.333Z",
  "meta": {
    "location": "https://api.kirimwa.id/v1/webhooks"
  }
}

Endpoint ini digunakan untuk menambahkan webhook yang akan dipanggil oleh API KirimWA.id. Salah satu contohnya adalah Webhook Message Response diatas, API KirimWA.id akan memanggil URL yang dimasukkan pada endpoint ini.

Untuk melakukan update webhook URL maka anda dapat memanggil endpoint ini dengan parameter yang sama. Setiap pemanggilan akan menimpa nilai yang lama.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token
Content-Type: application/json Wajib Tipe dari request harus application/json

Body

Body dalam bentuk JSON.

Parameter Wajib Keterangan
webhook_url Wajib Alamat webhook URL yang akan dipanggil untuk menerima even dari API KirimWA.id
process_message_with_media Opsional Apakah pesan berbentuk media (image, document, audio, video) akan dikirim ke webhook. Nilai true untuk diproses dan false jika tidak ingin diproses. Default adalah false.
allowed_senders Opsional Daftar nomor pengirim yang pesannya akan dikirimkan ke webhook. Dapat berupa nomor invididu seperti 62123457890 atau Group ID. Gunakan koma untuk lebih dari satu nomor contoh 621234567890,62987654321. Default * yang berarti webhook akan dikirim ketika ada pesan masuk dari siapa saja (individu atau group).

GET /webhooks

curl 'https://api.kirimwa.id/v1/webhooks' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/webhooks');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/webhooks'
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": [
    {
      "id": "[email protected]_ADDR",
      "data": "https://YOUR_DOMAIN/my/webhook",
      "status": "active",
      "created_at": "2021-07-20T17:17:06.333Z"
    }
  ]
}

Endpoint ini digunakan untuk mendapatkan data webhook URL yang telah ditambahkan. Saat ini API KirimWA.id hanya mendukung penggunaan satu webhook URL.

DELETE /webhooks/WEBHOOK_ID

curl -X DELETE 'https://api.kirimwa.id/v1/webhooks/[email protected]_ADDR' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const webhookId = process.env.WEBHOOK_ID;
  const url = new URL('https://api.kirimwa.id/v1/webhooks/' + webhookId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'DELETE'
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/webhooks/%s', urlencode(getenv('WEBHOOK_ID'))),
    'method' => 'DELETE'
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 204 No Concent

Ednpoint ini digunakan untuk menghapus webhook yang telah didaftarkan. Setelah dihapus maka API KirimWA.id tidak akan mengirimkan notifikasi status pengeriman pesan ketika tidak ada webhook yang terdaftar.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

GET /webhook-responses

curl 'https://api.kirimwa.id/v1/webhook-responses' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/webhook-responses');
  // Do some filter
  // --------------
  url.searchParams.set('webhook_type', 'send_message_response');
  // url.searchParams.set('start_key', 'some_value');
  // url.searchParams.set('status', 'fail'); // value: success | fail
  // url.searchParams.set('device_id', 'DEVICE_ID');
  // url.searchParams.set('message_id', 'MESSAGE_ID');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query([
    'status' => 'success',
    'webhook_type' => 'send_message_response',
    'start_key' => '',
    'device_id' => '',
    'message_id' => ''
  ]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/webhook-responses?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": [
    {
      "id": "aca382a6-b636-481a-ad91-6e560e8dde53",
      "webhook_type": "send_message_response",
      "status": "success",
      "created_at": "2021-07-20T16:33:40.387Z",
      "url": "https://YOUR_DOMAIN/my/webhook",
      "http_response": "201 Created",
      "request_headers": {
        "host": "YOUR_DOMAIN",
        "content-length": 387,
        "content-type": "application/json",
        "user-agent": "API KirimWA/1.0"
      },
      "request_payload": {
        "id": "kwid-426564a5db7940288dc9fddb812",
        "server_time": "2021-07-19T13:35:00.078Z",
        "webhook_type": "send_message_response",
        "status": "success",
        "created_at": "2021-07-20T16:33:35.373Z",
        "message": "Message has been sent.",
        "payload": {
          "phone_number": "6281234567890",
          "message_type": "text",
          "message": "Halo ini adalah pesan dari api.kirimwa.id",
          "device_id": "asus-zenfone-1"
        },
      }
    },
    {
      "id": "fe9833c3-0ee0-4fad-bc93-7ea954d0ee64",
      "webhook_type": "send_message_response",
      "status": "success",
      "created_at": "2021-07-19T22:22:27.525Z",
      "url": "https://YOUR_DOMAIN/my/webhook",
      "http_response": "201 Created",
      "request_headers": {
        "host": "YOUR_DOMAIN",
        "content-length": 356,
        "content-type": "application/json",
        "user-agent": "API KirimWA/1.0"
      },
      "request_payload": {
        "id": "kwid-426564a5db7940288dc9fddb845",
        "server_time": "2021-07-19T22:22:23.221Z",
        "webhook_type": "send_message_response",
        "status": "success",
        "message": "Message has been sent.",
        "created_at": "2021-07-10T00:18:30.614Z",
        "payload": {
          "message": "Halo ini adalah pesan dari api.kirimwa.id",
          "phone_number": "6281234567890",
          "device_id": "iphone-x-pro",
          "message_type": "text"
        }
      }
    }
  ],
  "meta": {
    "last_key": null
  }
}

Untuk melihat response yang dikirimkan pada webhook URL pesan masuk gunakan perintah parameter webhook_type dengan nilai incoming_message.

curl 'https://api.kirimwa.id/v1/webhook-responses?webhook_type=incoming_message' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/webhook-responses');
  // Do some filter
  // --------------
  url.searchParams.set('webhook_type', 'incoming_message');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $query = http_build_query([
    'status' => 'success',
    'webhook_type' => 'incoming_message',
    'start_key' => '',
    'device_id' => '',
    'message_id' => ''
  ]);
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/webhook-responses?%s', $query)
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

{
  "data": [
    {
      "id": "537e8c78-3365-4562-b823-ae8c83785467",
      "webhook_type": "incoming_message",
      "status": "success",
      "created_at": "2021-09-11T01:43:54.449Z",
      "url": "https://YOUR_DOMAIN/my/webhook",
      "http_response": "200 OK",
      "request_headers": {
        "host": "YOUR_DOMAIN",
        "content-length": 605,
        "content-type": "application/json",
        "user-agent": "API KirimWA/1.0-RC5"
      },
      "request_payload": {
        "id": "kwid-398861d75c3e4641b2f0a0e5efa",
        "webhook_type": "incoming_message",
        "created_at": "2021-09-11T01:43:49.000Z",
        "server_time": "2021-09-11T01:43:53.371Z",
        "payload": {
          "id": "kwid-398861d75c3e4641b2f0a0e5efa",
          "sender": "6281234567890",
          "text": "Halo ini adalah pesan dari api.kirimwa.id",
          "type": "text",
          "from_me": false,
          "caption": null,
          "is_group_message": false,
          "group_id": null,
          "meta": {
            "seconds": 0,
            "size": 41,
            "mime_type": "plain/text",
            "dimension": {
              "width": 0,
              "height": 0
            },
            "file_name": null
          },
          "contact": {
            "name": null,
            "vcard": null
          },
          "location": {
            "name": null,
            "address": null,
            "latitude": 0,
            "longitude": 0
          },
          "timestamp": 1631324629
        }
      }
    }
  ],
  "meta": {
    "last_key": null
  }
}

Endpoint ini digunakan untuk mendapatkan respon yang diterima oleh API KirimWA.id ketika memanggil Webhook URL. Ini adalah respon yang dikembalikan oleh server anda ketika sebuah webhook dipanggil. Attribut yang dapat menjadi perhatian adalah status dan http_response. Jika nilai dari status adalah success berarti Webhook berhasil dipanggil dan server anda mengembalikan http_response 2XX. Jika pemanggilan gagal maka status bernilai fail dan http_response selain HTTP code 2XX.

Query String Parameter

Parameter Wajib Keterangan
start_key Opsional Nilai dari last_key yang digunakan untuk merequest halaman berikutnya.
webhook_type Opsional Tipe dari webhook response. Default adalah send_message_response.
status Opsional Status pemanggilan webhook yaitusuccess atau fail. Default adalah success.
device_id Opsional ID dari device yang digunakan. Wajib diisi ketika parameter message_id digunakan.
message_id Opsional ID pesan yang didapat ketika memanggil endpoint POST /messages.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

GET /webhook-response/WEBHOOK_RESPONSE_ID

curl 'https://api.kirimwa.id/v1/webhook-responses/fe9833c3-0ee0-4fad-bc93-7ea954d0ee64' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const responseId = 'fe9833c3-0ee0-4fad-bc93-7ea954d0ee64';
  const url = new URL('https://api.kirimwa.id/v1/webhook-responses/' + responseId);

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => sprintf('https://api.kirimwa.id/v1/webhook-responses/%s', getenv('WEBHOOK_RESPONSE_ID'))
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "id": "fe9833c3-0ee0-4fad-bc93-7ea954d0ee64",
  "webhook_type": "send_message_response",
  "status": "success",
  "created_at": "2021-07-19T22:22:27.525Z",
  "url": "https://YOUR_DOMAIN/my/webhook",
  "http_response": "201 Created",
  "request_headers": {
    "host": "YOUR_DOMAIN",
    "content-length": 356,
    "content-type": "application/json",
    "user-agent": "API KirimWA/1.0"
  },
  "request_payload": {
    "id": "kwid-426564a5db7940288dc9fddb845",
    "server_time": "2021-07-19T22:22:23.221Z",
    "webhook_type": "send_message_response",
    "status": "success",
    "message": "Message has been sent.",
    "created_at": "2021-07-10T00:18:30.614Z",
    "payload": {
      "message": "Halo ini adalah pesan dari api.kirimwa.id",
      "phone_number": "6281234567890",
      "device_id": "iphone-x-pro",
      "message_type": "text"
    }
  }
}

Endpoint ini digunakan untuk mendapatkan sebuah respon webhook yang dikirimkan API KirimWA.id ke server anda.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

Quotas

Saat ini setiap akun memiliki quota seperti berikut.

Quota pesan pengiriman akan direset setiap hari pada jam 00:00:00 waktu UTC atau jam 07:00:00 WIB.

Jika anda ingin quota tersebut ditambah silahkan kontak kami di TURN ON YOUR JAVASCRIPT.

GET /quotas

curl 'https://api.kirimwa.id/v1/quotas' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/quotas');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/quotas'
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "quota": {
    "message_per_day": 100,
    "incoming_message_per_day": -1,
    "incoming_media_bytes_per_month": 100000000,
    "batch_message_per_request": 50,
    "today_usage": 12,
    "today_incoming_usage": 55,
    "current_month_incoming_media_bytes": 10473969,
    "current_date": "2022-04-03T04:19:29.056Z",
    "next_reset": "2022-04-04T00:00:00.000Z",
    "daily_next_reset": "2022-04-04T00:00:00.000Z",
    "countdown_reset": 70831,
    "daily_next_countdown_reset": 70831
  }
}

Properti countdown_reset dan next_reset sekarang deprecated dan kemungkinan akan dihapus pada rilis mendatang. Silahkan gunakan properti daily_next_countdown_reset dan daily_next_reset sebagai pengganti.

Endpoint ini digunakan untuk mengetahui jumlah quota pengiriman untuk akun anda dan penggunaannya pada hari tersebut. Nilai -1 mengindikasikan tidak ada batas maksimal.

Header Parameter

Header Wajib Keterangan
Authorization: Bearer API_TOKEN Wajib API Token

Reconnect

Terkadang koneksi perangkat terputus sehingga pengiriman atau proses penerimaan pesan masuk di API KirimWA.id terganggu. Proses reconnect dapat membantu memulihkan koneksi tanpa harus melakukan scan ulang QR.

POST /reconnect

curl 'https://api.kirimwa.id/v1/reconnect' \
  -H 'Authorization: Bearer API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "iphone-x-pro" }'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1/reconnect');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url,
    method: 'POST',
    payload: JSON.stringify({
      device_id: 'iphone-x-pro'
    })
  };

  try {
    const { body, response } = await apiKirimWaRequest(reqParams);
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();

// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1/reconnect',
    'method' => 'POST',
    'payload' => json_encode([
      'device_id' => 'iphone-x-pro'
    ])
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "message": "Reconnecting device, please check device status using URL at meta.location.",
  "meta": {
    "location": "https://api.kirimwa.id/v1/devices/iphone-x-pro"
  }
}

Endpoint ini digunakan untuk melakukan reconnect tanpa perlu scan ulang QR Code. Proses reconnect berjalan asynchronus. Status dari koneksi perangkat dapat dilihat pada endpoint GET /v1/devices/DEVICE_ID.

Version

Versi dari API KirimWA.id akan diupdate dari waktu ke waktu. Namun update yang dilakukan akan tetap memprioritaskan kompatibilitas dengan versi sebelumnya. Sehingga aplikasi yang dibuat oleh developer tetap dapat berjalan dengan lancar.

GET /

Endpoint ini digunakan untuk mengetahui versi dari API KirimWA.id yang sedang digunakan.

curl 'https://api.kirimwa.id/v1' \
  -H 'Authorization: Bearer API_TOKEN'
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
(async function() {
  const url = new URL('https://api.kirimwa.id/v1');

  const reqParams = {
    token: process.env.API_TOKEN,
    url: url
  };

  try {
    const { body, response } = await apiKirimWaRequest({});
    console.log(body);
  } catch (error) {
    console.error('Something went wrong', {
      body: error.body,
      statusCode: error.response.statusCode
    });
  }
})();
// Lihat apiKirimWaRequest() pada Contoh Integrasi diatas
try {
  $reqParams = [
    'token' => getenv('API_TOKEN'),
    'url' => 'https://api.kirimwa.id/v1'
  ];

  $response = apiKirimWaRequest($reqParams);
  echo $response['body'];
} catch (Exception $e) {
  print_r($e);
}

Perintah diatas akan mengembalikan respon berikut.

HTTP/1.1 200 OK
Content-Type: application/json
{
  "message": "API KirimWA.id - Unofficial WhatsApp API Gateway",
  "version": "1.0-RC2",
  "stability": "Developer-Preview"
}

Error

Pada API KirimWA.id setiap request yang berhasil akan mengembalikan response HTTP code 2XX. Sedangkan jika terjadi error maka HTTP code yang dikembalikan adalah 4XX atau 5XX.

Error Code Keterangan
400 Bad Request -- Request yang dilakukan tidak sesuai.
401 Unauthorized -- API Token salah.
403 Forbidden -- Tidak ada akses untuk URL yang diminta.
404 Not Found -- Tidak ada halaman yang dimaksud.
429 Too Many Requests -- Jumlah request yang dilakukan melebihi batas yang ditentukan.
500 Internal Server Error -- Terjadi kesalahan pada server API KirimWA.id.