Base URLhttp://localhost:8080

Konekwa API Documentation

Konekwa adalah platform WhatsApp Gateway multi-tenant. Gunakan API ini untuk mengirim pesan, mengelola sesi WhatsApp, template, dan webhook.

WhatsApp Messaging

Kirim text, image, video, audio, document, location, dan contact melalui API.

Secure Sessions

Kelola multiple WhatsApp session dengan QR code scanning dan auto-reconnect.

Webhook Events

Terima notifikasi real-time untuk pesan masuk dan event WhatsApp lainnya.

Authentication

Semua API endpoint yang memerlukan autentikasi menggunakan API Key yang dikirim melalui header X-API-Key.

Dapatkan API Token

Buat dan kelola API token Anda di Konekwa Dashboard → Token

Header Authentication

X-API-Key: your_api_token_here

cURL Example

curl -X GET http://localhost:8080/v1/sessions \
  -H "X-API-Key: your_api_token_here" \
  -H "Content-Type: application/json"

Base URL

Semua request API dikirim ke API Gateway:

Base URL

http://localhost:8080

API Versioning

API menggunakan versioning via URL path. Semua endpoint authenticated berada di bawah prefix /v1.

Prefix	Auth	Keterangan
`/v1/*`	API Key	Authenticated endpoints
`/api/v1/*`	None	Public endpoints (QR, status)
`/health`	None	Health check

Error Handling

API menggunakan HTTP status code standar dan mengembalikan error dalam format JSON.

Error Response Format

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is missing required fields",
    "details": "Field 'recipient' is required"
  }
}

Status Code	Keterangan
`200`	Success
`201`	Created
`202`	Accepted (message queued)
`400`	Bad Request - Parameter tidak valid
`401`	Unauthorized - API key tidak valid
`403`	Forbidden - Tidak memiliki akses
`404`	Not Found - Resource tidak ditemukan
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

POST/v1/messages

Kirim pesan WhatsApp ke nomor tujuan. Mendukung text, image, video, audio, document, location, dan contact.

Asynchronous

Endpoint ini mengembalikan 202 Accepted. Pesan akan diproses secara async melalui message queue.

Request Headers

Field	Type	Required	Description
`X-API-Key`	string	Required	API authentication token
`Content-Type`	string	Required	application/json

Request Body

Field	Type	Required	Description
`session_id`	string	Required	ID sesi WhatsApp yang digunakan untuk mengirim
`recipient`	string	Required	Nomor WhatsApp tujuan (format: 628xxx) atau Group JID
`message_type`	string	Required	Tipe pesan: text, image, video, audio, document, location, contact
`content`	string	Optional	Isi pesan text. Required jika message_type = text
`media_url`	string	Optional	URL media. Required untuk image, video, audio, document
`caption`	string	Optional	Caption untuk media (image, video, document)
`filename`	string	Optional	Nama file untuk document
`latitude`	float	Optional	Latitude. Required jika message_type = location
`longitude`	float	Optional	Longitude. Required jika message_type = location
`vcard_data`	string	Optional	vCard data. Required jika message_type = contact
`template_id`	string	Optional	ID template pesan
`placeholder_values`	map	Optional	Key-value placeholder untuk template

Text

curl -X POST http://localhost:8080/v1/messages \
  -H "X-API-Key: your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-001",
    "recipient": "6281234567890",
    "message_type": "text",
    "content": "Hello from Konekwa!"
  }'

Response 202 Accepted

Response Body

{
  "message_id": "msg_abc123def456",
  "status": "QUEUED",
  "queued_at": "2026-03-10T10:30:00Z"
}

GET/v1/messages/:id

Ambil detail pesan berdasarkan ID.

Path Parameters

Field	Type	Description
`id`	string	Message ID

cURL

curl -X GET http://localhost:8080/v1/messages/msg_abc123def456 \
  -H "X-API-Key: your_api_token"

Response 200 OK

Response Body

{
  "id": "msg_abc123def456",
  "session_id": "session-001",
  "recipient": "6281234567890",
  "message_type": "text",
  "content": "Hello from Konekwa!",
  "status": "SENT",
  "direction": "OUTBOUND",
  "created_at": "2026-03-10T10:30:00Z",
  "sent_at": "2026-03-10T10:30:02Z"
}

GET/v1/messages

Ambil daftar pesan dengan filter.

Query Parameters

Parameter	Type	Required	Description
`session_id`	string	Optional	Filter berdasarkan session
`direction`	string	Optional	sent atau received
`type`	string	Optional	Filter berdasarkan message type
`start_date`	string	Optional	Tanggal mulai (ISO 8601)
`end_date`	string	Optional	Tanggal akhir (ISO 8601)
`page_size`	integer	Optional	Jumlah item per halaman (default: 20)
`page_token`	string	Optional	Token untuk pagination

