Volara Docs

Tema

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.

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.

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 ​