Volara Docs

Tema

SDK PHP ​

volara/sdk adalah SDK resmi PHP untuk Volara: messaging WhatsApp/omnichannel, conversations, CRM, broadcast, knowledge base, metrics, dan agency white-label.

Tanpa dependensi runtime — memakai ekstensi cURL bawaan PHP, jadi langsung jalan di plugin WordPress atau WooCommerce tanpa menarik Guzzle. Butuh PHP 8.0+ dengan ekstensi curl dan json (keduanya standar).

Kode sumber: github.com/volara-asia.

Install ​

bash
composer require volara/sdk

Autentikasi ​

Buat klien dengan API key Anda, atau set env VOLARA_API_KEY dan biarkan constructor membacanya. Ambil kunci dari dashboard Volara (Settings → API Keys).

php
use Volara\Client;

$client = new Client('sk_live_...');                          // kunci eksplisit
$client = new Client();                                        // membaca VOLARA_API_KEY
$client = new Client(['apiKey' => 'sk_...', 'baseUrl' => 'https://api.volara.chat']);

Opsi konfigurasi (bentuk array, atau new Client($apiKey, $opts)):

KeyDefaultCatatan
apiKeygetenv('VOLARA_API_KEY')API key rahasia Anda.
baseUrlhttps://api.volara.chatOverride untuk self-host atau region.
timeout30Timeout per-permintaan, dalam detik.
maxRetries2Retry pada 429 / 5xx / error jaringan.
defaultHeaders[]Header tambahan di setiap permintaan.

Jaga kerahasiaan API key

API key memberi akses penuh ke data tenant. Simpan server-side, jangan ekspos ke browser atau repo publik.

Quickstart — kirim pesan pertama ​

php
require 'vendor/autoload.php';
use Volara\Client;

$client = new Client(); // membaca VOLARA_API_KEY
$client->messages->send('conv_123', ['text' => 'Halo! 👋']);

Contoh resource ​

Body permintaan dikirim dalam camelCase, dan respons sukses kembali sebagai associative array dengan envelope { data } / { success, data } yang sudah dibuka.

php
// Conversations
$page = $client->conversations->list(['status' => 'open', 'perPage' => 25]);
foreach ($page['data'] as $conversation) {
    echo $conversation['id'] . "\n";
}
$conversation = $client->conversations->get('conv_123');

// Messages
$client->messages->send('conv_123', ['text' => 'Pesanan kamu sudah dikirim.']);
$client->messages->send('conv_123', [
    'type' => 'template',
    'content' => ['name' => 'order_shipped', 'language' => 'id'],
]);

// Contacts (CRM)
$contacts = $client->contacts->list(['q' => 'budi']);
$contact  = $client->contacts->get('cust_123');
$created  = $client->contacts->create([
    'name'        => 'Budi Santoso',
    'phoneNumber' => '+6281234567890', // E.164
    'email'       => '[email protected]',
]);

// Broadcasts
$client->broadcasts->create([
    'title'          => 'Promo Lebaran',
    'messageContent' => 'Diskon 20% minggu ini!',
    'targetAudience' => ['tag' => 'vip'],
]);

// Knowledge base & metrics
$hits = $client->knowledge->search('refund policy');         // scope: sources
$faqs = $client->knowledge->search('refund policy', 'faqs');
$dashboard = $client->metrics->dashboard();

Escape hatch ​

php
$tickets = $client->request('/tickets', ['query' => ['status' => 'open']]);

request() membuka envelope; raw() mengembalikan body apa adanya.

Verifikasi webhook ​

Verifikasi webhook terhadap signing secret Anda sebelum dipercaya. Selalu pakai body mentah — memverifikasi JSON yang di-serialize ulang akan gagal karena byte-nya berbeda. Hex polos atau awalan sha256= keduanya diterima, dan perbandingannya constant-time.

php
use Volara\Webhooks;

$raw    = file_get_contents('php://input');
$sig    = $_SERVER['HTTP_X_VOLARA_SIGNATURE'] ?? '';
$secret = getenv('VOLARA_WEBHOOK_SECRET');

if (!Webhooks::verify($raw, $sig, $secret)) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
// tangani $event['type'] ...

Error handling ​

Setiap respons non-2xx melempar Volara\VolaraError. Kegagalan jaringan melempar VolaraConnectionError dan timeout melempar VolaraTimeoutError — keduanya meng-extend VolaraError, jadi satu catch mencakup semuanya. Error membawa status HTTP, kode VLR-* yang machine-readable, dan request id server untuk support.

php
use Volara\VolaraError;

try {
    $client->conversations->get('does-not-exist');
} catch (VolaraError $err) {
    error_log($err->getStatus());     // mis. 404
    error_log($err->getErrorCode());  // mis. "VLR-NOT-FOUND"
    error_log($err->getRequestId());  // untuk support
    error_log((string) $err);         // pesan + detail
}

Idempotency ​

Setiap operasi tulis (POST / PUT / PATCH / DELETE) dikirim dengan header Idempotency-Key agar permintaan yang di-retry tidak menggandakan data. SDK membuatkan UUID v4 otomatis. Berikan milik Anda sendiri untuk membuat panggilan tertentu bisa diulang aman:

php
$client->messages->send('conv_123', [
    'text'           => 'Halo!',
    'idempotencyKey' => 'order-4587-confirmation',
]);

Langkah selanjutnya ​