cURL

curl -X GET "http://localhost:8080/v1/messages?session_id=session-001&direction=sent&page_size=10" \
  -H "X-API-Key: your_api_token"

Response 200 OK

Response Body

{
  "messages": [
    {
      "id": "msg_abc123",
      "session_id": "session-001",
      "recipient": "6281234567890",
      "message_type": "text",
      "content": "Hello!",
      "status": "SENT",
      "direction": "OUTBOUND",
      "created_at": "2026-03-10T10:30:00Z"
    }
  ],
  "next_page_token": "eyJwYWdlIjoy",
  "total_count": 150
}

POST/v1/sessions

Buat sesi WhatsApp baru. Setelah sesi dibuat, scan QR code untuk menghubungkan perangkat.

Request Body

Field	Type	Required	Description
`name`	string	Required	Nama sesi (untuk identifikasi)
`webhooks`	object	Optional	Konfigurasi webhook URL
`webhooks.message`	string	Optional	URL webhook untuk event pesan
`webhooks.status`	string	Optional	URL webhook untuk event status
`proxy_url`	string	Optional	Proxy URL untuk koneksi WhatsApp

cURL

curl -X POST http://localhost:8080/v1/sessions \
  -H "X-API-Key: your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CS WhatsApp",
    "webhooks": {
      "message": "https://yourapp.com/webhook/message",
      "status": "https://yourapp.com/webhook/status"
    }
  }'

Response 201 Created

Response Body

{
  "id": "ses_xyz789",
  "name": "CS WhatsApp",
  "status": "CREATED",
  "qr_url": "/api/v1/qr/ses_xyz789/image",
  "created_at": "2026-03-10T10:00:00Z"
}

GET/v1/sessions

Ambil daftar semua sesi WhatsApp.

cURL

curl -X GET http://localhost:8080/v1/sessions \
  -H "X-API-Key: your_api_token"

Response 200 OK

Response Body

{
  "sessions": [
    {
      "id": "ses_xyz789",
      "name": "CS WhatsApp",
      "status": "CONNECTED",
      "phone_number": "6281234567890",
      "created_at": "2026-03-10T10:00:00Z",
      "connected_at": "2026-03-10T10:01:30Z"
    }
  ]
}

GET/v1/sessions/:id

Ambil detail sesi berdasarkan ID.

Path Parameters

Field	Type	Description
`id`	string	Session ID

cURL

curl -X GET http://localhost:8080/v1/sessions/ses_xyz789 \
  -H "X-API-Key: your_api_token"

Response 200 OK

PATCH/v1/sessions/:id

Update informasi sesi WhatsApp.

Path Parameters

Field	Type	Description
`id`	string	Session ID

Request Body

Field	Type	Required	Description
`name`	string	Optional	Nama sesi baru

cURL

curl -X PATCH http://localhost:8080/v1/sessions/ses_xyz789 \
  -H "X-API-Key: your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales WhatsApp"}'

Response 200 OK

DELETE/v1/sessions/:id

Hapus sesi WhatsApp berdasarkan ID. Sesi akan di-disconnect dan dihapus permanen.

Path Parameters

Field	Type	Description
`id`	string	Session ID

cURL

curl -X DELETE http://localhost:8080/v1/sessions/ses_xyz789 \
  -H "X-API-Key: your_api_token"

Response 200 OK

Response Body

{
  "message": "Session deleted successfully"
}

DELETE/v1/sessions

Hapus semua sesi WhatsApp (bulk delete).

Destructive Action

Operasi ini tidak dapat di-undo. Semua sesi dan data terkait akan dihapus permanen.

cURL

curl -X DELETE http://localhost:8080/v1/sessions \
  -H "X-API-Key: your_api_token"

Response 200 OK

POST/v1/sessions/:id/disconnect

Disconnect sesi WhatsApp tanpa menghapus. Sesi bisa di-reconnect nanti.

Path Parameters

Field	Type	Description
`id`	string	Session ID

cURL

curl -X POST http://localhost:8080/v1/sessions/ses_xyz789/disconnect \
  -H "X-API-Key: your_api_token"

Response 200 OK

POST/v1/sessions/:id/restart-qr

Restart QR code listener untuk sesi. Gunakan jika QR code expired atau perlu di-refresh.

Path Parameters

Field	Type	Description
`id`	string	Session ID

cURL

curl -X POST http://localhost:8080/v1/sessions/ses_xyz789/restart-qr \
  -H "X-API-Key: your_api_token"

Response 200 OK

POST/v1/sessions/:id/reset

