# Volara Docs — Dokumentasi Lengkap

> Dokumentasi Volara — CRM omnichannel untuk WhatsApp, Instagram, dan TikTok dengan inbox terpadu, AI chatbot, broadcast, flows, dan REST API untuk developer. Situs ini ramah-AI: setiap halaman punya front-matter dan tersedia sebagai Markdown.

Sumber: https://docs.volara.chat

---

<!-- Source: https://docs.volara.chat/ -->

# Volara Docs — Satu API untuk semua chat pelanggan



---

<!-- Source: https://docs.volara.chat/agency -->

# Agency & White-label

Mode Agency menjadikan Volara produk white-label untuk Anda jual kembali. Sebuah
**organisasi agency** adalah organisasi induk yang menaungi banyak tenant klien
melalui tautan agency-klien yang eksplisit.

## Yang bisa Anda kustomisasi

- **Brand kit** — unggah logo dan favicon, atur warna agar sesuai merek Anda.
- **Custom domain** — sajikan app di domain Anda sendiri.
- **Kelola klien** — buat dan kelola tenant untuk tiap klien dari satu tempat.
- **Entitlements** — atur fitur dan batas yang tersedia per klien.
- **Billing** — kelola penagihan terpusat untuk portofolio klien Anda.

::: warning Isolasi data tetap dijaga
Custom domain dan branding **tidak pernah** memberi otorisasi atas data tenant klien
yang dilindungi. Konteks tenant selalu berasal dari sesi/API key terverifikasi —
bukan dari domain, header, atau hint publik.
:::

## Otomasi via API

Operasi agency berada di bawah prefix **`/agencies/current/...`** — konteks agency
diturunkan dari kunci/sesi terverifikasi, jadi `current` selalu mengacu ke agency
Anda sendiri. Contoh resource: profil agency, brand kit, domains, signup forms,
landing pages, dan form submissions.

```bash
# Ambil profil agency saat ini
curl https://api.volara.chat/api/v1/agencies/current \
  -H "Authorization: Bearer AGENCY_API_KEY"

# Daftar domain kustom
curl https://api.volara.chat/api/v1/agencies/current/domains \
  -H "Authorization: Bearer AGENCY_API_KEY"
```

Kunci agency hanya dapat bertindak atas tenant klien melalui **grant eksplisit** —
tidak pernah lintas-tenant tanpa izin. Daftar endpoint agency lengkap ada di
[Referensi API interaktif](/api-reference.html).

## Langkah selanjutnya

- Pelajari [BYOK](/byok) agar tiap klien bisa pakai AI provider sendiri.
- Lihat [API Reference](/api) untuk otomasi penyediaan klien.
- Pahami [Autentikasi](/api/authentication) dan grant lintas-tenant.

---

<!-- Source: https://docs.volara.chat/api -->

# API Reference

API Volara adalah REST API ber-otentikasi API key yang memungkinkan Anda mengirim
pesan, mengelola kontak dan percakapan, knowledge base, serta menerima event lewat
webhook. Seluruh API dideskripsikan oleh satu sumber mesin-terbaca: **OpenAPI 3.1**.

