Integrasi Nata ke web self-hosted

1. Dua jalur, pilih satu

Boleh dua-duanya: widget untuk pembeli di halaman toko, API untuk tim CS di dashboard internal.

2. Kunci API

Buka api.nyataka.com → Kunci lalu tekan Buat kunci. Kunci hanya ditampilkan sekali; di server kami yang tersimpan cuma hash-nya, jadi simpan di tempat aman waktu itu juga.

Formatnya:

nata_whk_<key_id>.<rahasia>

key_id adalah penanda publik (boleh kamu tulis di tiket dukungan); bagian rahasianya yang tidak boleh keluar dari server. Kirim di setiap permintaan:

Authorization: Bearer nata_whk_<key_id>.<rahasia>

Jangan tertukar dengan kunci widget

Widget resmi memakai kunci publik nata_pub_… yang boleh ditempel di HTML dan hanya bisa memanggil widget. API memakai nata_whk_… yang rahasia, hanya di server, dan memotong kredit API. Kunci widget tidak bisa memanggil /webhook/nata, dan kunci API tidak boleh dipakai di script widget.

Ganti kunci

Tekan Ganti kunci di halaman yang sama. Kunci lama langsung mati — tidak ada masa transisi — jadi perbarui environment variable di servermu segera setelah mengganti. Kalau kamu perlu memutar kunci tanpa downtime, hubungi kami: dua kunci aktif sekaligus belum didukung hari ini.

Kalau kunci bocor

1. Ganti kunci sekarang di halaman API (kunci lama mati seketika).
2. Perbarui NATA_API_KEY di server dan deploy ulang.
3. Cek pemakaian di halaman API (pesan hari ini) untuk melihat apakah ada pemakaian yang bukan dari kamu.
4. Email [email protected] dengan key_id (bukan kuncinya) supaya kami bisa menelusuri log.

3. Quickstart

Semua endpoint integrasi, sekilas:

Ganti kunci, atur URL callback, dan lihat meteran ada di halaman API-nya sendiri: api.nyataka.com → Kunci. Tidak ada endpoint untuk memutar kunci dari server — itu sengaja, supaya kunci tidak bisa diganti oleh kode yang mungkin sudah bocor.

curl

curl -X POST https://app.nyataka.com/webhook/nata \
  -H "Authorization: Bearer $NATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Stok gamis ukuran L masih ada?","thread_id":"cust-123"}'

JavaScript (Node 18+, fetch bawaan)

const res = await fetch("https://app.nyataka.com/webhook/nata", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.NATA_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Stok gamis L masih ada?", thread_id: "cust-123" }),
});

const data = await res.json();
if (!res.ok) {
  // data.error berisi kode mesin, lihat bagian 8
  throw new Error(data.error);
}
console.log(data.reply); // balasan siap tampil

Isi permintaan

Isi balasan (200)

{
  "ok": true,
  "reply": "Masih ada 4 pcs ukuran L.",
  "reply_html": "<p>Masih ada 4 pcs ukuran L.</p>",
  "reply_text": "Masih ada 4 pcs ukuran L.",
  "backend": "internal",
  "thread_id": "cust-123",
  "usage": { "messages_today": 12, "input_tokens": 812, "output_tokens": 233, "messages_this_month": 640 },
  "credits": 488
}

reply adalah Markdown dari Nata. reply_html sudah dirender jadi HTML, dan reply_text versi tanpa Markdown — pakai salah satu yang cocok dengan UI-mu. usage.input_tokens/output_tokens hanya untuk rekonsiliasi biaya di sisimu, bukan satuan yang kami tagih; messages_this_month dipakai untuk memantau ambang volume. backend adalah label internal kami: jangan dipakai untuk logika.

Meteran sendiri

curl https://app.nyataka.com/webhook/nata/usage \
  -H "Authorization: Bearer $NATA_API_KEY"

{
  "ok": true,
  "day": "2026-10-04",
  "resets_wib": "07:00",
  "credits": 488,
  "usage": { "messages": 12, "input_tokens": 8120, "output_tokens": 2330 }
}

4. Mode async dan callback

Permintaan berat (analisis, laporan panjang) bisa lebih lama dari kesabaran pengguna. Kirim mode: "async": kami menjawab 202 langsung dan mengirim hasilnya ke URL callback yang tersimpan di halaman API.