Reset sesi WhatsApp. Menghapus session data lokal dan memulai kembali dari QR scanning.

Path Parameters

Field	Type	Description
`id`	string	Session ID

cURL

curl -X POST http://localhost:8080/v1/sessions/ses_xyz789/reset \
  -H "X-API-Key: your_api_token"

Response 200 OK

PATCH/v1/sessions/:id/webhooks

Update konfigurasi webhook untuk sesi.

Path Parameters

Field	Type	Description
`id`	string	Session ID

Request Body

Field	Type	Required	Description
`message`	string	Optional	URL webhook untuk event pesan
`status`	string	Optional	URL webhook untuk event status

cURL

curl -X PATCH http://localhost:8080/v1/sessions/ses_xyz789/webhooks \
  -H "X-API-Key: your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "https://yourapp.com/webhook/message",
    "status": "https://yourapp.com/webhook/status"
  }'

Response 200 OK

PATCH/v1/sessions/:id/settings

Update pengaturan sesi WhatsApp.

Path Parameters

Field	Type	Description
`id`	string	Session ID

Request Body

Field	Type	Required	Description
`auto_read`	boolean	Optional	Auto read pesan masuk
`auto_typing`	boolean	Optional	Auto typing indicator sebelum kirim

cURL

curl -X PATCH http://localhost:8080/v1/sessions/ses_xyz789/settings \
  -H "X-API-Key: your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "auto_read": true,
    "auto_typing": true
  }'

Response 200 OK

POST/v1/templates

Buat template pesan baru. Template mendukung placeholder untuk personalisasi pesan.

Request Body

Field	Type	Required	Description
`name`	string	Required	Nama template
`content`	string	Required	Isi template. Gunakan {{placeholder}} untuk variabel
`message_type`	string	Optional	Tipe pesan (default: text)

cURL

curl -X POST http://localhost:8080/v1/templates \
  -H "X-API-Key: your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "content": "Halo {{name}}, selamat datang di {{company}}!"
  }'

Response 201 Created

Response Body

{
  "id": "tpl_abc123",
  "name": "welcome_message",
  "content": "Halo {{name}}, selamat datang di {{company}}!",
  "message_type": "text",
  "created_at": "2026-03-10T10:00:00Z"
}

GET/v1/templates

Ambil daftar semua template pesan.

cURL

curl -X GET http://localhost:8080/v1/templates \
  -H "X-API-Key: your_api_token"

Response 200 OK

GET/v1/templates/:id

Ambil detail template berdasarkan ID.

Path Parameters

Field	Type	Description
`id`	string	Template ID

cURL

curl -X GET http://localhost:8080/v1/templates/tpl_abc123 \
  -H "X-API-Key: your_api_token"

Response 200 OK

PUT/v1/templates/:id

Update template pesan.

Path Parameters

Field	Type	Description
`id`	string	Template ID

Request Body

Field	Type	Required	Description
`name`	string	Optional	Nama template baru
`content`	string	Optional	Isi template baru

cURL

curl -X PUT http://localhost:8080/v1/templates/tpl_abc123 \
  -H "X-API-Key: your_api_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message_v2",
    "content": "Hi {{name}}! Welcome to {{company}}. Ada yang bisa kami bantu?"
  }'

Response 200 OK

DELETE/v1/templates/:id

Hapus template pesan.

Path Parameters

Field	Type	Description
`id`	string	Template ID

cURL

curl -X DELETE http://localhost:8080/v1/templates/tpl_abc123 \
  -H "X-API-Key: your_api_token"

Response 200 OK

GET/v1/webhooks/failed

Ambil daftar webhook yang gagal terkirim. Berguna untuk monitoring dan retry.

cURL

curl -X GET http://localhost:8080/v1/webhooks/failed \
  -H "X-API-Key: your_api_token"

Response 200 OK

Response Body

{
  "webhooks": [
    {
      "id": "wh_fail_001",
      "session_id": "ses_xyz789",
      "url": "https://yourapp.com/webhook",
      "event_type": "message.received",
      "error": "Connection refused",
      "attempts": 3,
      "last_attempt_at": "2026-03-10T10:35:00Z",
      "created_at": "2026-03-10T10:30:00Z"
    }
  ]
}

POST/v1/webhooks/replay/:id

Retry pengiriman webhook yang gagal.

Path Parameters

Field	Type	Description
`id`	string	Failed webhook ID

cURL

curl -X POST http://localhost:8080/v1/webhooks/replay/wh_fail_001 \
  -H "X-API-Key: your_api_token"

Response 200 OK

Response Body

{
  "message": "Webhook replay queued successfully",
  "webhook_id": "wh_fail_001"
}