::: tip Referensi interaktif (Scalar)
Buka **[Referensi API interaktif →](/api-reference.html)** — daftar lengkap endpoint,
parameter, contoh request/response, panel **try-it**, dan pemilih bahasa kode
(cURL, TypeScript, Python). Dirender dengan [Scalar](https://scalar.com) dari
[`/openapi.json`](/openapi.json).
:::

## Konsep API

Baca halaman konsep ini sebelum integrasi serius:

- [Autentikasi](/api/authentication) — API key via `Authorization: Bearer`.
- [Errors](/api/errors) — amplop error + kode `VLR-*`.
- [Rate Limits](/api/rate-limits) — kuota per kunci + header `RateLimit-*`.
- [Pagination](/api/pagination) — kursor untuk endpoint daftar.
- [Webhooks](/api/webhooks) — event masuk + verifikasi HMAC-SHA256.

## Autentikasi

Semua permintaan memerlukan header:

```
Authorization: Bearer <API_KEY>
```

Buat API key di **Settings → API Keys**. Setiap kunci terikat pada satu tenant;
konteks tenant ditentukan dari kunci terverifikasi, bukan dari header publik. Detail
lengkap di [Autentikasi](/api/authentication).

## Konvensi

- **Base URL:** `https://api.volara.chat`
- **Versi:** `/api/v1/*` adalah mirror stabil dari `/api/*`. Untuk integrasi yang
  perlu kontrak stabil, pakai prefix `/api/v1`.
- **Format:** JSON request & response (`Content-Type: application/json`).
- **Pagination:** endpoint daftar memakai kursor — lihat [Pagination](/api/pagination).
- **Rate limit:** respons menyertakan header `RateLimit-*`; tangani `429` dengan
  backoff — lihat [Rate Limits](/api/rate-limits).
- **Errors:** amplop konsisten `{ "error": { "code", "message", "details" } }` —
  lihat [Errors](/api/errors).
- **Timestamps:** ISO 8601 (UTC).

## Kelompok endpoint

- **Messaging** — kirim pesan teks/template ke [WhatsApp](/guides/whatsapp),
  [Instagram](/guides/instagram), dan [TikTok](/guides/tiktok).
- **Contacts & CRM** — kelola kontak dan pipeline [CRM](/guides/crm).
- **Conversations & Inbox** — baca dan kelola percakapan [Inbox](/guides/inbox).
- **Knowledge** — cari sumber dan FAQ (`GET /knowledge/sources?q=` &
  `GET /knowledge/faqs?q=`) untuk [Knowledge / RAG](/guides/knowledge).
- **Broadcast & Flows** — kampanye dan automation.
- **Tickets** — tiket support.
- **Agency / White-label** — provisioning klien di bawah `/agencies/current/...`
  (lihat [Agency](/agency)).
- **Webhooks** — daftarkan endpoint untuk event masuk (verifikasi HMAC-SHA256,
  retry/backoff, idempotency) — lihat [Webhooks](/api/webhooks).

Daftar endpoint persisnya selalu dari **[Referensi API interaktif](/api-reference.html)**
(sumber kebenaran OpenAPI), bukan dari contoh di halaman panduan.

## Contoh: kirim pesan

```bash
curl -X POST https://api.volara.chat/api/v1/messages \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": "CHANNEL_ID", "to": "6281234567890", "type": "text", "text": "Halo!" }'
```

## Langkah selanjutnya

- Ikuti [Quickstart](/quickstart) untuk permintaan pertama Anda.
- Buka [Referensi API interaktif](/api-reference.html) untuk semua endpoint.
- Lihat [SDK & Integrasi](/sdk) untuk client library dan n8n.

---

<!-- Source: https://docs.volara.chat/api/authentication -->

# Autentikasi

API Volara memakai **API key** untuk autentikasi. Setiap kunci terikat pada satu
tenant (organisasi) dan menentukan konteks tenant dari kunci terverifikasi — bukan
dari header publik seperti `x-org-slug` atau `x-app-id`.

## Base URL & versi

- **Base URL:** `https://api.volara.chat`
- **Versi:** `/api/v1/*` adalah mirror stabil dari `/api/*`. Untuk integrasi
  jangka panjang, pakai prefix `/api/v1`.

```
https://api.volara.chat/api/v1/messages
```

## Membuat API key

1. Masuk ke [app.volara.chat](https://app.volara.chat).
2. Buka **Settings → API Keys**.
3. Buat kunci baru dan **salin saat itu juga** — kunci hanya ditampilkan sekali.

## Mengirim kredensial

Sertakan kunci di setiap permintaan. Dua bentuk header diterima:

::: code-group

```bash [Authorization: Bearer (disarankan)]
curl https://api.volara.chat/api/v1/conversations \
  -H "Authorization: Bearer API_KEY"
```

```bash [x-api-key]
curl https://api.volara.chat/api/v1/conversations \
  -H "x-api-key: API_KEY"
```

:::

```ts [TypeScript]
const res = await fetch('https://api.volara.chat/api/v1/conversations', {
  headers: { Authorization: `Bearer ${process.env.VOLARA_API_KEY}` },
})
```

## Isolasi tenant

Konteks tenant **selalu** berasal dari kunci terverifikasi. Header publik
(`x-org-slug`, `x-app-id`, `app_id`, dll.) tidak bisa memilih atau memverifikasi
tenant. Satu kunci tidak pernah bisa mengakses data tenant lain. Untuk agency,
akses ke tenant klien hanya melalui grant eksplisit — lihat [Agency](/agency).

::: warning Jaga kerahasiaan API key
API key memberi akses penuh ke data tenant Anda. Jangan menaruhnya di kode frontend,
repositori publik, atau bundel klien. Gunakan hanya dari server, dan putar (rotate)
kunci secara berkala.
:::

## Penanganan kesalahan autentikasi

- `401 Unauthorized` — kunci tidak ada, salah, atau dicabut. Periksa header dan
  buat ulang kunci bila perlu. Lihat [Errors](/api/errors).

## Langkah selanjutnya

- [Quickstart](/quickstart) — permintaan pertama Anda.
- [Errors](/api/errors) · [Rate Limits](/api/rate-limits) · [Pagination](/api/pagination).
- [Referensi API interaktif](/api-reference.html).

---

<!-- Source: https://docs.volara.chat/api/errors -->

# Errors

Semua kesalahan API Volara memakai **amplop error** JSON yang konsisten, sehingga
client bisa menanganinya secara seragam.

## Amplop error

```json
{
  "error": {
    "code": "validation_error",
    "message": "Field 'to' wajib diisi.",
    "details": [
      { "field": "to", "issue": "required" }
    ]
  }
}
```

- **`code`** — kode mesin yang stabil (snake_case) untuk percabangan logika.
- **`message`** — pesan yang dapat dibaca manusia (Bahasa Indonesia/Inggris).
- **`details`** — opsional; konteks tambahan (mis. error validasi per-field).

## Kode status HTTP

| Status | Arti | Tindakan |
| --- | --- | --- |
| `400` | Bad Request — payload/parameter tidak valid | Perbaiki request; baca `details`. |
| `401` | Unauthorized — API key salah/tidak ada/dicabut | Periksa [Autentikasi](/api/authentication). |
| `403` | Forbidden — kunci tidak punya scope/akses | Cek scope kunci atau grant agency. |
| `404` | Not Found — resource tidak ada di tenant ini | Verifikasi id milik tenant Anda. |
| `409` | Conflict — bentrok state/idempotency | Cek state resource atau ulangi dengan `idempotency-key` baru. |
| `422` | Unprocessable — validasi gagal | Baca `details`. |
| `429` | Too Many Requests — rate limit | Backoff; lihat [Rate Limits](/api/rate-limits). |
| `5xx` | Server error | Retry dengan backoff; jika berlanjut, hubungi dukungan. |

::: tip Pola penanganan
Percabangkan logika pada `error.code` (stabil), bukan pada `error.message`
(bisa berubah). Tampilkan `message` ke pengguna seperlunya.
:::

## Kode referensi klien `VLR-*`

Sebagian respons error menyertakan **kode referensi `VLR-*`** (mis. `VLR-7F3A2C`).
Kode ini ditampilkan ke pengguna akhir saat terjadi kegagalan dan dipakai sebagai
tautan ke detail kejadian di admin. Saat melapor ke dukungan, sertakan kode `VLR-*`
agar tim dapat melacak kejadian persisnya tanpa membuka data sensitif.

## Contoh penanganan

```ts
const res = await fetch('https://api.volara.chat/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOLARA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ channelId, to, type: 'text', text: 'Halo!' }),
})

if (!res.ok) {
  const { error } = await res.json()
  switch (error?.code) {
    case 'rate_limited':
      // tunggu lalu retry — lihat header RateLimit-Reset
      break
    case 'validation_error':
      console.error('Validasi:', error.details)
      break
    default:
      console.error(`[${res.status}] ${error?.message}`)
  }
}
```

## Langkah selanjutnya

- [Rate Limits](/api/rate-limits) untuk penanganan `429`.
- [Referensi API interaktif](/api-reference.html) untuk kode error per-endpoint.

---

<!-- Source: https://docs.volara.chat/api/pagination -->

# Pagination

Endpoint daftar (mis. kontak, percakapan, pesan) mengembalikan hasil per-halaman
menggunakan **pagination berbasis kursor**. Kursor lebih stabil daripada offset
saat data berubah selama Anda menelusuri.

## Parameter

| Parameter | Lokasi | Arti |
| --- | --- | --- |
| `limit` | query | Jumlah item per halaman (ada nilai default & maksimum per endpoint). |
| `cursor` | query | Penanda halaman berikutnya, dari respons sebelumnya. |

## Bentuk respons

Respans daftar membawa data dan kursor untuk halaman selanjutnya:

```json
{
  "data": [
    { "id": "c_01", "name": "Budi" },
    { "id": "c_02", "name": "Sari" }
  ],
  "pageInfo": {
    "hasNextPage": true,
    "nextCursor": "eyJpZCI6ImNfMDIifQ"
  }
}
```

::: tip Bentuk pasti dapat berbeda per-endpoint
Nama field (`pageInfo`/`nextCursor`/`meta`) dan amplop respons bisa bervariasi.
Selalu cek bentuk persisnya di [Referensi API interaktif](/api-reference.html).
:::

## Menelusuri semua halaman

Lanjutkan selama `hasNextPage` `true`, teruskan `nextCursor` ke permintaan berikutnya:

```ts
async function* listAll(path: string) {
  let cursor: string | undefined
  do {
    const url = new URL(`https://api.volara.chat/api/v1/${path}`)
    url.searchParams.set('limit', '100')
    if (cursor) url.searchParams.set('cursor', cursor)

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.VOLARA_API_KEY}` },
    })
    const body = await res.json()
    for (const item of body.data) yield item
    cursor = body.pageInfo?.hasNextPage ? body.pageInfo.nextCursor : undefined
  } while (cursor)
}

for await (const contact of listAll('contacts')) {
  console.log(contact.id)
}
```

## Praktik baik

- Pakai `limit` sebesar mungkin yang diizinkan untuk mengurangi jumlah permintaan,
  tetapi tetap hormati [Rate Limits](/api/rate-limits).
- Perlakukan `cursor` sebagai token buram (opaque) — jangan parse atau ubah.
- Untuk sinkronisasi real-time, gabungkan dengan [Webhooks](/api/webhooks)
  alih-alih polling berulang.

## Langkah selanjutnya

- [Rate Limits](/api/rate-limits) agar penelusuran besar tetap aman.
- [Errors](/api/errors) untuk menangani kegagalan di tengah halaman.

---

<!-- Source: https://docs.volara.chat/api/rate-limits -->

# Rate Limits

API Volara membatasi laju permintaan **per API key** untuk menjaga stabilitas dan
mencegah penyalahgunaan. Saat batas terlampaui, API mengembalikan status `429`.

## Header kuota

Setiap respons menyertakan header yang menggambarkan kuota saat ini:

| Header | Arti |
| --- | --- |
| `RateLimit-Limit` | Jumlah maksimum permintaan dalam jendela waktu. |
| `RateLimit-Remaining` | Sisa permintaan pada jendela saat ini. |
| `RateLimit-Reset` | Detik tersisa (atau timestamp) sampai kuota di-reset. |
| `Retry-After` | (Pada `429`) berapa detik harus menunggu sebelum mencoba lagi. |

::: tip Nama header bisa bervariasi
Selalu baca nilai dari respons, jangan hard-code angka kuota. Untuk batas pasti
per-endpoint, lihat [Referensi API interaktif](/api-reference.html).
:::

## Menangani `429`

Saat menerima `429 Too Many Requests`, jangan langsung mengulang. Tunggu sesuai
`Retry-After` (atau `RateLimit-Reset`), lalu retry dengan **exponential backoff**
dan jitter.

```ts
async function requestWithRetry(url: string, init: RequestInit, max = 5) {
  for (let attempt = 0; attempt < max; attempt++) {
    const res = await fetch(url, init)
    if (res.status !== 429) return res

    const retryAfter = Number(res.headers.get('Retry-After')) || 2 ** attempt
    const jitter = Math.random() * 0.3 * retryAfter
    await new Promise((r) => setTimeout(r, (retryAfter + jitter) * 1000))
  }
  throw new Error('Rate limit: gagal setelah beberapa percobaan')
}
```

## Praktik baik

- **Pakai webhooks**, bukan polling, untuk event masuk — lihat [Webhooks](/api/webhooks).
- **Batch** dan beri jeda pekerjaan besar (mis. impor kontak, broadcast).
- **Hormati `RateLimit-Remaining`** dan perlambat sebelum mencapai nol.
- **Idempotency** pada write agar retry aman (kirim ulang `idempotency-key` yang sama).

## Langkah selanjutnya

- [Errors](/api/errors) untuk amplop error dan kode lain.
- [Pagination](/api/pagination) untuk mengambil data besar tanpa membebani API.

---

<!-- Source: https://docs.volara.chat/api/webhooks -->

# Webhooks

Webhook mengirim event Volara ke endpoint HTTPS Anda secara **real-time**, sehingga
Anda tidak perlu polling. Gunakan webhook untuk bereaksi atas pesan masuk, perubahan
status, percakapan baru, dan event lainnya.

## Cara kerja

1. Daftarkan URL endpoint HTTPS Anda (di dashboard atau via API).
2. Volara mengirim `POST` JSON ke URL itu setiap kali event terjadi.
3. Endpoint Anda **memverifikasi tanda tangan**, lalu membalas `2xx` secepatnya.
4. Jika endpoint gagal/timeout, Volara **mengulang dengan backoff**.

## Contoh payload

```json
{
  "id": "evt_01HZ...",
  "type": "message.received",
  "createdAt": "2026-06-23T08:12:00.000Z",
  "data": {
    "channelId": "ch_123",
    "conversationId": "conv_456",
    "message": {
      "id": "msg_789",
      "from": "6281234567890",
      "type": "text",
      "text": "Halo, saya mau tanya produk"
    }
  }
}
```

Contoh tipe event: `message.received`, `message.status`, `conversation.created`,
`conversation.assigned`, `ticket.updated`. Katalog event lengkap dan bentuk payload
persisnya ada di [Referensi API interaktif](/api-reference.html).

## Verifikasi tanda tangan (HMAC-SHA256)

Setiap permintaan webhook menyertakan header tanda tangan yang dihitung sebagai
**HMAC-SHA256** dari **raw body** menggunakan **signing secret** webhook Anda.
**Wajib** verifikasi sebelum memproses, dan **gunakan body mentah** (jangan body
yang sudah di-parse ulang).

::: code-group

```ts [Node.js (Express)]
import crypto from 'node:crypto'

// Pastikan dapat membaca raw body, mis. express.raw({ type: 'application/json' })
app.post('/webhooks/volara', (req, res) => {
  const signature = req.header('X-Volara-Signature') || ''
  const secret = process.env.VOLARA_WEBHOOK_SECRET!

  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body) // Buffer mentah
    .digest('hex')

  const ok =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))

  if (!ok) return res.status(401).send('invalid signature')

  const event = JSON.parse(req.body.toString('utf8'))
  // ... proses event (idempotent), lalu:
  res.sendStatus(200)
})
```

```python [Python (Flask)]
import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/webhooks/volara")
def volara_webhook():
    signature = request.headers.get("X-Volara-Signature", "")
    secret = os.environ["VOLARA_WEBHOOK_SECRET"].encode()
    expected = hmac.new(secret, request.get_data(), hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)
    event = request.get_json()
    # ... proses event (idempotent)
    return "", 200
```

:::

::: warning Gunakan perbandingan konstan-waktu
Bandingkan tanda tangan dengan `timingSafeEqual` / `hmac.compare_digest`, bukan `==`,
untuk mencegah timing attack. Verifikasi memakai **raw body**, bukan JSON yang
diserialisasi ulang (urutan field/spasi bisa berubah).
:::

::: tip Nama header
Nama header tanda tangan (mis. `X-Volara-Signature`) dan secret-nya tampil saat
Anda membuat webhook di dashboard. Selalu konfirmasi di
[Referensi API interaktif](/api-reference.html).
:::

## Retry & idempotency

- **Retry/backoff** — jika endpoint tidak membalas `2xx` (atau timeout), Volara
  mengulang pengiriman dengan jeda yang membesar.
- **Idempotency** — event yang sama bisa terkirim lebih dari sekali. Simpan
  `event.id` yang sudah diproses dan abaikan duplikat.
- **Balas cepat** — kembalikan `2xx` segera, lalu proses berat di background agar
  tidak timeout dan memicu retry.

## Langkah selanjutnya

- [Rate Limits](/api/rate-limits) — webhook menggantikan polling.
- [Errors](/api/errors) — penanganan kegagalan.
- [Business Webhooks](/api-reference.html) — daftar event & manajemen di API Reference.

---

<!-- Source: https://docs.volara.chat/byok -->

# BYOK — Bring Your Own Key

BYOK memungkinkan tiap tenant memakai kunci API provider AI miliknya sendiri,
alih-alih kuota bawaan Volara. Cocok untuk organisasi yang ingin kontrol penuh atas
biaya, model, dan kepatuhan AI mereka.

## Cara kerja

- **Registry per-tenant** — kunci provider disimpan terenkripsi per tenant.
- **Uji koneksi** — verifikasi kunci sebelum dipakai produksi.
- **Fallback otomatis** — bila provider utama gagal, sistem beralih ke cadangan.
- **Dipakai lintas fitur** — [AI Chatbot](/guides/ai-chatbot) dan
  [Knowledge / RAG](/guides/knowledge) memakai konfigurasi BYOK Anda.

::: warning Keamanan kunci
Kunci disimpan terenkripsi dan tidak pernah ditampilkan kembali setelah disimpan.
Putar (rotate) kunci secara berkala dan cabut yang tidak terpakai.
:::

## Menyiapkan BYOK

1. Buka pengaturan AI tenant Anda di dashboard.
2. Tambahkan provider AI dan tempelkan kunci API milik Anda.
3. Jalankan **uji koneksi** untuk memastikan kunci valid sebelum dipakai produksi.
4. (Opsional) Tetapkan provider cadangan untuk **fallback otomatis**.
5. Hubungkan ke [AI Chatbot](/guides/ai-chatbot) dan [Knowledge / RAG](/guides/knowledge).

::: tip Kunci tidak pernah dikembalikan oleh API
Sesuai prinsip keamanan, endpoint AI tidak pernah mengembalikan nilai kunci yang
tersimpan — hanya status (terpasang/teruji). Lihat endpoint AI di
[Referensi API interaktif](/api-reference.html).
:::

## Langkah selanjutnya

- Aktifkan di pengaturan AI tenant, lalu hubungkan ke
  [AI Chatbot](/guides/ai-chatbot).
- Untuk agency, atur BYOK per klien — lihat [Agency](/agency).
- Pelajari endpoint AI di [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/changelog -->

# Changelog

Catatan perubahan platform dan API Volara. Perubahan terbaru di atas.

## 2026-06 — Agency, Voice AI & BYOK

- **Agency overview & white-label** — kelola portofolio klien, brand kit (logo &
  favicon), dan custom domain dari organisasi induk. Lihat [Agency](/agency).
- **Voice AI** — agent suara per-organisasi dengan kill-switch, consent, dan usage
  ledger. Lihat [Voice AI](/voice-ai).
- **BYOK** — registry AI provider per-tenant yang terenkripsi, dengan uji koneksi
  dan fallback. Lihat [BYOK](/byok).

## Sebelumnya

- Inbox omnichannel, CRM & Pipeline, AI Chatbot, Knowledge/RAG, Broadcast, Flows,
  Tickets, dan Analytics. Lihat [Panduan](/guides/inbox).

::: tip Berlangganan pembaruan
Halaman ini diperbarui setiap rilis. Bagi developer, perubahan API yang relevan
juga tercermin di [API Reference](/api).
:::

---

<!-- Source: https://docs.volara.chat/faq -->

# FAQ

## Channel apa saja yang didukung?

Volara mendukung [WhatsApp](/guides/whatsapp), [Instagram](/guides/instagram), dan
[TikTok](/guides/tiktok) dalam satu [Inbox omnichannel](/guides/inbox).

## Bagaimana cara mendapatkan API key?

Buka **Settings → API Keys** di [app.volara.chat](https://app.volara.chat), lalu
buat kunci baru. Kunci hanya ditampilkan sekali — simpan dengan aman. Lihat
[Quickstart](/quickstart).

## Mengapa saya tidak bisa mengirim pesan WhatsApp bebas kapan saja?

WhatsApp membatasi pesan free-form ke jendela 24 jam sejak balasan terakhir
pelanggan. Di luar itu, gunakan **template** yang disetujui. Lihat
[Channel WhatsApp](/guides/whatsapp).

## Apakah chatbot AI bisa pakai model saya sendiri?

Ya. Dengan [BYOK](/byok), tiap tenant dapat memakai kunci provider AI sendiri,
lengkap dengan uji koneksi dan fallback.

## Bisakah saya menjual Volara dengan merek saya sendiri?

Bisa. Mode [Agency & White-label](/agency) menyediakan brand kit, custom domain,
dan pengelolaan banyak tenant klien.

## Di mana referensi API lengkap?

Lihat [API Reference](/api). Spesifikasi mesin-terbaca tersedia sebagai OpenAPI 3.1,
dan dokumentasi ini juga menyediakan [`/llms.txt`](/llms.txt) +
[`/llms-full.txt`](/llms-full.txt) untuk konsumsi AI.

---

<!-- Source: https://docs.volara.chat/guides/ai-chatbot -->

# AI Chatbot & Guardrails

AI Chatbot Volara membalas pelanggan secara otomatis di semua channel, memakai
[Knowledge / RAG](/guides/knowledge) Anda sebagai sumber jawaban, dengan
**guardrails** untuk menjaga jawaban tetap relevan dan aman.

## Cara kerja

1. Pesan masuk dari channel diteruskan ke chatbot.
2. Chatbot mengambil konteks relevan dari [Knowledge base](/guides/knowledge).
3. Model AI menyusun jawaban dalam batas guardrails yang Anda tetapkan.
4. Jika di luar cakupan, percakapan di-*handover* ke agen di [Inbox](/guides/inbox).

## Guardrails

Guardrails memastikan chatbot berperilaku sesuai kebijakan Anda:

- **Persona & nada** — atur gaya bahasa dan batasan topik.
- **Cakupan jawaban** — batasi jawaban hanya pada knowledge yang disediakan.
- **Handover otomatis** — alihkan ke agen manusia untuk topik sensitif atau saat
  pelanggan meminta.
- **Jam aktif** — tentukan kapan chatbot membalas dan kapan menyerahkan ke tim.

::: tip Pakai AI provider Anda sendiri
Dengan [BYOK](/byok), Anda bisa memakai kunci API provider AI sendiri (per-tenant),
lengkap dengan uji koneksi dan fallback otomatis.
:::

## Knowledge base (RAG)

Akurasi chatbot bergantung pada kualitas knowledge. Lihat
[Knowledge / RAG](/guides/knowledge) untuk mengunggah dokumen, FAQ, dan sumber lain
yang menjadi dasar jawaban. Chatbot mengambil konteks dari knowledge yang Anda cari
lewat `GET /knowledge/sources?q=` dan `GET /knowledge/faqs?q=`.

## Konfigurasi via API

Konfigurasi chatbot (persona, guardrails, aktif/nonaktif) dapat dibaca dan diubah
lewat endpoint **Chatbot** di [API Reference](/api). Karena bentuk field bisa
berubah, ambil kontrak persisnya dari [Referensi API interaktif](/api-reference.html)
ketimbang dari contoh statis.

## Langkah selanjutnya

- Isi [Knowledge base](/guides/knowledge) Anda.
- Atur [Flows](/guides/flows) untuk alur lanjutan dan eskalasi.
- Pakai [BYOK](/byok) untuk provider AI sendiri.
- Pertimbangkan [Voice AI](/voice-ai) untuk percakapan suara.

---

<!-- Source: https://docs.volara.chat/guides/analytics -->

# Analytics

Analytics memberi gambaran kesehatan operasional Anda lintas channel, tim, dan
otomasi — agar keputusan berbasis data.

## Metrik yang dipantau

- **Volume** — jumlah percakapan dan pesan per channel.
- **Waktu respons** — kecepatan balasan pertama dan resolusi.
- **Performa agen** — beban kerja dan penyelesaian per agen.
- **Konversi pipeline** — pergerakan peluang di [CRM](/guides/crm).
- **Efektivitas AI** — porsi percakapan yang diselesaikan
  [AI Chatbot](/guides/ai-chatbot) tanpa handover.

## Ekspor metrik via API

Metrik dan ringkasan dashboard dapat diambil lewat endpoint **Metrics** di
[API Reference](/api) untuk dimasukkan ke BI/data warehouse Anda. Hormati
[rate limit](/api/rate-limits) saat menarik data berkala. Bentuk respons persisnya
ada di [Referensi API interaktif](/api-reference.html).

## Langkah selanjutnya

- Optimalkan alur dengan [Flows](/guides/flows).
- Tingkatkan jawaban dengan [Knowledge base](/guides/knowledge) yang lebih baik.
- Ambil data via [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/guides/broadcast -->

# Broadcast

Broadcast mengirim pesan ke banyak kontak sekaligus — ideal untuk pengumuman,
promo, dan notifikasi. Untuk WhatsApp, broadcast memakai **template** yang sudah
disetujui agar mematuhi kebijakan platform.

## Membuat broadcast

1. Pilih channel dan **template** pesan.
2. Pilih segmen kontak (berdasar tag/atribut [CRM](/guides/crm)).
3. Jadwalkan atau kirim sekarang.
4. Pantau status pengiriman dan balasan di [Inbox](/guides/inbox).

::: warning Patuhi kebijakan platform
Hindari spam. Pastikan kontak memberi consent dan gunakan template sesuai kategori
yang disetujui untuk menjaga kualitas nomor.
:::

## Otomasi via API

Broadcast dan template dapat dikelola lewat endpoint **Broadcast** di
[API Reference](/api). Untuk pekerjaan besar, jadwalkan dan beri jeda agar tetap di
bawah [rate limit](/api/rate-limits); pantau hasil pengiriman lewat
[webhook](/api/webhooks) `message.status`. Bentuk request persisnya ada di
[Referensi API interaktif](/api-reference.html).

## Langkah selanjutnya

- Siapkan segmen di [CRM & Pipeline](/guides/crm).
- Otomatiskan tindak lanjut dengan [Flows](/guides/flows).
- Pantau pengiriman lewat [Webhooks](/api/webhooks).

---

<!-- Source: https://docs.volara.chat/guides/crm -->

# CRM & Pipeline

CRM Volara menyatukan data pelanggan dengan percakapan. Setiap kontak terhubung ke
[Inbox](/guides/inbox) sehingga tim sales melihat riwayat lengkap saat berinteraksi.

## Kontak & perusahaan

Simpan kontak beserta atribut khusus (custom fields), tag, dan riwayat percakapan
lintas channel. Kontak otomatis dibuat saat ada pesan masuk dari nomor baru.

## Pipeline

Pipeline adalah papan visual tahap-tahap penjualan. Geser peluang antar tahap,
beri nilai (value), dan pantau konversi di [Analytics](/guides/analytics).

## Kelola kontak via API

Buat dan ambil kontak lewat REST API untuk sinkronisasi dengan sistem internal:

::: code-group

```bash [Buat kontak]
curl -X POST https://api.volara.chat/api/v1/contacts \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Budi Santoso", "phone": "6281234567890" }'
```

```bash [Daftar kontak (paginasi kursor)]
curl "https://api.volara.chat/api/v1/contacts?limit=100" \
  -H "Authorization: Bearer API_KEY"
```

:::

::: tip Akses via API
Kontak, pipeline, dan percakapan tersedia lewat [API Reference](/api). Endpoint daftar
memakai [pagination kursor](/api/pagination); tangani `429` dengan
[backoff](/api/rate-limits). Bentuk field persisnya ada di
[Referensi API interaktif](/api-reference.html).
:::

## Langkah selanjutnya

- Hubungkan percakapan di [Inbox](/guides/inbox).
- Otomatiskan pemindahan tahap dengan [Flows](/guides/flows).
- Lihat endpoint Contacts & CRM di [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/guides/flows -->

# Flows / Automation

Flows adalah pembangun alur otomasi visual. Tetapkan pemicu (trigger), kondisi, dan
aksi untuk menangani percakapan secara otomatis — tanpa menulis kode.

## Anatomi sebuah flow

- **Trigger** — misalnya pesan masuk, kata kunci tertentu, atau kontak baru.
- **Kondisi** — cabang berdasarkan atribut [CRM](/guides/crm), channel, atau jam.
- **Aksi** — balas pesan, tugaskan agen, beri tag, buat [tiket](/guides/tickets),
  atau panggil [AI Chatbot](/guides/ai-chatbot).

## Contoh kasus

- Routing: arahkan pertanyaan billing ke tim finance.
- Eskalasi: jika pelanggan menulis "komplain", handover ke agen + buat tiket.
- Tindak lanjut: kirim pesan otomatis bila percakapan tak dibalas dalam 24 jam.

## Memicu dari sistem eksternal

Selain trigger bawaan, flow dapat bereaksi atas event yang Anda terima lewat
[webhook](/api/webhooks), atau Anda picu aksi dari sistem Anda lewat
[API Reference](/api) (mis. kirim pesan, buat tiket). Lihat endpoint **Flow** di
[Referensi API interaktif](/api-reference.html).

## Langkah selanjutnya

- Padukan dengan [AI Chatbot](/guides/ai-chatbot) dan [Tickets](/guides/tickets).
- Ukur dampak di [Analytics](/guides/analytics).
- Integrasikan event eksternal via [Webhooks](/api/webhooks).

---

<!-- Source: https://docs.volara.chat/guides/inbox -->

# Inbox Omnichannel

Inbox adalah pusat kerja harian tim support dan sales Anda. Semua percakapan dari
[WhatsApp](/guides/whatsapp), [Instagram](/guides/instagram), dan
[TikTok](/guides/tiktok) masuk ke satu tampilan terpadu, sehingga tim tidak perlu
berpindah aplikasi.

## Cara kerja

Setiap pesan masuk dikelompokkan menjadi **percakapan** per kontak per channel.
Percakapan memiliki status (terbuka, tertunda, selesai) dan dapat ditugaskan ke
anggota tim tertentu.

## Fitur utama

- **Tampilan terpadu** — filter berdasarkan channel, status, agen, atau label.
- **Assignment** — tugaskan percakapan ke agen agar tidak ada yang terlewat.
- **Label & catatan internal** — beri konteks tanpa terlihat oleh pelanggan.
- **Balasan cepat & template** — jawab pertanyaan umum dalam sekali klik.
- **Konteks pelanggan** — data [CRM](/guides/crm) tampil di samping percakapan.

## Otomasi

Padukan Inbox dengan:

- [AI Chatbot](/guides/ai-chatbot) untuk balasan otomatis dan triase.
- [Flows](/guides/flows) untuk routing dan eskalasi otomatis.
- [Tickets](/guides/tickets) untuk kasus yang butuh penanganan terstruktur.

## Akses via API

Percakapan dan pesan tersedia lewat REST API untuk membangun integrasi atau
dashboard sendiri:

::: code-group

```bash [Daftar percakapan]
curl "https://api.volara.chat/api/v1/conversations?limit=50" \
  -H "Authorization: Bearer API_KEY"
```

```bash [Balas percakapan]
curl -X POST https://api.volara.chat/api/v1/messages \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": "CHANNEL_ID", "to": "6281234567890", "type": "text", "text": "Terima kasih!" }'
```

:::

::: tip Real-time tanpa polling
Daftarkan [webhook](/api/webhooks) untuk event pesan masuk dan perubahan
percakapan, alih-alih polling. Endpoint daftar memakai
[pagination kursor](/api/pagination).
:::

## Langkah selanjutnya

- Hubungkan channel pertama Anda di [panduan WhatsApp](/guides/whatsapp).
- Atur [CRM & Pipeline](/guides/crm) agar konteks pelanggan lengkap.
- Otomatiskan lewat [Webhooks](/api/webhooks) dan [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/guides/instagram -->

# Channel Instagram

Hubungkan akun Instagram Business Anda untuk mengelola direct message langsung dari
[Inbox](/guides/inbox), sama seperti channel lainnya.

## Menghubungkan channel

1. Buka **Settings → Channels → Instagram**.
2. Otorisasi akun Instagram Business yang tertaut ke halaman Facebook Anda.
3. Setelah status **Connected**, DM masuk akan otomatis muncul di Inbox.

::: warning Prasyarat
Instagram memerlukan akun **Business/Creator** yang tertaut ke halaman Facebook.
Akun personal tidak didukung untuk integrasi messaging.
:::

## Balas & otomasi

- Balas DM dari [Inbox](/guides/inbox) seperti channel lain.
- Aktifkan [AI Chatbot](/guides/ai-chatbot) untuk balasan otomatis.
- Kirim dan terima pesan lewat [API](/api) dengan `channelId` Instagram.

```bash
curl -X POST https://api.volara.chat/api/v1/messages \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": "INSTAGRAM_CHANNEL_ID", "to": "INSTAGRAM_USER_ID", "type": "text", "text": "Halo!" }'
```

Untuk DM masuk secara real-time, daftarkan [webhook](/api/webhooks).

## Langkah selanjutnya

- Pelajari [Inbox omnichannel](/guides/inbox).
- Hubungkan [WhatsApp](/guides/whatsapp) dan [TikTok](/guides/tiktok) juga.
- Lihat endpoint Instagram di [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/guides/knowledge -->

# Knowledge / RAG

Knowledge base adalah otak dari [AI Chatbot](/guides/ai-chatbot). Dengan pendekatan
RAG (retrieval-augmented generation), chatbot mengambil potongan informasi paling
relevan dari knowledge Anda sebelum menyusun jawaban — sehingga jawaban berdasar
data Anda, bukan tebakan model.

## Mengisi knowledge

- **Unggah dokumen** — produk, kebijakan, panduan internal.
- **FAQ** — pasangan tanya-jawab yang sering muncul.
- **Sumber teks** — tempelkan konten langsung.

Konten dipotong, di-*embed*, dan diindeks agar bisa dicari secara semantik.

::: tip Kualitas knowledge = kualitas jawaban
Jaga knowledge tetap ringkas, faktual, dan terbarui. Hapus dokumen usang agar
chatbot tidak memberi jawaban yang salah.
:::

## Mencari knowledge via API

Knowledge dapat dicari lewat parameter query `q` pada endpoint sumber dan FAQ.
Tidak ada endpoint RAG khusus terpisah — pencarian dilakukan langsung pada
resource knowledge:

::: code-group

```bash [Cari sumber]
curl "https://api.volara.chat/api/v1/knowledge/sources?q=kebijakan%20retur" \
  -H "Authorization: Bearer API_KEY"
```

```bash [Cari FAQ]
curl "https://api.volara.chat/api/v1/knowledge/faqs?q=ongkir" \
  -H "Authorization: Bearer API_KEY"
```

:::

Untuk daftar endpoint knowledge lengkap (kategori, sumber, FAQ, stats) dan bentuk
respons persisnya, buka [Referensi API interaktif](/api-reference.html). Hasil
daftar dipaginasi dengan kursor — lihat [Pagination](/api/pagination).

## Langkah selanjutnya

- Hubungkan ke [AI Chatbot](/guides/ai-chatbot).
- Pakai [BYOK](/byok) untuk memilih provider embedding/LLM Anda.
- Jelajahi endpoint di [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/guides/tickets -->

# Tickets

Tickets mengubah percakapan menjadi kasus yang dapat dilacak. Cocok untuk masalah
yang butuh penanganan terstruktur dan SLA, bukan sekadar balasan cepat.

## Siklus hidup tiket

1. Tiket dibuat dari [Inbox](/guides/inbox), [Flows](/guides/flows), atau manual.
2. Beri prioritas, kategori, dan tugaskan ke agen/tim.
3. Lacak status hingga **selesai**.
4. Pantau metrik penyelesaian di [Analytics](/guides/analytics).

::: tip Otomasi pembuatan tiket
Gunakan [Flows](/guides/flows) untuk membuat tiket otomatis saat terdeteksi kata
kunci tertentu (mis. "refund", "komplain").
:::

## Kelola tiket via API

Buat, perbarui status, dan ambil tiket lewat endpoint **Tickets** di
[API Reference](/api). Berlangganan event `ticket.updated` lewat
[webhook](/api/webhooks) agar sistem Anda selalu sinkron. Bentuk field persisnya
ada di [Referensi API interaktif](/api-reference.html).

## Langkah selanjutnya

- Hubungkan dengan [Inbox](/guides/inbox) dan [Flows](/guides/flows).
- Analisis performa di [Analytics](/guides/analytics).
- Otomatiskan via [API Reference](/api) dan [Webhooks](/api/webhooks).

---

<!-- Source: https://docs.volara.chat/guides/tiktok -->

# Channel TikTok

Tambahkan TikTok sebagai channel agar pesan dari audiens TikTok Anda masuk ke
[Inbox](/guides/inbox) yang sama dengan WhatsApp dan Instagram.

## Menghubungkan channel

1. Buka **Settings → Channels → TikTok**.
2. Otorisasi akun TikTok bisnis Anda.
3. Setelah **Connected**, pesan masuk tampil di Inbox dan dapat dibalas tim.

## Balas & otomasi

- Tangani percakapan dari [Inbox](/guides/inbox).
- Aktifkan [AI Chatbot](/guides/ai-chatbot) untuk balasan otomatis.
- Gunakan [API](/api) dengan `channelId` TikTok untuk integrasi kustom, dan
  [webhook](/api/webhooks) untuk pesan masuk real-time.

## Langkah selanjutnya

- Satukan semua channel di [Inbox omnichannel](/guides/inbox).
- Buat kampanye dengan [Broadcast](/guides/broadcast).
- Lihat endpoint TikTok di [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/guides/whatsapp -->

# Channel WhatsApp

WhatsApp adalah channel paling populer untuk percakapan dengan pelanggan di
Indonesia. Panduan ini menjelaskan cara menghubungkan nomor WhatsApp ke Volara
dan mulai berkomunikasi melalui [Inbox](/guides/inbox) maupun [API](/api).

## Menghubungkan channel

1. Buka **Settings → Channels → WhatsApp** di dashboard.
2. Ikuti langkah otorisasi untuk menautkan nomor WhatsApp Business Anda.
3. Setelah status menjadi **Connected**, catat `channelId` untuk dipakai di API.

::: warning Verifikasi nomor
Nomor harus memenuhi syarat WhatsApp Business. Nomor yang sudah dipakai di aplikasi
WhatsApp personal pada perangkat lain perlu dilepas terlebih dahulu.
:::

## Mengirim pesan teks

Setelah channel aktif, kirim pesan lewat API:

::: code-group

```bash [cURL]
curl -X POST https://api.volara.chat/api/messages \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "CHANNEL_ID",
    "to": "6281234567890",
    "type": "text",
    "text": "Halo! Ada yang bisa kami bantu?"
  }'
```

```ts [TypeScript]
await fetch('https://api.volara.chat/api/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOLARA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    channelId: 'CHANNEL_ID',
    to: '6281234567890',
    type: 'text',
    text: 'Halo! Ada yang bisa kami bantu?',
  }),
})
```

:::

## Template & jendela 24 jam

WhatsApp membatasi pesan bebas (free-form) ke dalam jendela 24 jam sejak balasan
terakhir pelanggan. Di luar jendela tersebut, gunakan **template** yang sudah
disetujui. Kelola dan kirim template untuk [Broadcast](/guides/broadcast) dan
notifikasi terjadwal.

## Menerima balasan

Balasan pelanggan otomatis masuk ke [Inbox](/guides/inbox) pada percakapan yang
sama. Untuk diberi tahu secara real-time di sistem Anda, daftarkan
[webhook](/api/webhooks) untuk event `message.received` (verifikasi tanda tangan
HMAC-SHA256 sebelum memproses).

## Langkah selanjutnya

- Aktifkan [AI Chatbot](/guides/ai-chatbot) untuk balasan otomatis.
- Siapkan [Broadcast](/guides/broadcast) untuk kampanye berbasis template.
- Lihat endpoint WhatsApp & WABA di [API Reference](/api).

---

<!-- Source: https://docs.volara.chat/quickstart -->

# Quickstart

Panduan ini membawa Anda dari nol sampai mengirim pesan pertama lewat API Volara
dalam waktu kurang dari lima menit.

## Konsep inti

Sebelum mulai, kenali tiga konsep yang dipakai di seluruh dokumentasi:

- **Tenant (organisasi)** — ruang kerja Anda. Semua data (kontak, percakapan,
  channel) terisolasi per-tenant. Konteks tenant ditentukan dari sesi login atau
  API key terverifikasi — tidak pernah dari header publik.
- **Channel** — koneksi ke platform pesan: WhatsApp, Instagram, atau TikTok.
  Satu tenant bisa punya banyak channel.
- **Conversation (percakapan)** — utas pesan dengan satu kontak di satu channel,
  muncul di [Inbox omnichannel](/guides/inbox).

## 1. Buat akun & organisasi

Daftar di [app.volara.chat](https://app.volara.chat) lalu buat organisasi
pertama Anda. Organisasi inilah tenant Anda.

## 2. Ambil API key

Buka **Settings → API Keys** di dashboard, lalu buat API key baru. Simpan kunci
dengan aman — kunci hanya ditampilkan sekali. Semua permintaan API memakai header
`Authorization: Bearer <API_KEY>` (atau `x-api-key`). Detail lengkap di
[Autentikasi](/api/authentication).

::: warning Jaga kerahasiaan API key
API key memberi akses penuh ke data tenant Anda. Jangan menaruhnya di kode
frontend, repositori publik, atau bundel klien. Gunakan hanya dari server.
:::

## 3. Hubungkan channel

Hubungkan minimal satu channel agar bisa mengirim pesan. Untuk WhatsApp, ikuti
[panduan channel WhatsApp](/guides/whatsapp). Setelah terhubung, catat
`channelId`-nya.

## 4. Kirim pesan pertama

Ganti `API_KEY`, `CHANNEL_ID`, dan nomor tujuan, lalu jalankan:

::: code-group

```bash [cURL]
curl -X POST https://api.volara.chat/api/v1/messages \
  -H "Authorization: Bearer API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "CHANNEL_ID",
    "to": "6281234567890",
    "type": "text",
    "text": "Halo dari Volara!"
  }'
```

```ts [TypeScript (fetch)]
const res = await fetch('https://api.volara.chat/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VOLARA_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    channelId: 'CHANNEL_ID',
    to: '6281234567890',
    type: 'text',
    text: 'Halo dari Volara!',
  }),
})

const data = await res.json()
console.log(data)
```

```python [Python (requests)]
import os, requests

res = requests.post(
    "https://api.volara.chat/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['VOLARA_API_KEY']}"},
    json={
        "channelId": "CHANNEL_ID",
        "to": "6281234567890",
        "type": "text",
        "text": "Halo dari Volara!",
    },
)
print(res.json())
```

:::

::: tip Hasil yang diharapkan
Respons `2xx` berisi `id` pesan. Pesan akan muncul di [Inbox](/guides/inbox)
sebagai pesan keluar, dan balasan kontak akan masuk ke percakapan yang sama.
:::

## Langkah selanjutnya

- Jelajahi [Referensi API interaktif](/api-reference.html) lengkap dengan try-it.
- Pahami [Errors](/api/errors), [Rate Limits](/api/rate-limits), dan
  [Pagination](/api/pagination).
- Terima event real-time dengan [Webhooks](/api/webhooks).
- Pasang [AI Chatbot](/guides/ai-chatbot) agar membalas otomatis.
- Pelajari [Flows / Automation](/guides/flows) untuk alur lanjutan.

---

<!-- Source: https://docs.volara.chat/sdk -->

# SDK & Integrasi

Volara punya SDK resmi untuk lima bahasa dan beberapa integrasi siap pakai. Semuanya
membungkus [REST API](/api) yang sama, jadi yang Anda pelajari di satu tempat berlaku
di tempat lain.

Semua SDK pakai autentikasi yang sama: satu **API key** per tenant (lihat
[Autentikasi](/api/authentication)). Setiap SDK membaca env `VOLARA_API_KEY` atau
menerima kunci lewat constructor. Kode sumber ada di
[github.com/volara-asia](https://github.com/volara-asia).

## SDK resmi

| SDK | Paket | Untuk |
| --- | --- | --- |
| [TypeScript / JavaScript](/sdk/javascript) | `@volara/sdk` (npm) | Node 18+, browser, Cloudflare Workers / edge |
| [Python](/sdk/python) | `volara` (PyPI) | Python 3.9+, tanpa dependensi pihak ketiga |
| [PHP](/sdk/php) | `volara/sdk` (Composer) | PHP 8.0+, cocok untuk plugin WordPress/WooCommerce |
| [Ruby](/sdk/ruby) | `volara` (RubyGems) | Ruby 3.0+, hanya standard library |
| [Go](/sdk/go) | `github.com/volara-asia/volara-go` | Go 1.21+, hanya standard library |

Tiap SDK menyediakan resource yang sama — `messages`, `conversations`, `contacts`,
`broadcasts`, `knowledge`, `metrics`, dan `agency` — plus verifikasi webhook,
auto-retry pada `429`/`5xx`, dan idempotency key otomatis untuk setiap operasi tulis.

## Integrasi

| Integrasi | Untuk |
| --- | --- |
| [WordPress & WooCommerce](/sdk/wordpress) | Tangkap lead jadi kontak CRM, notifikasi pesanan via WhatsApp, dan widget chat — tanpa coding. |
| [n8n](/sdk/n8n) | Rangkai Volara ke ratusan aplikasi lewat node komunitas, plus trigger untuk event Volara. |
| MCP server | Ekspos Volara sebagai tool [Model Context Protocol](https://modelcontextprotocol.io) untuk agen AI. Server meneruskan API key pemanggil ke REST API; tenant dan scope tetap diturunkan dari kunci. |

## Mulai dari mana

- Baru pertama kali? Ikuti [Quickstart](/quickstart) untuk mengambil API key dan
  mengirim pesan pertama.
- Pilih halaman SDK bahasa Anda di tabel di atas untuk contoh lengkap.
- Butuh endpoint yang belum dimodelkan SDK? Pakai escape hatch (`request()` /
  `raw()`) atau panggil [REST API](/api) langsung.

---

<!-- Source: https://docs.volara.chat/sdk/go -->

# SDK Go

Klien resmi Go untuk Volara: messaging, conversations, CRM contacts, broadcast,
knowledge, metrics, dan agency white-label.

Dibangun hanya di atas standard library Go — tanpa dependensi pihak ketiga.
**Go 1.21+**.

Kode sumber: [github.com/volara-asia/volara-go](https://github.com/volara-asia/volara-go).

## Install

```sh
go get github.com/volara-asia/volara-go
```

```go
import volara "github.com/volara-asia/volara-go"
```

## Autentikasi

Ambil API key dari dashboard Volara (**Settings → API Keys**). Berikan ke `NewClient`,
atau kosongkan argumen dan set env `VOLARA_API_KEY`.

```go
client, err := volara.NewClient("sk_live_...")   // eksplisit
client, err := volara.NewClient("")              // membaca VOLARA_API_KEY
```

Kunci dikirim sebagai `Authorization: Bearer` sekaligus `x-api-key`. SDK tidak pernah
mencatatnya.

::: warning Jaga kerahasiaan API key
API key memberi akses penuh ke data tenant. Pakai hanya dari server, jangan menaruhnya
di repo publik.
:::

## Quickstart — kirim pesan pertama

```go
client, _ := volara.NewClient("") // VOLARA_API_KEY
ctx := context.Background()
msg, err := client.Messages.Send(ctx, "conv_123", volara.SendMessageParams{
	Text: "Halo dari Volara Go SDK!",
})
```

Setiap method menerima `context.Context` lebih dulu, jadi Anda mengontrol cancellation
dan deadline per panggilan.

## Konfigurasi

`NewClient` menerima functional option:

```go
client, err := volara.NewClient(
	"sk_live_...",
	volara.WithBaseURL("https://api.volara.chat"), // self-host atau region
	volara.WithTimeout(15*time.Second),            // timeout per-permintaan
	volara.WithMaxRetries(3),                      // budget retry
	volara.WithHTTPClient(myHTTPClient),           // transport/proxy kustom
	volara.WithHeader("X-Trace", "abc"),           // header di setiap permintaan
)
```

Operasi tulis mendapat `Idempotency-Key` otomatis agar create yang di-retry tidak
menggandakan data. Retry berjalan pada 408/425/429/5xx dan error jaringan, dengan
exponential backoff yang menghormati `Retry-After`.

## Contoh resource

### Conversations

```go
page, err := client.Conversations.List(ctx, volara.ListConversationsParams{
	Status:  "open",
	PerPage: 25,
})
for _, conv := range page.Data {
	fmt.Println(conv["id"])
}
```

### Contacts (CRM, telepon dalam E.164)

```go
contact, err := client.Contacts.Create(ctx, volara.CreateContactParams{
	Name:        "Budi",
	PhoneNumber: "+6281234567890",
	Source:      "website",
})
```

### Broadcasts

```go
bc, err := client.Broadcasts.Create(ctx, volara.CreateBroadcastParams{
	Title:          "Promo akhir pekan",
	MessageContent: "Diskon 20% akhir pekan ini!",
})
```

### Knowledge base & metrics

```go
res, err := client.Knowledge.Search(ctx, "refund policy", volara.KnowledgeScopeSources)
faqs, err := client.Knowledge.FAQs(ctx, "pengiriman")
stats, err := client.Metrics.Dashboard(ctx)
```

### Escape hatch

```go
tickets, err := client.Request(ctx, "GET", "/tickets", map[string]string{"status": "open"}, nil)
```

## Verifikasi webhook

Selalu verifikasi tanda tangan sebelum mempercayai webhook. Pakai body **mentah**,
bukan struct yang sudah di-encode ulang.

```go
func handler(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body)
	if !volara.VerifyWebhook(raw, r.Header.Get("x-volara-signature"), webhookSecret) {
		http.Error(w, "invalid signature", http.StatusUnauthorized)
		return
	}
	// terpercaya: parse raw ke tipe event Anda
}
```

Perbandingannya constant-time, dan awalan `sha256=` pada header tetap diterima.

## Error handling

Respons non-2xx, timeout, dan kegagalan jaringan semua mengembalikan `*volara.Error`:

```go
_, err := client.Conversations.Get(ctx, "missing")
if vErr, ok := volara.AsError(err); ok {
	log.Printf("status=%d code=%s request_id=%s", vErr.Status, vErr.Code, vErr.RequestID)
}
```

`RequestID` (dari `x-request-id` / `cf-ray`) adalah nilai yang dikutip saat menghubungi
support. `errors.As(err, &vErr)` dan `errors.Is` juga bekerja, karena error membungkus
penyebab transport di bawahnya.

## Bentuk hasil

API Volara sedang diformalkan ke spesifikasi OpenAPI 3.1 yang dibekukan. Sampai itu
rampung, objek tunggal kembali sebagai `volara.Resource` (`map[string]any`) dan list
sebagai `*volara.List` (`Data` plus `Total`/`Page`/`Limit`). Struct hasil bertipe akan
hadir setelah spec v1 dibekukan; signature method dan parameter struct sudah stabil.

## Langkah selanjutnya

- Lihat [SDK & Integrasi](/sdk) lainnya.
- Pahami [Autentikasi](/api/authentication), [Errors](/api/errors), dan [Webhooks](/api/webhooks).
- Coba endpoint di [Referensi API interaktif](/api-reference.html).

---

<!-- Source: https://docs.volara.chat/sdk/javascript -->

# SDK TypeScript / JavaScript

`@volara/sdk` adalah klien resmi TypeScript/JavaScript untuk Volara. Klien kecil,
typed, tanpa dependensi, dan berjalan di mana pun `fetch` tersedia: **Node 18+,
browser, dan Cloudflare Workers / edge**.

Kode sumber: [github.com/volara-asia](https://github.com/volara-asia).

## Install

```bash
npm install @volara/sdk
# atau
pnpm add @volara/sdk
# atau
bun add @volara/sdk
```

## Autentikasi

Buat API key di dashboard Volara (**Settings → API Keys**). Kunci membawa tenant dan
scope Anda, jadi SDK cukup mengirimkannya di setiap permintaan.

```ts
import { Volara } from '@volara/sdk'

// Set kunci lewat constructor...
const volara = new Volara({ apiKey: 'sk_live_xxx' })

// ...atau set env VOLARA_API_KEY dan biarkan SDK membacanya.
const volara2 = new Volara()
```

Self-host atau pakai endpoint regional? Override base URL:

```ts
const volara = new Volara({ apiKey: '...', baseUrl: 'https://api.volara.chat' })
```

::: warning Jaga kerahasiaan API key
API key memberi akses penuh ke data tenant. Jangan menaruhnya di bundel klien atau
repo publik — pakai hanya dari server.
:::

## Quickstart — kirim pesan pertama

```ts
import { Volara } from '@volara/sdk'

const volara = new Volara({ apiKey: process.env.VOLARA_API_KEY })
await volara.messages.send({ conversationId: 'conv_123', text: 'Halo 👋' })
```

## Contoh resource

### Conversations

```ts
const { data, total } = await volara.conversations.list({ status: 'open', perPage: 20 })
const conversation = await volara.conversations.get('conv_123')

// Auto-paging — iterasi semua percakapan tanpa mengelola nomor halaman.
for await (const c of volara.conversations.iterate({ status: 'open' })) {
  console.log(c.id, c.status)
}
```

### Messages

```ts
await volara.messages.send({ conversationId: 'conv_123', text: 'Pesanan kamu sudah dikirim.' })

// Payload lebih kaya (template, media) diteruskan sesuai dokumentasi API.
await volara.messages.send({
  conversationId: 'conv_123',
  type: 'template',
  content: { name: 'order_update', language: 'id', variables: ['#A123'] },
})
```

### Contacts (CRM)

```ts
const { data } = await volara.contacts.list({ q: 'budi', perPage: 50 })
const contact = await volara.contacts.create({
  name: 'Budi Santoso',
  phoneNumber: '+6281234567890',
  email: 'budi@example.com',
})
```

### Broadcasts

```ts
const broadcast = await volara.broadcasts.create({
  title: 'Promo Lebaran',
  messageContent: 'Diskon 30% minggu ini!',
})
```

### Knowledge base & metrics

```ts
const sources = await volara.knowledge.search('refund policy')
const faqs = await volara.knowledge.search('cara melacak pesanan', { scope: 'faqs' })
const dashboard = await volara.metrics.dashboard()
```

### Escape hatch

Butuh endpoint yang belum dimodelkan? Panggil langsung di bawah `/api/v1`:

```ts
const tickets = await volara.request('/tickets', { query: { status: 'open' } })
```

## Verifikasi webhook

Verifikasi webhook masuk dengan HMAC-SHA256. Helper memakai Web Crypto, jadi jalan di
Node, browser, dan Workers — dengan perbandingan constant-time.

```ts
import { verifyWebhook } from '@volara/sdk/webhooks'

// Baca body MENTAH dan verifikasi SEBELUM parse — re-serialize mengubah byte-nya.
const raw = await request.text()
const ok = await verifyWebhook({
  payload: raw,
  signature: request.headers.get('x-volara-signature') ?? '',
  secret: process.env.VOLARA_WEBHOOK_SECRET,
})
if (!ok) return new Response('invalid signature', { status: 401 })

const event = JSON.parse(raw)
if (event.type === 'message.received') {
  // ...
}
```

## Error handling

Setiap respons non-2xx, timeout, dan kegagalan jaringan melempar `VolaraError`. Selalu
catat `requestId` agar support Volara bisa menelusuri panggilan yang tepat.

```ts
import { Volara, VolaraError } from '@volara/sdk'

try {
  await volara.conversations.get('missing')
} catch (err) {
  if (err instanceof VolaraError) {
    console.error(err.status)    // mis. 404
    console.error(err.code)      // mis. "VLR-..." (saat API mengirimnya)
    console.error(err.requestId) // sertakan ini di tiket support
    console.error(err.message)
  }
}
```

`VolaraTimeoutError` dan `VolaraConnectionError` adalah subclass dari `VolaraError`,
jadi satu `catch (err instanceof VolaraError)` sudah mencakup semuanya.

## Resilience

- **Retry** pada `429`/`5xx` (dan gangguan jaringan) dengan exponential backoff +
  jitter, menghormati header `Retry-After`. Atur dengan `maxRetries` (default `2`).
- **Timeout** lewat `AbortSignal.timeout`. Atur dengan `timeoutMs` (default `30000`).
- **Idempotency key** otomatis menempel di setiap operasi tulis
  (`POST`/`PUT`/`PATCH`/`DELETE`) agar retry tidak menggandakan data.

```ts
const volara = new Volara({ apiKey: '...', timeoutMs: 10_000, maxRetries: 4 })
```

## Langkah selanjutnya

- Lihat [SDK & Integrasi](/sdk) lainnya.
- Pahami [Autentikasi](/api/authentication), [Errors](/api/errors), dan [Webhooks](/api/webhooks).
- Coba endpoint di [Referensi API interaktif](/api-reference.html).

---

<!-- Source: https://docs.volara.chat/sdk/n8n -->

# n8n

Node komunitas **`n8n-nodes-volara`** menghubungkan Volara ke ratusan aplikasi lain di
[n8n](https://n8n.io) tanpa menulis kode. Tersedia node aksi (Volara) dan node trigger
(Volara Trigger).

Kode sumber: [github.com/volara-asia](https://github.com/volara-asia).

## Install

Di n8n self-host, pasang node komunitas dari **Settings → Community Nodes → Install**,
lalu masukkan nama paket:

```
n8n-nodes-volara
```

## Kredensial

Buat kredensial **Volara API** sekali, lalu pakai ulang di setiap node:

1. Buat API key di dashboard Volara (**Settings → API Keys**).
2. Di n8n, buka **Credentials → New → Volara API**.
3. Tempel API key. Biarkan base URL default kecuali Anda self-host Volara.

Kunci membawa tenant dan scope Anda, jadi node tidak perlu memilih organisasi.

## Operasi (node Volara)

Node aksi memetakan resource API yang sama dengan SDK:

- **Messages** — kirim pesan WhatsApp/omnichannel ke percakapan atau kontak.
- **Conversations** — list dan ambil percakapan.
- **Contacts** — list dan buat kontak CRM.
- **Broadcasts** — buat/mulai kampanye broadcast.
- **Knowledge** — cari knowledge base (sources atau FAQ).
- **Metrics** — baca metrik dashboard.

## Trigger (node Volara Trigger)

Node **Volara Trigger** menjalankan workflow saat event Volara terjadi (misalnya pesan
masuk). Node menerima webhook dari Volara, jadi workflow Anda bereaksi real-time tanpa
polling.

## Langkah selanjutnya

- Butuh kontrol penuh lewat kode? Pakai salah satu [SDK resmi](/sdk).
- Pahami [Autentikasi](/api/authentication) dan [Webhooks](/api/webhooks).
- Lihat [SDK & Integrasi](/sdk) lainnya.

---

<!-- Source: https://docs.volara.chat/sdk/php -->

# 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](https://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)`):

| Key              | Default                     | Catatan                                 |
| ---------------- | --------------------------- | --------------------------------------- |
| `apiKey`         | `getenv('VOLARA_API_KEY')`  | API key rahasia Anda.                   |
| `baseUrl`        | `https://api.volara.chat`   | Override untuk self-host atau region.   |
| `timeout`        | `30`                        | Timeout per-permintaan, dalam detik.    |
| `maxRetries`     | `2`                         | Retry pada 429 / 5xx / error jaringan.  |
| `defaultHeaders` | `[]`                        | Header tambahan di setiap permintaan.   |

::: warning 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'       => 'budi@example.com',
]);

// 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

- SDK PHP ini juga di-bundle di [plugin WordPress / WooCommerce](/sdk/wordpress).
- Lihat [SDK & Integrasi](/sdk) lainnya.
- Pahami [Autentikasi](/api/authentication), [Errors](/api/errors), dan [Webhooks](/api/webhooks).

---

<!-- Source: https://docs.volara.chat/sdk/python -->

# SDK Python

`volara` adalah klien resmi Python untuk Volara: messaging, conversations, CRM,
broadcast, knowledge search, metrics, dan agency white-label. Tanpa dependensi pihak
ketiga (standard library saja) dan jalan di **Python 3.9 ke atas**.

Kode sumber: [github.com/volara-asia](https://github.com/volara-asia).

## Install

```bash
pip install volara
```

## Autentikasi

Set API key langsung, atau set env `VOLARA_API_KEY` dan biarkan klien membacanya. Ambil
kunci dari dashboard Volara (**Settings → API Keys**).

```python
from volara import Volara

client = Volara(api_key="sk_live_...")
# atau, dengan VOLARA_API_KEY di environment:
client = Volara()
```

::: warning Jaga kerahasiaan API key
API key memberi akses penuh ke data tenant. Pakai hanya dari server, jangan menaruhnya
di kode klien atau repo publik.
:::

## Quickstart — kirim pesan pertama

```python
from volara import Volara

client = Volara()  # membaca VOLARA_API_KEY
message = client.messages.send("conv_123", text="Halo dari Volara!")
print(message["id"])
```

## Contoh resource

### Conversations

```python
# Satu halaman (dengan metadata bila API menyediakannya)
result = client.conversations.list(status="open", per_page=25)
for conv in result["data"]:
    print(conv["id"], conv.get("status"))

# Atau iterasi semua tanpa mengelola nomor halaman sendiri
for conv in client.conversations.iterate(status="open"):
    print(conv["id"])
```

### Contacts (CRM)

```python
contact = client.contacts.create(
    name="Sita Dewi",
    phone_number="+6281234567890",
    email="sita@example.com",
)
```

### Broadcasts

```python
broadcast = client.broadcasts.create(
    title="Promo Akhir Pekan",
    message_content="Diskon 20% akhir pekan ini!",
)
```

### Knowledge base & metrics

```python
sources = client.knowledge.search("refund policy", scope="sources")
faqs = client.knowledge.search("estimasi pengiriman", scope="faqs")
metrics = client.metrics.dashboard()
```

### Escape hatch

```python
tickets = client.request("/tickets", query={"status": "open"})
```

## Verifikasi webhook

Validasi tanda tangan HMAC-SHA256 pada webhook masuk. Selalu pakai body **mentah** —
memverifikasi JSON yang sudah di-serialize ulang tidak akan cocok.

```python
import os, json
from volara import verify_webhook

raw_body = request.get_data()  # bytes, bukan JSON yang sudah di-parse
signature = request.headers.get("x-volara-signature", "")

if not verify_webhook(raw_body, signature, os.environ["VOLARA_WEBHOOK_SECRET"]):
    abort(401)

event = json.loads(raw_body)
```

Header tanda tangan boleh hex polos atau berawalan `sha256=`; keduanya diterima.

## Error handling

Setiap kegagalan memunculkan `VolaraError` (atau subclass-nya), jadi bisa ditangkap di
satu tempat. Pakai `request_id` saat menghubungi support.

```python
from volara import Volara, VolaraError

client = Volara()
try:
    client.conversations.get("does-not-exist")
except VolaraError as err:
    print(err.status, err.code, err.request_id, err.message)
```

- `VolaraTimeoutError` — permintaan melebihi timeout yang dikonfigurasi.
- `VolaraConnectionError` — permintaan gagal sebelum ada respons (DNS, TLS, offline).

## Resilience

Klien me-retry respons `429` dan `5xx` (serta error jaringan) dengan exponential
backoff, menghormati `Retry-After`. Setiap operasi tulis otomatis membawa
`Idempotency-Key` agar retry aman. Atur keduanya saat membuat klien:

```python
client = Volara(timeout=15, max_retries=3, base_url="https://api.volara.chat")
```

## Langkah selanjutnya

- Lihat [SDK & Integrasi](/sdk) lainnya.
- Pahami [Autentikasi](/api/authentication), [Errors](/api/errors), dan [Webhooks](/api/webhooks).
- Coba endpoint di [Referensi API interaktif](/api-reference.html).

---

<!-- Source: https://docs.volara.chat/sdk/ruby -->

# SDK Ruby

`volara` adalah klien resmi Ruby untuk Volara. Kirim pesan WhatsApp dan omnichannel,
kelola conversations dan contacts, jalankan broadcast, cari knowledge base, baca
metrics, dan provision org klien agency.

Dibangun di atas standard library Ruby — tanpa gem runtime untuk dipasang. Jalan di
**Ruby 3.0+**.

Kode sumber: [github.com/volara-asia](https://github.com/volara-asia).

## Install

```bash
gem install volara
```

Atau tambahkan ke `Gemfile`:

```ruby
gem "volara"
```

## Autentikasi

Ambil API key dari dashboard Volara (**Settings → API Keys**). Berikan langsung, atau
set env `VOLARA_API_KEY` dan biarkan klien membacanya.

```ruby
client = Volara::Client.new(api_key: "sk_live_...")
# atau, dengan VOLARA_API_KEY di environment:
client = Volara::Client.new
```

::: warning Jaga kerahasiaan API key
API key memberi akses penuh ke data tenant. Pakai hanya dari server, jangan menaruhnya
di kode klien atau repo publik.
:::

## Quickstart — kirim pesan pertama

```ruby
require "volara"

client = Volara::Client.new            # membaca VOLARA_API_KEY
message = client.messages.send("conv_123", text: "Halo dari Ruby!")
puts message[:id]
```

## Contoh resource

Respons kembali sebagai hash dengan symbol key (mis. `message[:id]`). Endpoint list
mengembalikan `{ data: [...], total:, page:, limit: }` saat API menyertakan metadata.

```ruby
# Conversations
client.conversations.list(status: "open", per_page: 25)[:data].each do |conv|
  puts conv[:id]
end

# Iterasi semua percakapan tanpa mengelola offset
client.conversations.each { |conv| puts conv[:id] }

# Ambil satu percakapan
client.conversations.get("conv_123")

# Contacts (CRM, telepon dalam E.164)
client.contacts.create(name: "Sari", phone_number: "+6281234567890", source: "website")

# Broadcasts
client.broadcasts.create(title: "Promo Lebaran", message_content: "Diskon 20% hari ini!")

# Knowledge base & metrics
client.knowledge.search("refund policy", scope: "faqs")
client.metrics.dashboard
```

### Escape hatch

```ruby
client.request("/tickets", query: { status: "open" })
```

## Verifikasi webhook

Verifikasi tanda tangan terhadap body **mentah** sebelum mempercayai event. Header
boleh hex polos atau membawa awalan `sha256=` — keduanya diterima, dan
perbandingannya constant-time.

```ruby
ok = Volara::Webhooks.verify(
  payload: raw_request_body,
  signature: request.get_header("HTTP_X_VOLARA_SIGNATURE").to_s,
  secret: ENV.fetch("VOLARA_WEBHOOK_SECRET")
)
```

Contoh di Sinatra:

```ruby
post "/webhooks/volara" do
  raw = request.body.read
  sig = request.env["HTTP_X_VOLARA_SIGNATURE"].to_s
  halt 401 unless Volara::Webhooks.verify(
    payload: raw, signature: sig, secret: ENV.fetch("VOLARA_WEBHOOK_SECRET")
  )
  event = JSON.parse(raw)
  # tangani event...
  status 200
end
```

## Error handling

Setiap respons non-2xx, plus kegagalan jaringan dan timeout, memunculkan
`Volara::Error`. Timeout dan kegagalan koneksi memakai subclass
`Volara::TimeoutError` dan `Volara::ConnectionError`, jadi cukup tangkap base class
untuk semuanya.

```ruby
begin
  client.conversations.get("missing")
rescue Volara::Error => err
  warn err.message      # human-readable
  warn err.status       # status HTTP (0 untuk jaringan/timeout)
  warn err.code         # kode mesin, mis. "VLR-..."
  warn err.request_id   # kutip ini saat menghubungi support
end
```

## Resilience

- Retry otomatis dengan exponential backoff pada `408`, `425`, `429`, dan `5xx`, plus
  error jaringan sementara. `Retry-After` dihormati bila ada.
- Timeout per-permintaan (`timeout:`, default 30 detik) dan budget retry
  (`max_retries:`, default 2) yang bisa dikonfigurasi.
- `Idempotency-Key` dibuat otomatis untuk setiap operasi tulis. Berikan milik Anda
  dengan `idempotency_key:`.

```ruby
client = Volara::Client.new(timeout: 10, max_retries: 4)
```

## Langkah selanjutnya

- Lihat [SDK & Integrasi](/sdk) lainnya.
- Pahami [Autentikasi](/api/authentication), [Errors](/api/errors), dan [Webhooks](/api/webhooks).
- Coba endpoint di [Referensi API interaktif](/api-reference.html).

---

<!-- Source: https://docs.volara.chat/sdk/wordpress -->

# WordPress & WooCommerce

Plugin **Volara CRM & WhatsApp** menghubungkan situs WordPress dan toko WooCommerce
Anda ke akun Volara dalam hitungan menit, tanpa perlu developer. Tempel API key,
aktifkan fitur yang dibutuhkan, lalu simpan.

[SDK PHP Volara](/sdk/php) sudah di-bundle di dalam plugin, jadi berjalan di host mana
pun tanpa Composer. API key rahasia disimpan server-side dan tidak pernah dikirim ke
browser; widget chat memakai widget key publik yang terpisah.

## Install

1. Unggah folder `volara-crm` ke `/wp-content/plugins/`, atau pasang lewat menu
   **Plugins** di WordPress.
2. Aktifkan plugin melalui menu **Plugins**.
3. Buka **Settings → Volara**.

## Hubungkan API key

1. Di **Settings → Volara**, tempel **API Key** Volara Anda (ambil dari dashboard:
   **Settings → API Keys**).
2. Biarkan **Base URL** apa adanya kecuali Anda self-host.
3. Klik **Test connection** untuk memastikan kunci valid (uji ini memanggil endpoint
   metrics Volara).
4. Aktifkan fitur yang Anda mau, lalu **Simpan**.

::: warning Jaga kerahasiaan API key
API key disimpan di database WordPress (server-side) dan tidak pernah ditampilkan
kembali secara penuh atau dikirim ke browser. Untuk widget chat, pakai **widget key
publik** yang terpisah — bukan API key rahasia.
:::

## Fitur

### Lead capture

Pelanggan yang checkout di WooCommerce atau mengisi form Contact Form 7 otomatis
tersimpan sebagai kontak di Volara CRM (nama, email, nomor telepon). Plugin mencoba
menormalkan nomor ke format E.164 — nomor lokal yang diawali `0` dikonversi ke awalan
`+62`.

Developer bisa mengirim lead dari sumber lain lewat filter:

```php
apply_filters( 'volara_capture_lead', array(
    'name'   => 'Budi',
    'email'  => 'budi@example.com',
    'phone'  => '081234567890',
    'source' => 'landing-page',
) );
```

### Notifikasi pesanan via WhatsApp

Kirim pesan WhatsApp ke pelanggan saat status pesanan WooCommerce berubah (diproses,
selesai, dibatalkan, refund). Tersedia filter untuk menyesuaikan isi pesan dan payload
notifikasi.

### Widget chat

Tampilkan launcher chat omnichannel Volara di seluruh halaman depan situs dengan satu
baris skrip, memakai **widget key publik**.

::: tip Sedang dirilis bertahap
CDN widget chat dan endpoint notifikasi sedang digulirkan. Lead capture dan integrasi
status pesanan WooCommerce sudah berjalan lewat REST API; widget dan notifikasi
mengikuti seiring rollout berlanjut.
:::

## Catatan

- **Butuh akun Volara.** Plugin menghubungkan situs ke akun Volara — daftar di
  [volara.chat](https://volara.chat) dan ambil API key dari dashboard.
- **Tidak perlu Composer.** SDK PHP sudah di-vendor di dalam plugin dan dimuat lewat
  autoloader internal.
- **WooCommerce opsional.** Lead capture dari Contact Form 7 dan widget chat berjalan
  tanpa WooCommerce. Notifikasi pesanan dan lead dari checkout hanya aktif bila
  WooCommerce terpasang.

## Langkah selanjutnya

- Butuh kontrol lebih? Pakai [SDK PHP](/sdk/php) langsung di kode Anda.
- Pahami [Autentikasi](/api/authentication) dan [Webhooks](/api/webhooks).
- Lihat [SDK & Integrasi](/sdk) lainnya.

---

<!-- Source: https://docs.volara.chat/voice-ai -->

# Voice AI

Voice AI menambahkan agent suara berbasis AI ke Volara untuk percakapan telepon
otomatis. Fitur ini dirancang dengan kontrol operasional dan kepatuhan sebagai
prioritas.

## Kontrol utama

- **Konfigurasi per-organisasi** — atur agent suara per tenant.
- **Kill-switch** — matikan Voice AI secara instan saat darurat.
- **Consent** — pastikan persetujuan perekaman/pemrosesan sesuai regulasi.
- **Usage ledger** — setiap pemakaian dicatat untuk transparansi dan billing.

::: warning Kepatuhan & consent
Selalu peroleh consent yang sah sebelum merekam atau memproses suara pelanggan.
Gunakan kill-switch jika ada indikasi penyalahgunaan atau masalah kualitas.
:::

## Menyiapkan Voice AI

1. Aktifkan Voice AI per organisasi di pengaturan, lalu konfigurasikan agent suara.
2. Pastikan alur **consent** terpasang sebelum percakapan dimulai.
3. Pantau **usage ledger** — setiap pemakaian dicatat untuk transparansi & billing.
4. Sediakan **kill-switch** yang mudah dijangkau operator untuk mematikan seketika.

## Via API

Konfigurasi Voice AI, kill-switch, dan pemakaian dapat dikelola lewat endpoint
**AI / Voice** di [API Reference](/api). Karena fitur ini sensitif terhadap
kepatuhan, ambil kontrak persisnya dari
[Referensi API interaktif](/api-reference.html).

## Langkah selanjutnya

- Padukan dengan [AI Chatbot](/guides/ai-chatbot) untuk pengalaman omnichannel.
- Gunakan [BYOK](/byok) untuk memilih provider suara/AI Anda sendiri.
- Jelajahi endpoint di [API Reference](/api).

---