await fetch("https://app.nyataka.com/webhook/nata", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.NATA_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({ text: "Buat laporan penjualan minggu ini", thread_id: "ops-9", mode: "async" }),
});

Balasan callback adalah JSON yang sama dengan balasan sinkron (reply, reply_html, reply_text, thread_id), dikirim sebagai POST ke URL-mu.

Verifikasi tanda tangan callback

Setiap callback ditandatangani, jadi orang yang tahu URL callback-mu tetap tidak bisa menyuntikkan balasan palsu. Rahasianya adalah callback_signing_secret di halaman API (terbit bersama kunci dan tidak berubah saat kunci diganti; GET /api/web/webhook/status menampilkannya lagi kalau lupa), dikirim sebagai header:

Contoh verifikasi di Node (pakai body mentah, sebelum JSON.parse):

import crypto from "node:crypto";

// Signature = HMAC-SHA256(secret, `${X-Nyataka-Timestamp}.${rawBody}`)
export function verifyCallback(rawBody, headers, secret) {
  const timestamp = Number(headers["x-nyataka-timestamp"]);
  if (!Number.isFinite(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = "sha256=" + crypto.createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(headers["x-nyataka-signature"] || "");
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

• URL callback harus https publik. http://, localhost, IP privat, dan host .local/.internal ditolak dengan callback_url_must_be_https atau invalid_callback_url.
• Kami mencoba 2 kali dengan jeda 1,5 detik, lalu berhenti. Tidak ada antrean di sisi kami, jadi balas 2xx secepatnya — simpan ke antrean di sisimu kalau perlu.
• Redirect tidak diikuti, dan alamatnya dicek ulang waktu pengiriman (anti DNS rebinding).
• Kalau URL callback diisi, salinan balasan juga dikirim ke sana untuk permintaan sinkron. Kalau tidak mau, kosongkan URL callback.

5. Kirim katalog sendiri

Nata menjawab pembeli dari data tokomu. Dua cara mengisinya: biarkan Nata membaca sitemap situsmu dari tab Akun (Baca katalog dari website), atau dorong datanya dari backend — lebih akurat untuk stok dan harga yang berubah cepat.

curl -X PUT https://app.nyataka.com/webhook/nata/knowledge \
  -H "Authorization: Bearer $NATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "replace",
    "products": [
      { "id": "gm-1042", "title": "Gamis Lyla", "price_idr": 189000, "in_stock": true,
        "category": "gamis", "url": "https://tokomu.com/p/gamis-lyla",
        "description": "Bahan viscose, ukuran L dan XL." }
    ],
    "pages": [
      { "id": "retur", "title": "Kebijakan pengembalian", "url": "https://tokomu.com/retur",
        "body": "Retur 7 hari, barang belum dipakai." }
    ]
  }'

• mode: "replace" (default) mengganti seluruh isi kategori itu; "upsert" menambah/memperbarui saja.
• Maks 500 produk dan 500 halaman per kiriman. Kirim bertahap kalau katalogmu lebih besar.
• Balasan: { "ok": true, "counts": { "products": 128, "pages": 12 } } — jumlah yang tersimpan setelah kiriman.
• Body kosong (tidak ada produk maupun halaman yang lolos) → 400 nothing_to_store.

Yang didapat seller: Nata menjawab dari harga, stok, dan kebijakan asli tokomu, bukan menebak. Kalau katalog belum pernah dikirim, Nata akan bilang datanya belum ada — itu perilaku yang benar, bukan bug.

6. Widget dan origin yang diizinkan

Ambil snippetnya di app.nyataka.com → Integrasi → Widget di situs setelah mengisi nama toko dan daftar domain. Bentuknya:

<script src="https://app.nyataka.com/embed/nata-widget.js"
        data-key="nata_pub_KUNCI_PUBLIK_TOKO"
        data-mode="shopper" defer></script>

Dari JavaScript halamanmu: window.NataWidget.open(), .close(), .toggle(), dan .ask("teks").

Endpoint yang dipanggil widget

Kalau kamu mau men-debug network tab atau membangun UI sendiri untuk pembeli:

Keduanya memakai kunci publik dan hanya melayani origin yang kamu izinkan — bukan pengganti API server-to-server, dan tidak menerima kunci nata_whk_.

CORS dan daftar origin

Permintaan pembeli hanya dilayani kalau header Origin browser sama persis dengan salah satu baris di daftar Website yang boleh memasang widget. Tulis skema + host saja, tanpa path dan tanpa garis miring di akhir:

https://tokumu.com
https://www.tokumu.com

Origin yang tidak terdaftar mendapat 403 origin_not_allowed dan header CORS tidak dikirim — jadi di browser gejalanya sering muncul sebagai error CORS di console, bukan sebagai pesan error dari widget. Itu penyebab tersamar nomor satu; cek daftar origin dulu sebelum menuduh yang lain.

Batas widget

• Per IP: 30 pesan per 10 menit; per situs: 40 pesan per menit. Lewat batas → 429 slow_down.
• Kuota harian pembeli per situs (default 25, diatur di halaman widget). Habis → 429 store_daily_cap, dan pesannya menyarankan pembeli menghubungi kontak tokomu.
• Pesan pembeli dipotong di 800 karakter; lebih dari 1.600 karakter ditolak 413 message_too_long.
• Widget butuh paket yang mengizinkan integrasi web (Max). Akun tanpa itu → 403 widget_plan_required, dan widget tidak muncul.

6b. Copilot halaman (page agent)

Kalau halaman admin milikmu sendiri yang ingin dibantu Nata, kirim mode: "copilot" ke endpoint yang sama. Kamu mengirim apa yang terlihat di halaman; Nata membalas kalimat + daftar aksi yang boleh dijalankan halaman itu. Nata tidak punya browser di sini — halamanmu yang mengeksekusi.

POST /webhook/nata
Authorization: Bearer <API_KEY>

{
  "mode": "copilot",
  "session_id": "percakapan-1",
  "message": "Ubah nama toko jadi Rumaisha Hijab",
  "access_mode": "approval",
  "page": {
    "url": "https://admin.tokomu.com/pengaturan",
    "title": "Pengaturan Toko",
    "summary": "Form pengaturan. Nama toko: Lama.",
    "fields": [{ "name": "store_name", "label": "Nama toko", "value": "Lama" }],
    "elements": [{ "ref": "r1", "role": "button", "name": "Simpan" }]
  }
}

Balasannya memuat reply, actions, requires_approval, dan session_id. Aksi yang diizinkan hanya set_field (nama field harus ada di page.fields) dan click (ref harus ada di page.elements). Server membuang aksi ke Simpan/Publikasi/Hapus/Bayar/Kirim; halaman tetap wajib menampilkan diff dan meminta persetujuan bila requires_approval.

access_mode: read_only (tanpa aksi), approval (default, aksi menunggu persetujuan), full_access (aksi boleh langsung dijalankan). Satu panggilan copilot = satu kredit API. Panduan lengkap dan contoh page agent ada di docs/copilot-api.md di repo; kontrak ini berlaku untuk semua customer API, bukan hanya satu toko.

Kalau halamanmu punya banyak route, deklarasikan manifest sekali. Contoh nyata Rumaisha: 20 route, 86 field, 11 flow; pack-nya ada di docs/rumaisha-page-agent-pack.json. Manifest menyimpan struktur, bukan nilai field, password, atau data pembeli.

7. Batas dan kuota API

Harga

Ringkasnya ada di Biaya & paket di atas: API adalah paket terpisah, prabayar Rp 199 per pesan, tanpa biaya bulanan.

Harga ini keputusan pemilik 2026-10-03 (docs product-strategy-tiers-api §4). Penagihan masih manual lewat tim: belum ada top up sendiri di app dan belum ada invoice otomatis. Untuk menambah kredit, email [email protected] dengan key_id-mu.

8. Error

Semua error berbentuk JSON { "error": "kode_mesin" }. error adalah kontrak yang stabil dan tidak berubah bahasa. Kalau ada teks untuk manusia, ia datang dua kali: message (Indonesia) dan message_en (Inggris). Kadang ada juga credits atau required. Kode di bawah ini yang benar-benar dikeluarkan hari ini.

API webhook

Kunci/callback (dari halaman API)

Katalog

Widget

9. Kalau macet