Connect Nata to your own site

1. Two paths, pick one

You can use both: the widget for shoppers on your store pages, the API for your support team's internal dashboard.

2. API keys

Open api.nyataka.com → Kunci and click Buat kunci. The key is shown once. Our server keeps only its hash, so save it somewhere safe right then.

The format:

nata_whk_<key_id>.<rahasia>

key_id is the public identifier, safe to quote in a support ticket. The secret half must never leave your server. Send both on every request:

Authorization: Bearer nata_whk_<key_id>.<rahasia>

Don't confuse it with the widget key

The official widget uses a public key, nata_pub_…, which may sit in HTML and can only call the widget. The API uses nata_whk_…, which is secret, server-side only, and spends API credits. A widget key cannot call /webhook/nata, and an API key must never be used in a widget script.

Rotate a key

Click Ganti kunci on the same page. The old key dies immediately, with no transition period, so update the environment variable on your server as soon as you rotate. Need to rotate with no downtime? Ask us: two active keys at once are not supported today.

If a key leaks

1. Rotate the key now on the API page. The old key dies at once.
2. Update NATA_API_KEY on your server and redeploy.
3. Check usage on the API page (messages today) for traffic that is not yours.
4. Email [email protected] with the key_id, not the key, so we can trace the logs.

3. Quickstart

Every integration endpoint, at a glance:

Rotate keys, set the callback URL, and read the meter on the API surface itself: api.nyataka.com → Kunci. There is no endpoint to rotate a key from your server. That is deliberate: leaked code must not be able to replace the key.

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+, built-in fetch)

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 holds the machine code; see section 8
  throw new Error(data.error);
}
console.log(data.reply); // the reply is ready to display

Request body

Response body (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 is Nata's Markdown. reply_html is rendered HTML, and reply_text is the same text without Markdown. Pick whichever fits your UI. usage.input_tokens/output_tokens are for your own cost reconciliation, not a unit we bill. messages_this_month tracks the volume threshold. backend is an internal label: do not build logic on it.

Your own meter

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. Async mode and callbacks

A heavy request, such as an analysis or a long report, can outlast a waiting user. Send mode: "async": we answer 202 right away and POST the result to the callback URL saved on the API page.

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" }),
});

The callback body is the same JSON as a synchronous reply (reply, reply_html, reply_text, thread_id), sent as a POST to your URL.

Verify the callback signature

Every callback is signed, so knowing your callback URL is not enough to inject a fake reply. The secret is callback_signing_secret on the API page. It is issued with the key and does not change when you rotate it; GET /api/web/webhook/status shows it again if you lose it. We send two headers:

Verification in Node. Use the raw body, before 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);
}

• The callback URL must be public https. http://, localhost, private IPs, and .local/.internal hosts get callback_url_must_be_https or invalid_callback_url.
• We try 2 times, 1.5 seconds apart, then stop. We keep no queue on our side, so answer 2xx fast. Queue on your side if you need to.
• We do not follow redirects, and we re-check the address at delivery time to block DNS rebinding.
• If you set a callback URL, a copy of the reply also goes there for synchronous requests. Leave the URL empty if you do not want that.

5. Push your own catalog

Nata answers shoppers from your store data. Two ways to fill it: let Nata read your site sitemap from the Akun tab (Baca katalog dari website), or push the data from your backend. Pushing is more accurate for stock and prices that change fast.

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) swaps the whole category. "upsert" adds or updates only.
• At most 500 products and 500 pages per request. Send in batches if your catalog is bigger.
• { "ok": true, "counts": { "products": 128, "pages": 12 } } — what is stored after the push.
• An empty body, where no product or page passes validation, returns 400 nothing_to_store.

What you get: Nata answers from your real prices, stock, and policies instead of guessing. If you never pushed a catalog, Nata says the data is missing. That is correct behaviour, not a bug.

6. The widget and allowed origins

Get the snippet at app.nyataka.com → Integrasi → Widget di situs after you fill in the store name and domain list. It looks like this:

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

From your page's JavaScript: window.NataWidget.open(), .close(), .toggle(), and .ask("text").

Endpoints the widget calls

Use these to debug the network tab or build your own shopper UI:

Both take the public key and serve only the origins you allow. They are not a replacement for the server-to-server API, and they reject nata_whk_ keys.

CORS and the origin list

A shopper request is served only when the browser's Origin header matches a row in Website yang boleh memasang widget exactly. Write the scheme and host only, with no path and no trailing slash:

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

An unlisted origin gets 403 origin_not_allowed and no CORS header. In a browser that usually shows up as a CORS error in the console, not as a widget error message. It is the most common red herring, so check the origin list first.

Widget limits

• Per IP: 30 messages per 10 minutes. Per site: 40 messages per minute. Over the limit: 429 slow_down.
• A daily shopper quota per site (default 25, set on the widget page). When it runs out: 429 store_daily_cap, and the message tells the shopper to contact your store.
• Shopper messages are truncated at 800 characters. Over 1,600 characters is rejected with 413 message_too_long.
• The widget needs a plan that includes web integration (Max). Without it: 403 widget_plan_required, and the widget does not appear.

6b. Page copilot (page agent)

If the admin page you want help with is your own, send mode: "copilot" to the same endpoint. You send what is visible on the page; Nata replies with words plus a list of actions the page may run. Nata has no browser here — your page executes them.

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" }]
  }
}

The response carries reply, actions, requires_approval, and session_id. The only allowed actions are set_field (the name must exist in page.fields) and click (the ref must exist in page.elements). The server drops Save/Publish/Delete/Pay/Send actions; the page must still show a diff and ask for approval when requires_approval is true.

access_mode: read_only (no actions), approval (default; actions wait for approval), full_access (actions may run immediately). One copilot call costs one API credit. The full guide and a page-agent example live in docs/copilot-api.md; this contract is for every API customer, not one store.

If your page has many routes, declare the manifest once. Real Rumaisha example: 20 routes, 86 fields, 11 flows; the pack is at docs/rumaisha-page-agent-pack.json. A manifest stores structure, never field values, passwords, or buyer data.

7. API limits and quota

Pricing

In short, from Pricing and packages above: the API is a separate package, prepaid at Rp 199 per message, with no monthly fee.

These prices are an owner decision from 2026-10-03 (docs product-strategy-tiers-api §4). Billing is still manual through the team: no self-serve top-up in the app and no automatic invoice. To add credits, email [email protected] with your key_id.

8. Errors

Every error is JSON: { "error": "machine_code" }. error is the stable contract and never changes language. When there is human text it arrives twice: message in Indonesian and message_en in English. Some responses also carry credits or required. These are the codes the API emits today.

API webhook

Keys and callbacks (from the API page)

Catalog

Widget

9. Troubleshooting